Data API
Haal je leden, hun activiteit en hun saldo's naar je CRM, je datawarehouse of je BI-tool.
HTTP-toegang met alleen leesrechten tot de leden, de activiteit, de saldo's en het itembezit van je eigen community, geauthenticeerd met een sleutel. De fanervaring wordt er nooit door geraakt.
Reikwijdte en eerste toepassingen
De drie dingen die partners er als eerste mee hebben gebouwd:
- Een CRM-segment. Leden en hun saldo's gekoppeld aan de e-maillijst, zodat een campagne naar fans boven level tien kan gaan in plaats van naar iedereen.
- Een tabel in het datawarehouse. Elke nacht worden leden en activiteit opgehaald naar dezelfde plek waar de webshopgegevens al binnenkomen, zodat engagement in de app en omzet in één query te bekijken zijn.
- Een dashboard dat je directie al leest. De belangrijkste totalen in de BI-tool die alle andere cijfers toont, in plaats van nog een login voor nog een paneel.
Een sleutel krijgen
Vraag je contactpersoon bij FanBase om een sleutel.
De sleutel wordt één keer getoond, bij het aanmaken, en daarna nooit meer. Zet hem meteen in een wachtwoordmanager of in je secret store. Als hij kwijt is, is de oplossing een nieuwe sleutel.
Een sleutel kan een vervaldatum hebben. Vraag daarom bij alles wat tijdelijk is, zoals de integratie van een externe ontwikkelaar of een eenmalige migratie. Een sleutel zonder vervaldatum blijft langer bestaan dan de persoon die erom vroeg.
Laat ons weten wanneer een sleutel moet stoppen met werken, dan trekken wij hem in.
Dit is een API van server naar server. De sleutel mag nooit in een browser, een mobiele app, een front-endbuild of iets anders terechtkomen dat een fan kan lezen. De sleutel leest je hele community, en een fan die hem vindt, kan die ook lezen. Zet hem op een server, in een geplande taak of in de connector van je datawarehouse.
Als wat je bouwt voor fans bedoeld is, gebruik dan de SDK. Die authenticeert als de fan en geeft alleen de gegevens van die fan terug. Zie de API-referentie van de FanBase SDK.
De API aanroepen
Stuur de sleutel mee in een header x-api-key. De basis-URL is https://api.gamerbase.gg.
curl -H "x-api-key: $FANBASE_API_KEY" \
"https://api.gamerbase.gg/v1/data/members?limit=100&offset=0"Geen OAuth-stappen en geen tokens om te vernieuwen.
Resources die je kunt lezen
| Resource | Waar die voor dient |
|---|---|
| Leden | Eén rij per fan in je community. De koppelsleutel voor al het andere hier, en de tabel waarop je CRM segmenteert. |
| Verwijderde leden | Fans die hun account hebben verwijderd. De enige manier om een verwijdering ook in je eigen systemen door te voeren, want een verwijderde fan verschijnt niet meer in de leden en ook niet in de ledenexport, zonder dat iets die afwezigheid aangeeft. |
| Activiteit | Wat fans hebben gedaan en wanneer. Het gebeurtenissenlogboek achter elk cijfer op het dashboard, en de bron voor retentie- en cohortanalyses. |
| Resourcesaldo's | Eén saldo per fan per resource, dus XP en elke uitgeefbare valuta die je community heeft aangemaakt. Hierop segmenteer je als je je beste duizend fans wilt in plaats van allemaal. |
| Itembezit | Welke verzamelobjecten en inventarisitems elke fan bezit. Handig om te controleren wie het item waar een campagne omheen is gebouwd echt in bezit heeft. |
| Geopende lootboxen | Elke opening en wat eruit kwam. Voor de afstemming, en om de fan te antwoorden die zegt dat de winkansen niet kloppen. |
| Statistiektotalen | De belangrijkste tellingen voor de hele community, waaronder totalMembers en totalQuestsCompleted. De volledige set staat in de referentie. De goedkope aanroep voor een statusbord dat geen rijen per fan nodig heeft. |
| Questcatalogus | Je gepubliceerde quests. Openbaar, en het enige onderdeel hiervan waarvoor helemaal geen sleutel nodig is. |
Pagineren en synchroniseren
Elk lijstantwoord heeft dezelfde vorm: data bevat de rijen, total geeft aan hoeveel rijen er in totaal overeenkomen, en offset zegt waar de pagina die je in handen hebt begint. Je pagineert met limit en offset. Het huidige maximum voor limit staat in de referentie, die uit de API wordt gegenereerd en de waarde geeft waarop je moet programmeren.
Gebruik updatedSince. Geef een tijdstempel mee en je krijgt alleen de rijen terug die daarna zijn gewijzigd. Je eerste run haalt de hele community op. Elke run daarna haalt het handjevol rijen op dat sinds de vorige is veranderd.
Twee dingen die goed moeten zitten als je die lus bouwt.
Sla het tijdstip op waarop de run begon. Tijdens het pagineren kunnen er rijen worden geschreven, dus een cursor die op de laatst geziene rij staat, slaat ze over. Neem het begin van de run als ankerpunt, laat de volgende run een paar minuten overlappen, en een rij die halverwege de synchronisatie is geschreven, wordt toch meegenomen. Schrijf je rijen zo weg dat het geen kwaad kan om dezelfde rij twee keer te zien, dan kost de overlap je niets.
Lees verwijderde leden volgens hetzelfde schema als leden. Een verwijderde fan verschijnt niet meer in de leden, en een incrementele synchronisatie die alleen op updatedSince is gebouwd, kan een afwezigheid op geen enkele manier opmerken. Die houdt de verouderde rij voorgoed in je CRM en blijft e-mails sturen naar iemand die heeft gevraagd om vergeten te worden. Verwijderingen zijn juist een aparte resource zodat je ze kunt ophalen en ernaar kunt handelen.
Verzoeklimieten
De limiet geldt per minuut en per sleutel, en ligt zo hoog dat een goed gebouwde incrementele synchronisatie er nooit bij in de buurt komt. Elk antwoord bevat X-RateLimit-* headers met de actuele cijfers, en die headers zijn leidend. Een client die ze leest en gas terugneemt als het resterende aantal laag wordt, blijft binnen de limiet zonder dat jij iets hoeft af te stellen.
Als je tegen de limiet aanloopt, is de oorzaak bijna altijd een geplande volledige download die steeds opnieuw wordt uitgevoerd.
De interactieve referentie
Elk endpoint, elke parameter en elke antwoordvorm staat op api.gamerbase.gg/api, en je kunt ze vanaf de pagina aanroepen met je sleutel. De referentie wordt uit de API gegenereerd, dus het is de actuele vorm en geen kopie ervan. Stuur je ontwikkelaars en je codeeragent daar eerst naartoe.
Webhooks
In onderzoekOp dit moment vraag je de API zelf met vaste tussenpozen op. Webhooks zouden dat omdraaien: je registreert een URL en het platform stuurt je een bericht wanneer er iets gebeurt, zodat een voltooide quest je CRM binnen enkele seconden kan bereiken in plaats van bij de volgende synchronisatie.
Dit wordt besproken, maar is nog niet ingepland. Als je campagne afhangt van een realtime reactie, vertel het dan aan je contactpersoon bij FanBase: weten dat een partner het nodig heeft, zorgt ervoor dat het een datum krijgt.