Integração com o Singular

Glossário

Singular

Atribuição móvel e plataforma de análises de marketing. O Singular possibilita que desenvolvedores de aplicativos, profissionais de marketing e marcas rastreiem, meçam e otimizem a eficiência de suas campanhas de marketing ao longo de vários canais e dispositivos. Consulte a documentação do Singular para obter informações detalhadas sobre a plataforma.

Singular Device ID (SDID)

ID Exclusivo que identifica o navegador de cada visitante, gerado automaticamente pelo Singular Web SDK.

ID de Aplicativo

ID de Aplicativo móvel exclusivo para cada plataforma (Android, iOS). Ele corresponde ao valor Bundle ID que você pode encontrar no Singular na seção Settings > Apps, no painel de um aplicativo necessário.

Valor Vitalício (LTV)

Receita média que um usuário gera durante o tempo que eles usam o aplicativo. Consulte a documentação Singular para mais informações sobre o LTV.

Retorno Nos Gastos de Anúncios (ROAS)

Métrica que mede a eficiência de uma campanha de anúncios calculando a receita adquirida por unidade de anúncio gasta.

Evento web

As ações do usuário na Web Shop, que são enviadas do lado do cliente da Web Shop ao Singular e são necessários à integração do Web SDK.

Evento no aplicativo

Ação do usuário dentro do aplicativo. Consulte a documentação Singular para obter informações detalhadas sobre os eventos no aplicativo. As ações do usuário na Web Shop também são consideradas como eventos no app no caso da integração S2S e enviadas ao Singular pelo backend da Xsolla.

Aquisição de usuários

O processo de atrair novos usuários ao site, serviço, plataforma ou aplicativo através da atividade de marketing.

Redirecionamento

Contatar os usuários atuais ou passados através de campanhas de anúncios. Consulte a estratégia de usuários engajantes que já interagiram anteriormente com o seu aplicativo ou site. Consulte a documentação Singular para obter informações detalhadas.

ID de Usuário do Cliente (Customer user ID, CUID)

ID de Usuário gerado e definido pelo proprietário do aplicativo no momento do cadastro do usuário. O CUID deve ser o mesmo para a Web Shop e o Singular. Esse parâmetro é usado para o pareamento e atribuição de usuários.

Você deve passar este parâmetro no postback. Se os CUIDs na Web Shop e seu aplicativo móvel não corresponderem, contate seu Gerente de Sucesso do Cliente ou envie um e-mail para csm@xsolla.com para implementar o webhook Validação de usuário na Web Shop ou a autenticação via link profundo.

Para configurar o CUID, consulte a documentação Singular SDK.

Postback

Processo de recebimento de dados em eventos no app. Consulte a documentação Singular para obter informações detalhadas.

Chave SDK

Token que é usado para autorizar chamadas para enviar dados de eventos para o Singular. Ele é gerado no lado do Singular. Consulte as documentações Singular para obter informações detalhadas.

Segredo do SDK

Componente usado em conjunto com a chave Singular SDK para inicializar e autenticar o Singular SDK dentro de um aplicativo. Esse segredo, junto com a chave SDK, permite que o SDK se comunique seguramente com a plataforma Singular e atribua as instalações dos aplicativos, eventos e outros dados para análises de marketing.

Fluxo de integração

O Singular e a Xsolla suportam os seguintes tipos de integrações:

Mobile application S2S integration — permite a conclusão de mensurações LTV e ROAS completas para as compras dentro do aplicativo e na Web Shop. A Xsolla envia informações sobre compras na Web Shop ao Singular como eventos no aplicativo móvel, que o Singular então atribui à quantidade de instalações de aplicativos móveis, aquisição de usuários e campanhas de reengajamento.
Web SDK integration — permite que você meça e avalie a eficiência da aquisição de usuário e campanhas de redirecionamento para atrair tráfego à Web Shop.
A integração com o Web SDK permite a avaliação de quantos usuários vieram ao site através de uma campanha de redirecionamento e a conversão de canais levando ao site. A Xsolla envia informações sobre as compras na Web Shop ao Singular como eventos web, que o Singular atribui à fonte de mídia correspondente, campanha, conjunto de anúncio, e anúncios que levam o usuário à compra.

Você pode configurar a integração Web SDK com o Singular para obter análises de eventos avançadas se você utilizar:

Os seguintes eventos estão disponíveis pela integração Xsolla e Singular Web SDK:

Evento	Descrição
`load`	Evento de visitação do site, incluindo os parâmetros URL que contém a informação fonte de onde o usuário está vindo, e um Singular Device ID, que é armazenado em um cookie primário.
`identify`	Evento de login, incluindo Singular Device ID e CUID.
`event`	Evento de compra de item, incluindo o Singular Device ID e CUID, e outros eventos do Site Builder.

