Integrações

Data API

Leve os seus membros, a atividade e os saldos deles para o seu CRM, o seu data warehouse ou a sua ferramenta de BI.

Acesso HTTP só de leitura aos membros, à atividade, aos saldos e aos objetos detidos da sua própria comunidade, autenticado por uma chave. Nunca toca na experiência do fã.

Âmbito e primeiras utilizações

As três coisas que os parceiros construíram primeiro com ela:

  • Um segmento de CRM. Os membros e os respetivos saldos cruzados com a lista de e-mails, para que uma campanha vá para os fãs acima do nível dez e não para toda a gente.
  • Uma tabela no data warehouse. Um carregamento noturno de membros e atividade no mesmo sítio onde os dados da loja já chegam, para que o envolvimento na aplicação e a receita possam ser vistos numa única consulta.
  • Um dashboard que a sua direção já lê. Os totais principais na ferramenta de BI que mostra todos os outros números, em vez de mais um início de sessão para mais um painel.

Como obter uma chave

Peça uma chave ao seu contacto na FanBase.

É apresentada uma única vez, na criação, e nunca mais. Guarde-a diretamente num gestor de palavras-passe ou no seu cofre de segredos. Se se perder, a solução é uma chave nova.

Uma chave pode ter data de expiração. Peça uma para tudo o que for de curta duração, como a integração de um prestador de serviços ou uma migração pontual. Uma chave sem expiração é uma chave que dura mais do que a pessoa que a pediu.

Avise-nos quando uma chave deve deixar de funcionar e nós revogamo-la.

Esta é uma API de servidor para servidor. A chave nunca deve ir para um navegador, uma aplicação móvel, um build de front-end ou qualquer outra coisa que um fã possa ler. A chave lê a sua comunidade inteira, e um fã que a encontre também o pode fazer. Coloque a chave num servidor, numa tarefa agendada ou no conector do seu data warehouse.

Se o que está a construir se destina aos fãs, use o SDK. Autentica-se como o fã e devolve apenas os dados desse fã. Veja a referência da API do SDK da FanBase.

Como chamar

Envie a chave num cabeçalho x-api-key. O URL base é https://api.gamerbase.gg.

curl -H "x-api-key: $FANBASE_API_KEY" \
  "https://api.gamerbase.gg/v1/data/members?limit=100&offset=0"

Sem fluxo de OAuth e sem renovação de token.

Recursos que pode ler

RecursoPara que serve
MembrosUma linha por fã da sua comunidade. A chave de junção para tudo o resto aqui, e a tabela sobre a qual o seu CRM segmenta.
Eliminações de membrosFãs que eliminaram a conta. É a única forma de respeitar uma eliminação também nos seus próprios sistemas, porque um fã eliminado deixa de aparecer em membros, e na exportação de membros, sem nada que assinale a ausência.
AtividadeO que os fãs fizeram e quando. O registo de eventos por trás de cada número do dashboard, e a fonte para análises de retenção e de coortes.
Saldos de recursosUm saldo por fã e por recurso, ou seja, o XP e cada moeda gastável que a sua comunidade criou. É o que se usa para segmentar quando quer os seus mil melhores fãs e não todos.
Objetos detidosQue objetos colecionáveis e objetos de inventário cada fã detém. Útil para verificar quem tem realmente o objeto em torno do qual uma campanha foi criada.
Aberturas de loot boxesCada abertura e o que saiu dela. Serve para reconciliação e para responder ao fã que diz que as probabilidades estão erradas.
Totais de estatísticasContagens gerais de toda a comunidade, entre elas totalMembers e totalQuestsCompleted. O conjunto completo está na referência. É a chamada barata para um painel de acompanhamento que não precisa de linhas por fã.
Catálogo de missõesAs suas missões publicadas. É público, e a única parte que não exige chave nenhuma.

Paginação e sincronização

Todas as respostas de lista têm o mesmo formato: data traz as linhas, total traz quantas linhas correspondem no total, e offset indica onde começa a página que tem em mãos. A paginação faz-se com limit e offset. O máximo atual de limit está na referência, que é gerada a partir da API e é o valor a usar no seu código.

Use updatedSince. Passe um timestamp e recebe de volta apenas as linhas que mudaram depois dele. A sua primeira execução traz a comunidade inteira. Cada execução seguinte traz as poucas linhas que mudaram desde a anterior.

Dois pontos a acertar ao construir este ciclo.

Guarde a hora a que a execução começou. Podem ser gravadas linhas enquanto pagina, pelo que um cursor definido na última linha que viu as deixa para trás. Tome como âncora o início da execução, sobreponha a execução seguinte em alguns minutos, e uma linha gravada a meio da sincronização continuará a ser apanhada. Grave as suas linhas de modo que ver a mesma duas vezes seja inofensivo, e a sobreposição não custa nada.

Leia as eliminações de membros com a mesma frequência que os membros. Um fã eliminado deixa de aparecer em membros, e uma sincronização incremental baseada apenas em updatedSince não tem como dar por uma ausência. Mantém a linha desatualizada no seu CRM para sempre e continua a enviar e-mails a alguém que pediu para ser esquecido. As eliminações são um recurso separado precisamente para que as possa ir buscar e agir.

Limites de pedidos

O limite é por minuto e por chave, e é suficientemente alto para que uma sincronização incremental bem construída nunca se aproxime dele. Todas as respostas trazem cabeçalhos X-RateLimit-* com os números em tempo real, e esses cabeçalhos são a referência oficial. Um cliente que os lê e abranda o ritmo quando a contagem restante fica baixa mantém-se dentro do limite sem nenhum ajuste da sua parte.

Se está a atingir o limite, a causa é quase sempre uma nova transferência completa agendada.

A referência interativa

Cada endpoint, cada parâmetro e cada formato de resposta está em api.gamerbase.gg/api, e pode chamá-los a partir da própria página com a sua chave. É gerada a partir da API, por isso mostra o formato atual e não uma cópia. Indique-a primeiro aos seus engenheiros e ao seu agente de programação.

Webhooks

Em estudo

Hoje a API é consultada periodicamente. Os webhooks inverteriam isso: registaria um URL, e a plataforma enviar-lhe-ia um pedido quando algo acontecesse, de modo que a conclusão de uma missão poderia chegar ao seu CRM em segundos, e não na sincronização seguinte.

Está em discussão, ainda sem data. Se a sua campanha depende de uma reação em tempo real, avise o seu contacto na FanBase: saber que um parceiro precisa disso é o que faz a ideia ganhar uma data.

Nesta página