Data API
Porta i tuoi membri, la loro attività e i loro saldi nel tuo CRM, nel tuo data warehouse o nel tuo strumento di BI.
Accesso HTTP in sola lettura ai membri, all'attività, ai saldi e agli oggetti posseduti della tua community, autenticato con una chiave. Non tocca mai l'esperienza dei fan.
Ambito e primi utilizzi
Le tre cose che i partner hanno costruito per prime con questa API:
- Un segmento nel CRM. I membri e i loro saldi uniti alla lista email, così una campagna può andare ai fan sopra il livello dieci invece che a tutti.
- Una tabella nel data warehouse. Un'estrazione notturna di membri e attività nello stesso posto in cui arrivano già i dati del negozio, così il coinvolgimento nell'app e i ricavi si possono guardare in un'unica query.
- Una dashboard che la tua dirigenza legge già. I totali principali nello strumento di BI che mostra tutti gli altri numeri, invece di un altro accesso a un altro pannello.
Ottenere una chiave
Chiedi una chiave al tuo referente FanBase.
Viene mostrata una sola volta, alla creazione, e mai più. Mettila subito in un gestore di password o nel tuo archivio di segreti. Se va persa, la soluzione è una nuova chiave.
Una chiave può avere una scadenza. Chiedila per tutto ciò che ha vita breve, come l'integrazione di un consulente esterno o una migrazione una tantum. Una chiave senza scadenza è una chiave che sopravvive alla persona che l'ha chiesta.
Dicci quando una chiave deve smettere di funzionare e la revochiamo.
Questa è un'API da server a server. La chiave non deve mai finire in un browser, in un'app mobile, in una build del front end o in qualsiasi altra cosa che un fan possa leggere. La chiave legge tutta la tua community, e un fan che la trova può leggerla anche lui. Mettila su un server, in un job pianificato o nel connettore del tuo data warehouse.
Se quello che stai costruendo è rivolto ai fan, usa invece l'SDK. Si autentica come il fan e restituisce solo i dati di quel fan. Vedi la documentazione di riferimento dell'API di FanBase SDK.
Chiamarla
Invia la chiave in un header x-api-key. L'URL di base è https://api.gamerbase.gg.
curl -H "x-api-key: $FANBASE_API_KEY" \
"https://api.gamerbase.gg/v1/data/members?limit=100&offset=0"Niente flusso OAuth e niente rinnovo dei token.
Risorse che puoi leggere
| Risorsa | A cosa serve |
|---|---|
| Membri | Una riga per ogni fan della tua community. La chiave di join per tutto il resto qui, e la tabella su cui il tuo CRM crea i segmenti. |
| Eliminazioni di membri | I fan che hanno eliminato il proprio account. L'unico modo per rispettare un'eliminazione anche nei tuoi sistemi, perché un fan eliminato smette di comparire tra i membri, e nell'esportazione dei membri, senza nulla che ne segnali l'assenza. |
| Attività | Cosa hanno fatto i fan e quando. Il registro eventi che sta sotto ogni numero della dashboard, e la fonte per le analisi di fidelizzazione e di coorte. |
| Saldi delle risorse | Un saldo per fan e per risorsa, quindi gli XP e ogni valuta spendibile creata dalla tua community. È il dato su cui segmenti quando vuoi i tuoi primi mille fan e non tutti. |
| Oggetti posseduti | Quali oggetti da collezione e oggetti dell'inventario possiede ogni fan. Utile per verificare chi possiede davvero l'oggetto attorno a cui è stata costruita una campagna. |
| Aperture di loot box | Ogni apertura e cosa ne è uscito. Per la riconciliazione, e per rispondere al fan che dice che le probabilità sono sbagliate. |
| Totali statistici | I conteggi principali di tutta la community, tra cui totalMembers e totalQuestsCompleted. L'elenco completo è nella documentazione di riferimento. La chiamata leggera per un tabellone di stato che non ha bisogno di righe per fan. |
| Catalogo delle missioni | Le tue missioni pubblicate. Pubblico, ed è l'unica parte che non richiede alcuna chiave. |
Paginazione e sincronizzazione
Ogni risposta a elenco ha la stessa forma: data contiene le righe, total indica quante righe corrispondono in totale, e offset dice dove inizia la pagina che hai in mano. Scorri le pagine con limit e offset. Il massimo attuale per limit è nella documentazione di riferimento, che è generata dall'API ed è il valore su cui basare il codice.
Usa updatedSince. Passa un timestamp e ricevi solo le righe modificate dopo quel momento. La prima esecuzione scarica tutta la community. Ogni esecuzione successiva scarica le poche righe che sono cambiate dall'ultima.
Due cose da fare bene quando costruisci questo ciclo.
Salva l'ora in cui è iniziata l'esecuzione. Le righe possono essere scritte mentre scorri le pagine, quindi un cursore impostato sull'ultima riga vista le salta. Ancorati all'inizio dell'esecuzione, sovrapponi l'esecuzione successiva di qualche minuto, e una riga scritta a metà sincronizzazione viene comunque raccolta. Scrivi le tue righe in modo che vedere la stessa due volte sia innocuo, e la sovrapposizione non ti costa nulla.
Leggi le eliminazioni di membri con la stessa frequenza dei membri. Un fan eliminato smette di comparire tra i membri, e una sincronizzazione incrementale basata solo su updatedSince non ha modo di accorgersi di un'assenza. Tiene la riga obsoleta nel tuo CRM per sempre, e continua a mandare email a qualcuno che ha chiesto di essere dimenticato. Le eliminazioni sono una risorsa separata proprio perché tu possa scaricarle e agire di conseguenza.
Limiti di frequenza
Il limite è al minuto e per chiave, ed è abbastanza alto perché una sincronizzazione incrementale ben costruita non ci si avvicini mai. Ogni risposta contiene header X-RateLimit-* con i numeri in tempo reale, e sono quegli header a fare fede. Un client che li legge e rallenta quando il conteggio residuo si abbassa resta dentro il limite senza alcuna regolazione da parte tua.
Se raggiungi il limite, la causa è quasi sempre un nuovo download completo eseguito a intervalli pianificati.
La documentazione di riferimento interattiva
Ogni endpoint, ogni parametro e ogni forma di risposta si trova su api.gamerbase.gg/api, e puoi chiamarli dalla pagina con la tua chiave. È generata dall'API, quindi è la forma attuale e non una sua copia. Indirizza lì per prima cosa i tuoi sviluppatori e il tuo agente di programmazione.
Webhook
In valutazioneOggi interroghi tu l'API a intervalli. I webhook invertirebbero il meccanismo: registreresti un URL e la piattaforma ti invierebbe una richiesta quando succede qualcosa, così il completamento di una missione potrebbe arrivare al tuo CRM in pochi secondi invece che alla sincronizzazione successiva.
È in discussione, non in programma. Se la tua campagna dipende da una reazione in tempo reale, dillo al tuo referente FanBase: sapere che un partner ne ha bisogno è ciò che gli fa avere una data.