Como funciona

Abaixo, temos um cenário de interação do sistema ao implementar campanhas de aquisição de usuário e redirecionamento. O usuário passa pelos banners de anúncios à Web Shop e faz uma compra. O conjunto de eventos que são enviados ao Singular nesse processo nos permite rastrear:

quantos usuários clicaram em cada banner e de onde eles vieram
quanto os usuários pagaram
se a campanha de redirecionamento foi eficiente

  sequenceDiagram
    participant User
    participant Promo as Web Shop<br>promotional campaign<br>(ad banner)
    participant Shop as Web Shop
    participant SG as Singular
    User->>Promo: 1. Clicks banner
    Promo->>Shop: 2. Redirect with URL parameters
    Shop->>SG: 3. load event
    User->>Shop: 4. Logs in with CUID
    Shop->>SG: 5. identify event
    User->>Shop: 6. Makes purchase
    Shop->>SG: 7. event

Fluxo de usuário:

O usuário pressiona o banner da campanha de anúncios.
O usuário é redirecionado à Web Shop, e o URL dessa transição inclui os parâmetros Singular e macros, especificando de qual banner e site o usuário foi direcionado.
Um evento sobre a visite é enviado do lado do cliente do Web Shop ao Singular.
O usuário faz login na Web Shop usando o CUID.
O evento de autorização é enviado ao Singular.
O usuário faz uma compra na Web Shop.
O evento de compra é enviado ao Singular.

Como configurar no Singular

Acesse sua conta Singular.
Acesse a seção Settings > Apps.

Selecione Add new app.

Especifique o nome do seu aplicativo da web.

Selecione Web como o OS.
No campo URL, especifique o domínio do seu Web Shop, ex.: yourapp.yourcompany.com.
No campo Bundle ID, especifique sua ID de Conjunto no formato de DNS inverso, ex.: com.yourcompany.
Selecione Save.

Como configurar na Conta de Distribuidor

Abra seu projeto na Conta de Distribuidor.
Acesse o construtor de sites usando um dos seguintes métodos:
- No menu lateral, selecione Storefronts > Websites, selecione seu site e pressione Configure.
- No menu lateral, selecione Integrations. Na seção que surgir:
  1. Selecione o painel Singular.

- 1. No painel Web SDK (Site Builder), selecione Configure.

- 1. Selecione seu site e pressione Configure.
  2. Na aba Site settings, acesse a seção Apps.
  3. No painel Singular, selecione Connect.

No formulário Singular connection, preencha os campos chave SDK, segredo do SDK e ID do Conjunto:

Para encontrar essa informação na sua conta Singular:
1. Faça login na sua conta Singular.
2. Acesse a seção Developer Tools > SDK Integration.
3. Acesse a aba SDK Keys.
4. Selecione Show Keys.
5. Copie o valor no campo SDK Key.
6. Copie o valor no campo SDK Secret.

1. Para encontrar seu ID de Conjunto, acesse Settings > Apps > Web Application e copia o ID de Conjunto.

Selecione Connect.

Como executar campanhas de anúncios no app e na web para a Web Shop

Use essas instruções para executar e rastrear as campanhas de aquisição de usuários e de anúncios de redirecionamento para a Xsolla Web Shop. Isso se aplica tanto:

A campanhas da web à Web Shop (anúncios que geram usuários de fontes na web à sua Web Shop)
A campanhas de redirecionamento no app à Web Shop (anúncios que levam usuários do seu aplicativo à sua Web Shop)

Para criar um link do site Singular:

Acesse sua conta Singular.
Acesse a seção Attribution Setup e selecione Create Web Link.
No campo Target (App), escolha seu web app relacionado à Xsolla Web Shop.
No campo Partner, selecione seu parceiro da rede de anúncios.

Insira uma página de destino se necessário (opcional).
Atualize os campos UTM para capturar os dados da campanha (opcional).
Selecione Generate Link.

Um URL de destino final para sua Web Campaign será gerado com base na sua seleção. Trafege esse link para a sua Web Campaign.

Para um rastreamento de campanha mais detalhado (granularidade), você pode adicionar macros ao URL gerado. Use o guia de adição de macros para anexar parâmetros macro para o Singular Web SDK, permitindo a captura de dados no nível da campanha. Certifique-se de não sobrescrever quaisquer parâmetros existentes no link.

As instruções podem ser atualizadas com base na rede de anúncios específica selecionada. Sempre siga quaisquer notas específicas da rede de anúncios exibida no construtor da Web URL.

Para mais detalhes, consulte o guia Singular Website Links.

