A atribuição de jogos para PC e consola é uma funcionalidade empresarial. Para saber mais sobre esse recurso, leia nosso FAQ de Atribuição de Jogos de 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 para PC e Console à Singular para análise e atribuição.
Este guia explica como construir uma integração S2S para PC e Console com a Singular e implementar vários recursos opcionais.
Conceitos de integração
Esta secção detalha conceitos abrangentes importantes para a implementação de uma integração S2S de PC e Consola completa.
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 utilizador
A fim de preservar a privacidade do utilizador, a Singular recomenda que os programadores de jogos ofereçam uma opção para os utilizadores finais optarem por aceitar ou recusar o rastreio. Dependendo dos requisitos da sua empresa para lidar com os dados do usuário, você pode:
- Não enviar dados de eventos do jogo para a Singular ao optar por não participar
- Enviar dados de eventos de jogos para a Singular, mas incluir as opções de consentimento de inclusão e exclusão do utilizador. Nesses casos, implemente e passe esse sinalizador de consentimento através do valor "Limitar compartilhamento de dados" no parâmetro data_sharing_options.
A Singular utiliza "Limitar partilha de dados" em"Postbacks de privacidade do utilizador", bem como transmite esta informação aos parceiros que a exigem para cumprir os regulamentos relevantes. Consulte"Privacidade do utilizador e limitação da partilha de dados" para obter mais informações.
Autenticação
Todos os pedidos à API S2S para PC e Consola da Singular requerem o envio de uma chave SDK no parâmetro "a=". A sua chave SDK Singular pode ser encontrada em"Ferramentas do desenvolvedor -> Integração SDK > Chaves SDK" no seu painel Singular.
Aviso: Não utilize a "chave API" do Singular que se encontra em "Developer Tools -> API Keys". A "chave de API" é usada separadamente para a API de relatórios do Singular.
Plataformas, sistemas de jogos e lojas suportados
A "Plataforma" no Singular é definida como a "plataforma" onde o utilizador joga o jogo, e deve ser passada no parâmetro"p=" em todos os pedidos da API S2S. Uma lista fechada de valores de "plataforma" suportados está abaixo:
- pc
- xbox
- playstation
- nintendo
- metaquest
Para além da "plataforma", o "sistema operativo/jogo" e a "loja" devem ser passados nos parâmetros"os=" e"install_source=", respetivamente. Valores personalizados são suportados, mas a Singular recomenda os seguintes valores por plataforma:
| Plataforma (p=) |
Sistema operativo/jogo (os=) |
Loja (install_source=) |
| pc |
windows linux macos steamos |
steam epicgamestore microsoftstore gog humblestore auto-distribuição |
| 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 requisição.
- Qualquer valor pode ser suportado, mas a Singular recomenda que o valor seja passado em notação DNS reversa (i.e. com.singular.game)
- Se o seu jogo estiver disponível em várias plataformas, é necessário que o mesmo identificador de jogo seja utilizado 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 o Singular atribua corretamente as conversões de jogos a campanhas Web através de uma página de destino de um Web site, a "ID do produto" da sua integração Web 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 jogo em várias sessões de jogo 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
- O valor deve ser gerado pelo jogo/servidor no momento do primeiro lançamento do jogo (instalação) e persistir durante toda a vida útil da instalação do jogo.
ID de correspondência (opcional)
Se as campanhas Web do seu jogo conduzirem os utilizadores a uma página de destino Web e puder utilizar a "ID de correspondência" para a atribuição do jogo PC/Console ao Web site, pode, opcionalmente, passar 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 consola nas nossas FAQ sobre o tema.
- Para que a atribuição de instalação utilize o "ID da partida", este deve ser passado no primeiro lançamento do jogo para o utilizador.
- A "ID da partida" deve corresponder ao mesmo valor do usuário na implementação do Singular web SDK
Importante: A utilização da ID de partida para atribuição é considerada um recurso avançado. Consulte seu engenheiro de soluções Singular antes de implementar.
Relatórios de lançamentos de jogos
O relatório de todas as sessões de jogo para a Singular é necessário em uma integração de PC & Console e espera que as sessões de jogo sejam enviadas cada vez 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 Identificando instalações exclusivas de jogos), o 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, o Singular aciona o processo de atribuição de reengajamento (saiba mais nas Perguntas frequentes sobre reengajamento).
- Caso contrário, o 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 esperar que as funções assíncronas retornem e manipulem várias funcionalidades. Por exemplo:
- Ao usar a ID de correspondência para melhorar a correspondência de atribuição, é importante relatar a primeira sessão de jogo somente depois que a ID de correspondência estiver potencialmente disponível. Consulte ID da partida.
- Se o seu jogo oferece uma maneira de optar por participar do marketing e da análise de jogos da Singular, é importante aguardar até que o consentimento seja coletado antes de relatar a sessão do jogo. Consulte Privacidade do usuário.
Relatando 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 utilizador, desde logins e registos até à subida de nível no jogo.
Antes de implementar uma integração S2S com Singular, você deve ter uma lista dos eventos que sua organização deseja rastrear (consulte Definindo eventos no jogo).
Para notificar a Singular quando um evento ocorrer em seu jogo, chame o ponto de extremidade Notificação de evento. O nome do evento que você inclui 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 padrão de nomeação de eventos e atributos 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 de terceiros e soluções de análise que você possa querer usar.
- Os nomes de eventos são limitados a 32 caracteres ASCII. Para caracteres não-ASCII, o limite é de 32 bytes depois de convertidos para UTF-8.
- Os atributos e valores do evento estão limitados a 500 caracteres ASCII.
Receitas
A Singular pode recolher dados sobre a receita obtida através do jogo para ajudar a analisar o desempenho e o ROI das suas campanhas. A Singular disponibilizará os dados em relatórios, exportação de registos e postbacks.
Para rastrear eventos de receita, use o mesmo ponto de extremidade de Notificação de evento que você usa para todos os eventos, mas adicione as seguintes informações:
- is_revenue_event=true: marca o evento como um evento de receita. Pode ignorar este parâmetro se o nome do evento for"__iap__" ou se o montante for superior a zero.
- Montante da receita (por exemplo,"amt=1,99").
- Moeda (utilizar o código de moeda ISO 4217, por exemplo,"cur=USD").