Data API
Lleva a tus miembros, su actividad y sus saldos a tu CRM, tu almacén de datos o tu herramienta de BI.
Acceso HTTP de solo lectura a los miembros, la actividad, los saldos y los objetos en propiedad de tu propia comunidad, autenticado con una clave. Nunca toca la experiencia del fan.
Alcance y primeros usos
Las tres cosas que los socios construyeron primero con ella:
- Un segmento de CRM. Los miembros y sus saldos cruzados con la lista de correo, para que una campaña llegue a los fans por encima del nivel diez y no a todo el mundo.
- Una tabla en el almacén de datos. Una descarga nocturna de miembros y actividad en el mismo sitio al que ya llegan los datos de la tienda, para que la participación en la aplicación y los ingresos se puedan ver en una sola consulta.
- Un cuadro de mando que tu dirección ya consulta. Los totales principales dentro de la herramienta de BI que muestra todas las demás cifras, en lugar de un inicio de sesión más para un panel más.
Conseguir una clave
Pide una clave a tu contacto de FanBase.
Se muestra una sola vez, al crearla, y nunca más. Guárdala directamente en un gestor de contraseñas o en tu almacén de secretos. Si se pierde, la solución es una clave nueva.
Una clave puede tener fecha de caducidad. Pide una para todo lo que dure poco, como la integración de un proveedor externo o una migración puntual. Una clave sin caducidad es una clave que sobrevive a la persona que la pidió.
Dinos cuándo debe dejar de funcionar una clave y la revocamos.
Esta es una API de servidor a servidor. La clave nunca debe acabar en un navegador, una aplicación móvil, una compilación de front end ni en ningún otro sitio que un fan pueda leer. La clave lee toda tu comunidad, y un fan que la encuentre también puede leerla. Ponla en un servidor, en una tarea programada o en el conector de tu almacén de datos.
Si lo que estás construyendo va dirigido a los fans, usa el SDK. Se autentica como el fan y devuelve solo los datos de ese fan. Consulta la referencia de la API del FanBase SDK.
Cómo llamarla
Envía la clave en una cabecera x-api-key. La URL base es https://api.gamerbase.gg.
curl -H "x-api-key: $FANBASE_API_KEY" \
"https://api.gamerbase.gg/v1/data/members?limit=100&offset=0"Sin flujo de OAuth y sin renovación de tokens.
Recursos que puedes leer
| Recurso | Para qué sirve |
|---|---|
| Miembros | Una fila por cada fan de tu comunidad. La clave de unión para todo lo demás que hay aquí, y la tabla sobre la que segmenta tu CRM. |
| Bajas de miembros | Los fans que eliminaron su cuenta. La única forma de respetar una eliminación también en tus propios sistemas, porque un fan eliminado deja de aparecer en los miembros, y en la exportación de miembros, sin nada que marque la ausencia. |
| Actividad | Qué hicieron los fans y cuándo. El registro de eventos que hay debajo de cada cifra del cuadro de mando, y la fuente para los análisis de retención y de cohortes. |
| Saldos de recursos | Un saldo por fan y por recurso, es decir, los XP y cada moneda gastable que haya creado tu comunidad. Sobre esto segmentas cuando quieres a tus mil mejores fans y no a todos. |
| Objetos en propiedad | Qué objetos coleccionables y objetos del inventario tiene cada fan. Útil para comprobar quién tiene de verdad aquello en torno a lo que se montó una campaña. |
| Aperturas de cajas de botín | Cada apertura y lo que salió de ella. Para la conciliación, y para responder al fan que dice que las probabilidades están mal. |
| Totales de estadísticas | Los recuentos principales de toda la comunidad, entre ellos totalMembers y totalQuestsCompleted. El conjunto completo está en la referencia. La llamada barata para un panel de seguimiento que no necesita filas por fan. |
| Catálogo de misiones | Tus misiones publicadas. Es público, y la única parte de todo esto que no necesita ninguna clave. |
Paginación y sincronización
Todas las respuestas de lista tienen la misma forma: data contiene las filas, total indica cuántas filas coinciden en total y offset dice dónde empieza la página que tienes delante. Paginas con limit y offset. El máximo actual de limit está en la referencia, que se genera a partir de la API y es el valor con el que debes programar.
Usa updatedSince. Pasa una marca de tiempo y recibes solo las filas que cambiaron después. Tu primera ejecución descarga toda la comunidad. Cada ejecución posterior descarga el puñado de filas que cambiaron desde la anterior.
Dos cosas que hay que hacer bien al construir ese bucle.
Guarda la hora a la que empezó la ejecución. Se pueden escribir filas mientras paginas, así que un cursor fijado en la última fila que viste se las salta. Ánclate al inicio de la ejecución, solapa la siguiente ejecución unos minutos, y una fila escrita en mitad de la sincronización se recogerá igualmente. Escribe tus filas de modo que ver la misma dos veces sea inofensivo, y el solapamiento no te cuesta nada.
Lee las bajas de miembros con la misma frecuencia que los miembros. Un fan eliminado deja de aparecer en los miembros, y una sincronización incremental basada solo en updatedSince no tiene forma de notar una ausencia. Mantiene la fila obsoleta en tu CRM para siempre, y sigue enviando correos a alguien que pidió ser olvidado. Las bajas son un recurso aparte precisamente para que puedas descargarlas y actuar en consecuencia.
Límites de peticiones
El límite es por minuto y por clave, y está fijado lo bastante alto como para que una sincronización incremental bien construida nunca se acerque. Cada respuesta lleva cabeceras X-RateLimit-* con las cifras en tiempo real, y esas cabeceras son la referencia que manda. Un cliente que las lee y frena cuando el recuento restante baja se mantiene dentro del límite sin que tengas que ajustar nada.
Si estás alcanzando el límite, la causa es casi siempre una descarga completa repetida de forma programada.
La referencia interactiva
Cada endpoint, cada parámetro y cada forma de respuesta está en api.gamerbase.gg/api, y puedes llamarlos desde la página con tu clave. Se genera a partir de la API, así que es la forma actual y no una copia. Dirige allí primero a tus ingenieros y a tu agente de programación.
Webhooks
En estudioHoy consultas tú la API de forma periódica. Los webhooks le darían la vuelta: registrarías una URL y la plataforma te enviaría una petición cuando pasara algo, de modo que una misión completada podría llegar a tu CRM en segundos y no en la siguiente sincronización.
Está en debate, todavía sin fecha. Si tu campaña depende de una reacción en tiempo real, díselo a tu contacto de FanBase: saber que un socio lo necesita es lo que le pone fecha.