Como adicionar eventos Web/Web Shop no Singular

Faça login na sua conta Singular.
Acesse a seção Settings > Events.
Adicione os eventos capturados pelo seu Web SDK:
1. Selecione App specific Events.
2. Selecione seu aplicativo.
3. Na seção Cohort Events, adicione o nome do evento que aparecerá nos seus relatórios.
4. No campo Event maps to the following, selecione o evento SDK.
5. Selecione Save.

Consulte a instrução How to Track In-App Events para mais informações.

Os eventos de receita são inclusos automaticamente na métrica Revenue nos relatórios Singular. Você não precisa adicionar um evento personalizado a menos que você queira rastrear a quantidade de eventos de receita separadamente.

Como obter relatórios de desempenho de campanhas de anúncios da Web Shop no Singular

Para gerar um relatório para as campanhas de anúncios web-to-web e in-app-to-web:

Faça login na sua conta Singular.
Acesse a seção Reports > Insights.
Configure seus filtros:
- Defina sua faixa de datas desejada.
- Selecione o app que deseja analisar.

Adicione dimensões para segmentar seus dados:
- Fonte
- Nome da Campanha
- dimensões adicionais como necessário

Escolha suas métricas da web:
- Novos Visitantes da Web
- Visitantes Reengajados da Web

Inclua os dados da coorte:
- Receita
- ROI
- quaisquer eventos de coorte personalizados previamente configurados na página Settings > Events

Selecione Run report no canto superior direito.

Estabeleça uma convenção de nomenclatura para suas campanhas que distinguem entre campanhas web-to-web e in-app-to-web. Essa taxonomia faz com que a análise de relatórios seja significativamente mais fácil e garante que sua equipe possa rapidamente identificar os tipos de campanha.

Consulte Reports FAQ para saber mais.

Você pode configurar a integração de aplicativos móveis para obter análises de eventos avançadas se você:

tem um aplicativo móvel para Android/iOS
usa o Singular
use a solução Web Shop para vender itens no jogo

O seguinte evento está disponível via Xsolla e a integração Singular S2S:

Evento	Descrição
xsolla-billing-payment	Compra de item. Os parâmetros do evento contém informações sobre uma compra.

Como funciona

A integração inclui um fluxo de dados bidirecional entre a Xsolla e o Singular. Abaixo está o cenário de sistema de interação quando um usuário faz uma compra.

  sequenceDiagram
    participant User
    participant Mobile App
    participant Web Shop
    participant Xsolla Backend
    participant Singular
    User->>Mobile App: 1. Logs in
    Mobile App->>Singular: 2. Sends CUID
    Singular-->>Xsolla Backend: 3. Sends postback
    User->>Web Shop: 4. Logs in using CUID
    User->>Web Shop: 5. Makes a purchase
    Web Shop->>Xsolla Backend: 6. Sends purchase event
    Xsolla Backend->>Singular: 7. Sends xsolla-billing-payment event

O usuário (jogador) se cadastra ou faz login no aplicativo móvel.
Seu aplicativo envia um evento no app ao Singular, como login, ou qualquer outro evento que inclua o CUID.

Para configurar o CUID, consulte a documentação Singular SDK.

O Singular envia um postback à Xsolla, que inclui o CUID e outros dados sobre o dispositivo do usuário.
O usuário faz login na Web Shop usando o CUID.
O usuário faz uma compra na Web Shop.
O evento de compra é enviado ao servidor Xsolla e pareado com os dados recebidos do Singular.
O servidor da Xsolla envia um evento no app ao Singular, que contém parâmetros necessários para o mapeamento.

O Singular atribui um novo evento, compra e receita de volta à fonte de mídia que levou à aquisição do usuário ou o re-engajamento do usuário.

Como configurar na Conta de Distribuidor

Abra seu projeto na Conta de Distribuidor e acesse a seção Integrations.
Clique no painel Singular.

No painel Mobile app S2S integration, clique em Configure.
Na janela que surgir, certifique-se de que a caixa Enable this integration está marcada.
Forneça os seguintes dados:
1. Chave SDK do Singular.
2. ID do Aplicativo, exclusivo para cada plataforma (Android/iOS). Para adicionar uma plataforma, selecione Add application ID.
Selecione Save.
Ative a integração no Singular.

Depois de salvar as configurações, um indicador verde será exibido no painel de integração S2S.

Para fazer alterações na integração conectada:

Selecione o painel Singular.
Faça as alterações necessárias na janela que surgir.
Selecione Save.

Como configurar no Singular

No Singular, você precisa:

Obter uma chave SDK.
Ativar a integração com a Xsolla.

Obtenção da chave SDK

