Data API
Récupérez vos membres, leur activité et leurs soldes dans votre CRM, votre entrepôt de données ou votre outil de BI.
Un accès HTTP en lecture seule aux membres, à l'activité, aux soldes et aux objets détenus de votre propre communauté, authentifié par une clé. Il ne touche jamais à l'expérience des fans.
Périmètre et premiers usages
Les trois choses que les partenaires ont construites en premier avec cette API :
- Un segment de CRM. Les membres et leurs soldes rattachés à la liste e-mail, pour qu'une campagne parte vers les fans au-dessus du niveau dix plutôt que vers tout le monde.
- Une table d'entrepôt de données. Une récupération nocturne des membres et de l'activité au même endroit que les données de la boutique, pour que l'engagement dans l'application et le chiffre d'affaires se lisent dans une seule requête.
- Un tableau de bord que votre direction consulte déjà. Les totaux principaux dans l'outil de BI qui affiche tous les autres chiffres, plutôt qu'un identifiant de plus pour un panneau de plus.
Obtenir une clé
Demandez une clé à votre contact FanBase.
Elle est affichée une seule fois, à la création, et plus jamais ensuite. Placez-la directement dans un gestionnaire de mots de passe ou dans votre coffre de secrets. Si elle est perdue, la solution est une nouvelle clé.
Une clé peut avoir une date d'expiration. Demandez-en une pour tout ce qui est de courte durée, comme l'intégration d'un prestataire ou une migration ponctuelle. Une clé sans expiration est une clé qui survit à la personne qui l'a demandée.
Dites-nous quand une clé doit cesser de fonctionner et nous la révoquons.
C'est une API de serveur à serveur. La clé ne doit jamais se retrouver dans un navigateur, une application mobile, un build front-end ou quoi que ce soit d'autre qu'un fan peut lire. La clé lit toute votre communauté, et un fan qui la trouve peut la lire aussi. Placez-la sur un serveur, dans une tâche planifiée ou dans le connecteur de votre entrepôt de données.
Si ce que vous construisez s'adresse aux fans, utilisez plutôt le SDK. Il s'authentifie en tant que fan et ne renvoie que les données de ce fan. Voir la référence de l'API du SDK FanBase.
Appeler l'API
Envoyez la clé dans un en-tête x-api-key. L'URL de base est https://api.gamerbase.gg.
curl -H "x-api-key: $FANBASE_API_KEY" \
"https://api.gamerbase.gg/v1/data/members?limit=100&offset=0"Pas de parcours OAuth, pas de renouvellement de jeton.
Ressources que vous pouvez lire
| Ressource | À quoi elle sert |
|---|---|
| Membres | Une ligne par fan de votre communauté. La clé de jointure pour tout le reste ici, et la table sur laquelle votre CRM segmente. |
| Suppressions de membres | Les fans qui ont supprimé leur compte. Le seul moyen de respecter aussi une suppression dans vos propres systèmes, car un fan supprimé cesse d'apparaître dans les membres, et dans l'export des membres, sans rien pour signaler son absence. |
| Activité | Ce que les fans ont fait et quand. Le journal d'événements derrière chaque chiffre du tableau de bord, et la source pour les analyses de rétention et de cohortes. |
| Soldes de ressources | Un solde par fan et par ressource, donc l'XP et chaque monnaie dépensable créée par votre communauté. C'est là-dessus que vous segmentez quand vous voulez vos mille meilleurs fans plutôt que tous. |
| Objets détenus | Quels objets de collection et objets d'inventaire chaque fan possède. Utile pour vérifier qui détient réellement l'objet autour duquel une campagne a été construite. |
| Ouvertures de lootbox | Chaque ouverture et ce qui en est sorti. Pour le rapprochement, et pour répondre au fan qui dit que les probabilités sont fausses. |
| Totaux statistiques | Les compteurs principaux de toute la communauté, dont totalMembers et totalQuestsCompleted. La liste complète est dans la référence. L'appel peu coûteux pour un tableau de suivi qui n'a pas besoin de lignes par fan. |
| Catalogue de quêtes | Vos quêtes publiées. Public, et la seule partie qui ne demande aucune clé. |
Pagination et synchronisation
Chaque réponse de liste a la même forme : data contient les lignes, total indique combien de lignes correspondent au total, et offset indique où commence la page que vous avez en main. Vous paginez avec limit et offset. Le maximum actuel pour limit est dans la référence, qui est générée à partir de l'API et donne la valeur sur laquelle coder.
Utilisez updatedSince. Passez un horodatage et vous ne recevez que les lignes modifiées après. Votre première exécution récupère toute la communauté. Chaque exécution suivante récupère la poignée de lignes qui ont changé depuis la précédente.
Deux points à bien régler quand vous construisez cette boucle.
Enregistrez l'heure de début de l'exécution. Des lignes peuvent être écrites pendant que vous paginez, donc un curseur réglé sur la dernière ligne vue les saute. Ancrez-vous sur le début de l'exécution, faites chevaucher l'exécution suivante de quelques minutes, et une ligne écrite en cours de synchronisation sera quand même récupérée. Écrivez vos lignes de sorte que voir la même deux fois soit sans conséquence, et le chevauchement ne vous coûte rien.
Lisez les suppressions de membres au même rythme que les membres. Un fan supprimé cesse d'apparaître dans les membres, et une synchronisation incrémentale fondée sur updatedSince seul n'a aucun moyen de remarquer une absence. Elle garde la ligne périmée dans votre CRM indéfiniment, et continue d'envoyer des e-mails à quelqu'un qui a demandé à être oublié. Les suppressions sont une ressource à part précisément pour que vous puissiez les récupérer et agir en conséquence.
Limites de débit
La limite s'applique par minute et par clé, et elle est fixée assez haut pour qu'une synchronisation incrémentale bien construite ne s'en approche jamais. Chaque réponse porte des en-têtes X-RateLimit-* avec les chiffres en temps réel, et ces en-têtes font foi. Un client qui les lit et ralentit quand le nombre restant devient faible reste sous la limite sans aucun réglage de votre part.
Si vous atteignez la limite, la cause est presque toujours un retéléchargement complet planifié.
La référence interactive
Chaque point d'accès, chaque paramètre et chaque forme de réponse se trouve sur api.gamerbase.gg/api, et vous pouvez les appeler depuis la page avec votre clé. Elle est générée à partir de l'API, c'est donc la forme actuelle et non une copie. Orientez d'abord vos ingénieurs, et votre agent de code, vers elle.
Webhooks
À l'étudeAujourd'hui, vous interrogez l'API à intervalles réguliers. Les webhooks inverseraient cela : vous enregistreriez une URL, et la plateforme vous enverrait une requête quand quelque chose se passe, de sorte qu'une quête terminée pourrait atteindre votre CRM en quelques secondes plutôt qu'à la prochaine synchronisation.
C'est en discussion, pas encore planifié. Si votre campagne dépend d'une réaction en temps réel, dites-le à votre contact FanBase : savoir qu'un partenaire en a besoin est ce qui lui donne une date.