A atribuição de jogos para PC e console é um recurso empresarial. Para saber mais sobre esse recurso, leia nossas Perguntas frequentes sobre atribuição de jogos para PC e console ou entre em contato com seu gerente de sucesso do cliente.
A Singular fornece uma API REST que pode ser usada para relatar todos os seus dados de conversão de jogos de PC e console para a Singular para análise e atribuição.
Este guia explica como criar uma integração S2S para PC e console com a Singular e implementar vários recursos opcionais.
Conceitos de integração
Esta seção detalha conceitos abrangentes importantes para a implementação de uma integração S2S completa de PC e console.
Para obter uma lista completa dos pontos de extremidade da API S2S, seus parâmetros e exemplos de chamadas, consulte a Referência de pontos de extremidade S2S do PC & Console.
Privacidade do usuário
Para preservar a privacidade do usuário, a Singular recomenda que os desenvolvedores de jogos ofereçam uma opção para que os usuários finais aceitem ou não enviar dados de eventos do jogo para a Singular.
Autenticação
Todas as solicitações à API S2S para PC e console da Singular exigem que uma chave SDK seja enviada no parâmetro "a=". Sua chave SDK da Singular pode ser encontrada em "Developer Tools -> SDK Integration > SDK Keys" em seu painel de controle da Singular.
Aviso: Não use a "chave de API" da Singular encontrada em "Developer Tools -> API Keys". A "chave de API" é usada separadamente para a API de relatórios da Singular.
Plataformas, sistemas de jogos e lojas compatíveis
A "plataforma" na Singular é definida como a "plataforma" em que o usuário joga o jogo e deve ser passada no parâmetro"p=" em todas as solicitações de API S2S. Uma lista fechada de valores de "plataforma" compatíveis está abaixo:
- pc
- xbox
- playstation
- nintendo
- metaquest
Além da "plataforma", o "sistema operacional/jogo" e a "loja" devem ser passados nos parâmetros"os=" e"install_source=", respectivamente. Há suporte para valores personalizados, mas a Singular recomenda os seguintes valores por plataforma:
| Plataforma (p=) |
Sistema operacional/jogo (os=) |
Loja (install_source=) |
| pc |
windows linux macos steamos |
steam epicgamestore microsoftstore gog humblestore selfdistributed |
| xbox | xbox_one xbox_360 xbox_series_s xbox_series_x |
xbox |
| playstation | playstation_3 playstation_4 playstation_5 |
playstation |
| nintendo | nintendo_switch | nintendo |
| metaquest | metaquest metaquest_2 metaquest_pro |
metaquest |
Identificador de jogo
Para que a Singular associe eventos de jogo a um jogo, um identificador de jogo deve ser passado no parâmetro"i=" em cada solicitação.
- Qualquer valor pode ser aceito, mas a Singular recomenda que o valor seja passado em notação DNS reversa (ou seja, com.singular.game)
- Se o seu jogo estiver disponível em várias plataformas, é necessário que o mesmo identificador de jogo seja usado para o mesmo jogo em todas as plataformas suportadas (ou seja, p=pc&i=com.singular.game, p=xbox&i=com.singular.game, p=playstation&i=com.singular.game)
- Para que a Singular atribua corretamente as conversões de jogos a campanhas da Web por meio de uma página de destino do site, a "ID do produto" da integração da Web da Singular também deve corresponder ao valor do identificador do jogo.
Identificação de instalações exclusivas de jogos
Para que o Singular associe eventos de jogos em várias sessões de jogos para a mesma instalação de jogo, um identificador de instalação/dispositivo deve ser passado no parâmetro"sdid=" em cada solicitação.
- Formato UUID (versão 4) recomendado
- Esse valor deve ser gerado pelo jogo/servidor quando o jogo for iniciado (instalado) pela primeira vez e persistir durante toda a instalação do jogo.
ID de correspondência (opcional)
Se as campanhas na Web do seu jogo levarem os usuários a uma página de destino na Web e puderem utilizar a "ID de correspondência" para atribuição de site -> jogo para PC/Console, você poderá passar opcionalmente a "ID de correspondência" no parâmetro"match_id=" para melhorar a precisão da atribuição. Leia mais sobre a atribuição de PC e console em nossas Perguntas frequentes sobre o assunto.
- Para que a atribuição de instalação use a "ID da partida", ela deve ser passada na primeira inicialização do jogo para o usuário.
- O "Match ID" deve corresponder ao mesmo valor do usuário em sua implementação do Singular web SDK
Importante: a utilização da ID de correspondência para atribuição é considerada um recurso avançado. Consulte seu engenheiro de soluções Singular antes de implementá-lo.
Relatório de lançamentos de jogos
O relatório de todas as sessões de jogos para a Singular é necessário em uma integração de PC e console e espera que as sessões de jogos sejam enviadas sempre que o jogo for iniciado.
Para notificar a Singular sobre uma sessão de jogo, chame o Session Notification Endpoint.
As notificações de sessão permitem que o Singular faça várias coisas:
- Se for a primeira sessão de jogo após uma instalação exclusiva (consulte Identificação de instalações exclusivas de jogos), a Singular reconhece uma nova instalação e aciona o processo de atribuição de instalação.
- (Em breve) Se a sessão de jogo se qualificar como uma sessão de reengajamento, a Singular aciona o processo de atribuição de reengajamento (saiba mais nas Perguntas frequentes sobre reengajamento).
- Caso contrário, a Singular marca a sessão como uma sessão de jogo, que é usada para rastrear a atividade e a retenção do usuário.
Dica: Ao coletar os dados para relatar uma sessão de jogo, certifique-se de aguardar o retorno das funções assíncronas e de lidar com várias funcionalidades. Por exemplo:
- Ao usar o Match ID para melhorar a correspondência de atribuição, é importante relatar a primeira sessão de jogo somente depois que o Match ID estiver potencialmente disponível. Consulte Match ID.
- Se o seu jogo oferece uma maneira de aceitar o marketing e a análise de jogos da Singular, é importante esperar até que o consentimento seja coletado antes de relatar a sessão do jogo. Consulte Privacidade do usuário.
Relatório de eventos no jogo
Eventos
A Singular pode coletar dados sobre eventos no jogo para ajudar a analisar o desempenho de suas campanhas de marketing. Os eventos podem incluir qualquer interação do usuário, desde logins e registros até o aumento de nível no jogo.
Antes de implementar uma integração S2S com a Singular, você deve ter uma lista dos eventos que sua organização deseja rastrear (consulte Definição de eventos no jogo).
Para notificar a Singular quando um evento ocorrer em seu jogo, chame o endpoint Event Notification. O nome do evento que você incluir na chamada é como o evento será identificado nos relatórios, exportações e postbacks do Singular.
Observações:
- A Singular recomenda passar eventos usando a convenção de nomenclatura de eventos e atributos padrão da Singular. O uso de eventos padrão simplifica o mapeamento e a compatibilidade com os eventos padrão de seus parceiros em integrações.
- A Singular recomenda passar nomes e atributos de eventos personalizados em inglês para compatibilidade com quaisquer parceiros e soluções analíticas de terceiros que você queira usar.
- Os nomes de eventos são limitados a 32 caracteres ASCII. Para caracteres não ASCII, o limite é de 32 bytes após a conversão para UTF-8.
- Os atributos e valores de eventos são limitados a 500 caracteres ASCII.
Receita
A Singular pode coletar dados sobre a receita obtida por meio do jogo para ajudar a analisar o desempenho e o ROI de suas campanhas. A Singular disponibilizará os dados para você em relatórios, exportação de registros e postbacks.
Para rastrear eventos de receita, use o mesmo endpoint de Notificação de eventoque você usa para todos os eventos, mas adicione as seguintes informações:
- is_revenue_event=true: marca o evento como um evento de receita. Você pode ignorar esse parâmetro se o nome do evento for"__iap__" ou se o valor for maior que zero.
- Valor da receita (por exemplo,"amt=1,99").
- Moeda (use o código de moeda ISO 4217, por exemplo,"cur=USD").