Data API
Hol deine Mitglieder, ihre Aktivität und ihre Guthaben in dein CRM, dein Data Warehouse oder dein BI-Tool.
Lesender HTTP-Zugriff auf die Mitglieder deiner eigenen Community, ihre Aktivität, ihre Guthaben und ihre Objekte, authentifiziert mit einem Schlüssel. Das Fan-Erlebnis berührt er nie.
Umfang und erste Anwendungen
Die drei Dinge, die Partner zuerst damit gebaut haben:
- Ein CRM-Segment. Mitglieder und ihre Guthaben, verknüpft mit der E-Mail-Liste, damit eine Kampagne an Fans über Level zehn gehen kann statt an alle.
- Eine Tabelle im Data Warehouse. Ein nächtlicher Abruf von Mitgliedern und Aktivität an denselben Ort, an dem die Daten aus deinem Shopify-Shop schon landen, damit sich Engagement in der App und Umsatz in einer einzigen Abfrage betrachten lassen.
- Ein Dashboard, das deine Geschäftsführung schon liest. Die wichtigsten Gesamtzahlen im BI-Tool, das alle anderen Zahlen zeigt, statt noch eines Logins für noch ein Panel.
Einen Schlüssel bekommen
Frag deine Ansprechperson bei FanBase nach einem Schlüssel.
Er wird ein einziges Mal angezeigt, bei der Erstellung, und danach nie wieder. Leg ihn direkt in einem Passwortmanager oder in deinem Secret-Store ab. Geht er verloren, ist die Lösung ein neuer Schlüssel.
Ein Schlüssel kann ein Ablaufdatum haben. Bitte darum bei allem, was kurzlebig ist, etwa der Integration eines Dienstleisters oder einer einmaligen Migration. Ein Schlüssel ohne Ablaufdatum ist ein Schlüssel, der die Person überdauert, die ihn angefordert hat.
Sag uns, wann ein Schlüssel nicht mehr funktionieren soll, und wir widerrufen ihn.
Das ist eine Server-zu-Server-API. Der Schlüssel darf nie in einen Browser, eine mobile App, einen Frontend-Build oder irgendetwas anderes gelangen, das ein Fan lesen kann. Der Schlüssel liest deine gesamte Community, und ein Fan, der ihn findet, kann das auch. Leg ihn auf einem Server ab, in einem geplanten Job oder im Konnektor deines Data Warehouse.
Wenn das, was du baust, für Fans gedacht ist, nutze stattdessen das SDK. Es authentifiziert sich als der Fan und liefert nur die Daten dieses Fans. Siehe die API-Referenz des FanBase SDK.
Die API aufrufen
Sende den Schlüssel im Header x-api-key. Die Basis-URL ist https://api.gamerbase.gg.
curl -H "x-api-key: $FANBASE_API_KEY" \
"https://api.gamerbase.gg/v1/data/members?limit=100&offset=0"Kein OAuth-Ablauf und keine Token-Erneuerung.
Ressourcen, die du lesen kannst
| Ressource | Wofür sie da ist |
|---|---|
| Mitglieder | Eine Zeile pro Fan in deiner Community. Der Join-Schlüssel für alles andere hier und die Tabelle, nach der dein CRM segmentiert. |
| Löschungen von Mitgliedern | Fans, die ihr Konto gelöscht haben. Der einzige Weg, eine Löschung auch in deinen eigenen Systemen umzusetzen, denn ein gelöschter Fan taucht in den Mitgliedern und im Mitglieder-Export nicht mehr auf, und nichts weist auf sein Fehlen hin. |
| Aktivität | Was Fans getan haben und wann. Das Ereignisprotokoll hinter jeder Zahl auf dem Dashboard und die Quelle für Retention- und Kohortenanalysen. |
| Ressourcenguthaben | Ein Guthaben pro Fan und Ressource, also XP und jede ausgebbare Währung, die deine Community angelegt hat. Danach segmentierst du, wenn du deine besten tausend Fans willst und nicht alle. |
| Objekte im Besitz | Welche Sammelobjekte und Inventarobjekte jeder Fan besitzt. Nützlich, um zu prüfen, wer das Objekt tatsächlich hat, um das herum eine Kampagne gebaut wurde. |
| Lootbox-Öffnungen | Jede Öffnung und was dabei herauskam. Für den Abgleich und für die Antwort an den Fan, der sagt, die Chancen stimmten nicht. |
| Statistik-Gesamtzahlen | Die wichtigsten Zähler für die gesamte Community, darunter totalMembers und totalQuestsCompleted. Die vollständige Liste steht in der Referenz. Der günstige Aufruf für eine Statusübersicht, die keine Zeilen pro Fan braucht. |
| Quest-Katalog | Deine veröffentlichten Quests. Öffentlich und der einzige Teil, der gar keinen Schlüssel braucht. |
Paginierung und Synchronisierung
Jede Listenantwort hat dieselbe Form: data enthält die Zeilen, total gibt an, wie viele Zeilen insgesamt passen, und offset sagt, wo die Seite beginnt, die du gerade vor dir hast. Du blätterst mit limit und offset. Das aktuelle Maximum für limit steht in der Referenz, die aus der API generiert wird und den Wert liefert, gegen den du programmieren solltest.
Nutze updatedSince. Übergib einen Zeitstempel, und du bekommst nur Zeilen zurück, die sich danach geändert haben. Dein erster Lauf holt die gesamte Community. Jeder weitere Lauf holt die Handvoll Zeilen, die sich seit dem letzten geändert haben.
Zwei Dinge müssen stimmen, wenn du diese Schleife baust.
Speichere den Zeitpunkt, zu dem der Lauf begonnen hat. Während du blätterst, können Zeilen geschrieben werden, und ein Cursor, der auf die zuletzt gesehene Zeile gesetzt ist, überspringt sie. Orientiere dich am Beginn des Laufs, lass den nächsten Lauf um ein paar Minuten überlappen, und eine Zeile, die mitten in der Synchronisierung geschrieben wurde, wird trotzdem erfasst. Schreib deine Zeilen so, dass es nicht schadet, dieselbe zweimal zu sehen, dann kostet dich die Überlappung nichts.
Lies die Löschungen von Mitgliedern im selben Takt wie die Mitglieder. Ein gelöschter Fan taucht in den Mitgliedern nicht mehr auf, und eine inkrementelle Synchronisierung, die allein auf updatedSince beruht, kann ein Fehlen nicht bemerken. Sie behält die veraltete Zeile dauerhaft in deinem CRM und schickt weiter E-Mails an jemanden, der vergessen werden wollte. Löschungen sind genau deshalb eine eigene Ressource, damit du sie abrufen und danach handeln kannst.
Rate-Limits
Das Limit gilt pro Minute und pro Schlüssel und ist so hoch angesetzt, dass eine gut gebaute inkrementelle Synchronisierung ihm nie nahekommt. Jede Antwort enthält X-RateLimit-*-Header mit den aktuellen Zahlen, und diese Header sind maßgeblich. Ein Client, der sie liest und langsamer wird, wenn der verbleibende Wert niedrig wird, bleibt innerhalb des Limits, ohne dass du etwas einstellen musst.
Wenn du an das Limit stößt, ist die Ursache fast immer ein vollständiger erneuter Download nach Zeitplan.
Die interaktive Referenz
Jeder Endpunkt, jeder Parameter und jede Antwortform steht unter api.gamerbase.gg/api, und du kannst sie von der Seite aus mit deinem Schlüssel aufrufen. Sie wird aus der API generiert und zeigt deshalb die aktuelle Form und keine Kopie davon. Verweise deine Entwickler und deinen Coding-Agenten zuerst dorthin.
Webhooks
In PrüfungHeute fragst du in regelmäßigen Abständen ab. Webhooks würden das umkehren: Du würdest eine URL registrieren, und die Plattform würde dir eine Anfrage schicken, sobald etwas passiert. So könnte eine abgeschlossene Quest dein CRM in Sekunden erreichen statt bei der nächsten Synchronisierung.
Das wird diskutiert und ist noch nicht eingeplant. Wenn deine Kampagne von einer Reaktion in Echtzeit abhängt, sag es deiner Ansprechperson bei FanBase: Erst wenn wir wissen, dass ein Partner es braucht, bekommt es einen Termin.