Acesse sua conta Singular.
Abra a seção Developer Tools > SDK Integration.
Acesse a aba SDK Keys.
Selecione Show Keys.
Copie o valor no campo SDK Key.

Ative a integração com a Xsolla

Acesse sua conta Singular.
Acesse a seção Attribution Setup > Partner Configuration.
Selecione Add Partner.
Na barra de pesquisas, insira e selecione Xsolla.

Na janela que surgir, selecione um aplicativo para configurar a integração.
Selecione Next.
Certifique-se de que o evento Login esteja selecionado no bloco Events Postbacks.
Clique em Save.

Certifique-se de configurar o CUID:

O método SetCustomerId e seu evento de autenticação são implementados usando o Singular SDK.
Na sua Conta de Distribuidor Xsolla, a integração com o Singular está configurada.
Na sua conta Singular, a integração com a Xsolla está ativada.

Se você tiver a opção Reject IAP without receipt ativada para o seu aplicativo no Singular, contate seu Gerente do Cliente Singular para ativar ou desativar os eventos de receita da Xsolla.

Estrutura dos valores do evento

Se você quiser configurar um evento específico ou se as opções de integração atuais não cobrirem suas necessidades, contate seu Gerente de Sucesso do Cliente ou envie um e-mail para csm@xsolla.com.

Compra de itens

Quando um usuário faz uma compra na Web Shop, a Xsolla envia o evento xsolla-billing-payment ao Singular. As seguintes informações de compra são passadas nos parâmetros do evento:

Parâmetro	Descrição
content_id	Único SKU ou matriz de SKU na compra.
quantity	Quantidade do item com o SKU correspondente (um ou uma matriz).
revenue	Quantia de compra. Descontos são incluídos. Não contém quaisquer comissões ou taxas.
currency	Moeda de compra.

Dados adicionais

Além dos parâmetros passados no evento xsolla-billing-payment, a Xsolla envia os seguintes dados:

Parâmetro	Descrição
a	Chave SDK do Singular.
p	Plataforma do aplicativo. Exemplo: iOS.
ip	Endereço IP público do dispositivo do usuário.
ve	Versão do sistema operacional do dispositivo do usuário.
ma	Marca do dispositivo do usuário. Exemplo: Apple.
mo	Modelo do dispositivo do usuário. Exemplo: iPhone 4S.
lc	Local do dispositivo do usuário no formato `^[a-z]{2}-[A-Z]{2}$`. Exemplo: `en_US`.
i	ID do Aplicativo no lado do Singular.
att_authorization_status	Código de status App Tracking Transparency (ATT).
n	Nome do evento. O comprimento máximo é de 32 caracteres.
is_revenue_event	Se o evento está vinculado à receita.
amt	Quantia.
cur	Moeda. Código de três letras da moeda, de acordo com a norma ISO 4217.
custom_user_id	CUID.
partner	Parceiro — `xsolla`.
e	Outros parâmetros personalizados (opcional).

Obrigado pelo seu feedback!

Avaliaremos sua mensagem e a usaremos para melhorar sua experiência.

Última atualização: 30 de Dezembro de 2025

Encontrou um erro de texto ou digitação? Selecione o texto e pressione Ctrl+Enter.

Conteúdos

Glossário
Fluxo de integração
Como funciona
Como configurar no Singular
Como configurar na Conta de Distribuidor
Como executar campanhas de anúncios no app e na web para a Web Shop
Como adicionar eventos Web/Web Shop no Singular
Como obter relatórios de desempenho de campanhas de anúncios da Web Shop no Singular
Como funciona
Como configurar na Conta de Distribuidor
Como configurar no Singular
Obtenção da chave SDK
Ative a integração com a Xsolla
Estrutura dos valores do evento
Compra de itens
Dados adicionais

Your browser is not supported. Please try a different browser

Integração com o Singular

Glossário

Singular

Singular Device ID (SDID)

ID de Aplicativo

Valor Vitalício (LTV)

Retorno Nos Gastos de Anúncios (ROAS)

Evento web

Evento no aplicativo

Aquisição de usuários

Redirecionamento

ID de Usuário do Cliente (Customer user ID, CUID)

Postback

Chave SDK

Segredo do SDK

Fluxo de integração

Como funciona

Como configurar no Singular

Como configurar na Conta de Distribuidor

Como executar campanhas de anúncios no app e na web para a Web Shop

Como adicionar eventos Web/Web Shop no Singular

Como obter relatórios de desempenho de campanhas de anúncios da Web Shop no Singular

Como funciona

Como configurar na Conta de Distribuidor

Como configurar no Singular

Obtenção da chave SDK

Ative a integração com a Xsolla

Estrutura dos valores do evento

Compra de itens

Dados adicionais