fooz.js Integration
So bindest du Achievements & XP in deine eigene Website oder App ein.

fooz ist ein leichtgewichtiges Gamification-Overlay für deine Website: Du definierst Achievements im Dashboard, wir liefern dir ein Steam-artiges Toast-UI, das du mit einer einfachen API auslösen kannst.

1. Projekt & API-Key anlegen

1. Registriere dich auf fooz.de und logge dich ein.
2. Lege im Dashboard ein neues Projekt an.
3. Du erhältst einen API-Key und ein fertiges Integrations-Snippet.

2. fooz.js einbinden

Füge auf deiner Seite (z. B. im <head> oder vor dem schließenden </body>) den Script-Tag hinzu: 

<script src="https://fooz.de/fooz.js"></script>
<script>
  fooz.init({
    apiKey: '<DEIN_API_KEY_AUS_DEM_DASHBOARD>',
    userId: '<USER_ID_AUS_DEINEM_SYSTEM>',
    apiEndpoint: 'https://fooz.de/api/unlock.php',
    theme: {
      position: 'top-right', // top-right | top-left | bottom-right | bottom-left
      variant: 'dark',       // dark | light
      duration: 4000         // Anzeigedauer in ms
    }
  });
</script>

userId ist eine ID aus deinem System (z.B. Datenbank-ID, Hash, UUID). fooz speichert sie so, wie du sie übergibst – kein Login, keine Cookies, kein Tracking.

3. Achievements definieren

In deinem Projekt findest du die Seite „Achievements & Theme verwalten“. Dort kannst du:

  • Achievement-Key definieren (z. B. first_login)
  • Titel & Beschreibung festlegen
  • Icon als Bild-URL oder als Emoji (🔥, 🧠, …)
  • XP-Punkte vergeben

Der Key ist deine öffentliche API: du triggert das Achievement später mit fooz.unlock('DEIN_KEY').

4. Achievements im Code freischalten

Sobald ein Spieler etwas erreicht hat (z.B. Level-Up, Kauf abgeschlossen, erster Login), rufst du in deinem Frontend: 

// Beispiel: Achievement "first_login"
fooz.unlock('first_login');

fooz schickt dann einen POST-Request an https://fooz.de/api/unlock.php: 

POST /api/unlock.php
Content-Type: application/json

{
  "apiKey": "DEIN_API_KEY",
  "userId": "12345",
  "achievementId": "first_login"
}

Typische Antworten:

// Neues Achievement freigeschaltet
{
  "status": "unlocked",
  "achievement": {
    "key": "first_login",
    "title": "First Login",
    "description": "Du hast dich zum ersten Mal eingeloggt.",
    "icon": "🔥",
    "xp_points": 50
  }
}

// Bereits vorher freigeschaltet
{
  "status": "already_unlocked"
}

// Fehlerfälle (z.B. falscher API-Key oder Achievement)
{
  "error": "Invalid apiKey."
}

Pro Kombination aus project_id, userId und achievementId wird nur genau ein Eintrag in unlocked_achievements angelegt.

5. Toast-Design & Theme

Auf der Projektseite kannst du unter „Toast-Theme & Vorschau“ das Aussehen deiner Overlays konfigurieren:

  • Position: oben/unten, links/rechts
  • Stil: dunkel oder hell
  • Anzeigedauer: wie lange der Toast bleibt

Diese Theme-Einstellungen werden pro Projekt gespeichert und automatisch im Integrations-Snippet im Dashboard berücksichtigt.

6. DSGVO & Datenschutz

fooz speichert nur:

  • die von dir definierte userId (z. B. eine anonyme UUID)
  • den Achievement-Key
  • die Zeitpunkte der Freischaltungen (unlocked_at)

Es werden keine Cookies gesetzt, kein Tracking über Domains hinweg und keine personenbezogenen Daten, außer du kodierst sie selbst in die userId. Für DSGVO-Konformität solltest du deine userId daher als pseudonyme ID anlegen (z. B. Hash, UUID).

7. Fehlersuche & Logging

Im Backend siehst du auf jeder Projektseite:

  • Letzte Unlocks (Log der letzten 50 Einträge)
  • die komplette Liste aller Achievements pro Projekt
  • eine Test-Funktion, mit der du die Toasts direkt aus dem Backend auslösen kannst

Für lokale Tests kannst du auch direkt HTTP-Requests gegen /api/unlock.php schicken (z. B. mit Postman, curl).