Server-to-Server - Fundamentos
Implemente a REST API da Singular para rastreamento completo do lado do servidor como alternativa à integração via SDK, permitindo controle total sobre a coleta, a transmissão e os fluxos de trabalho de atribuição de dados.
Escolhendo sua integração: SDK ou S2S? Se você puder incorporar um SDK de cliente, comece pela documentação de integração do SDK . Use Server-to-Server quando precisar de entrega de eventos do lado do servidor, estiver em uma plataforma sem SDK ou quiser controle total sobre a coleta de dados. Esta suíte cobre o caminho S2S e é a referência compartilhada para os guias S2S de Mobile, Web e PC/Console.
Visão geral
Caso de uso do Server-to-Server
A integração server-to-server (S2S) fornece endpoints da REST API para criar soluções completas de atribuição e análise executadas a partir da sua infraestrutura de backend, sem incorporar o SDK da Singular nos aplicativos cliente.
Abordagens de integração:
- S2S puro: Implementação 100% do lado do servidor, tratando o rastreamento de sessões e de eventos
- Híbrido: O SDK da Singular gerencia as sessões enquanto o lado do servidor trata o rastreamento de eventos
Padrão de integração híbrida
A integração híbrida combina o SDK da Singular para gerenciamento de sessões com a EVENT API do lado do servidor para rastreamento de eventos no backend, equilibrando a facilidade de implementação com a flexibilidade do lado do servidor.
Benefícios do modo híbrido:
- O SDK trata automaticamente a lógica complexa de sessões, o deep linking e a coleta de dados do dispositivo
- O servidor envia eventos para transações processadas nos sistemas de backend
- Redução da complexidade de implementação do lado do cliente
- Endpoint SESSION não é necessário — o SDK gerencia o ciclo de vida da sessão
Métodos de recuperação de dados do dispositivo:
- Fluxo gerenciado pelo cliente: Capture os dados necessários no cliente e encaminhe-os ao servidor por meio de uma API interna para uso com o endpoint EVENT da Singular
- Postback de BI interno: Configure o postback de BI interno da Singular para receber, em tempo real, um payload JSON com identificadores de dispositivo após uma instalação, um reengajamento ou eventos ( Guia de configuração )
Manutenção do grafo de dispositivos: Ambos os métodos exigem lógica do lado do servidor para manter o grafo de dispositivos. Quando o SDK detectar alterações no identificador do dispositivo, atualize o servidor de acordo para garantir um rastreamento preciso.
Recursos de implementação:
- Parâmetros obrigatórios do endpoint EVENT
- Guia de recuperação de dados do dispositivo (exemplos de código para iOS/Android)
Principais princípios de integração
| Princípio | Descrição |
|---|---|
| Flexibilidade | Controle total sobre a coleta de dados e o momento da transmissão |
| Paridade de recursos | Suporta todas as funcionalidades do SDK quando os dados adequados são fornecidos |
| Caminho de integração | Cliente → Seu servidor → API da Singular |
| Processamento em tempo real | Uma requisição por vez — sem suporte a processamento em lote |
| Fluxo sequencial | Os eventos devem ser processados cronologicamente |
| Sem deduplicação | A Singular não faz deduplicação — implemente a deduplicação do lado do servidor |
| Permanência dos dados | Dados em nível de dispositivo não podem ser excluídos após a ingestão — valide antes de enviar |
Requisitos de integração
A integração S2S pura exige a implementação de um pipeline de dados abrangente para o rastreamento de sessões e eventos.
- Coleta de dados: Colete os dados necessários dos aplicativos cliente
- Grafo de dispositivos: Encaminhe os dados ao servidor e mantenha o armazenamento dos identificadores de dispositivo
- Requisições de sessão: Envie notificações de sessão pela SESSION API
- Tratamento de respostas: Processe e repasse as respostas da Singular de volta ao aplicativo cliente
- Requisições de eventos: Encaminhe os eventos pela EVENT API
Guias S2S relacionados
Este artigo é a referência compartilhada para a suíte S2S. Use o guia que corresponde à sua plataforma e as referências de endpoint para obter todos os detalhes dos parâmetros.
Guias por plataforma
- Guia S2S de aplicativo mobile
- Guia de implementação S2S para Web
- Guia de integração de jogos para PC e Console
Referências de endpoint
- Referência da API do endpoint SESSION
- Referência da API do endpoint EVENT
- Referência do endpoint da API para PC e Console
Guias de recursos
Endpoints da REST API
A Singular fornece dois endpoints principais da REST API para o rastreamento de sessões e eventos server-to-server.
Endpoint de sessão
API de rastreamento de sessão
O endpoint SESSION notifica a Singular sobre eventos de abertura do aplicativo para inicializar sessões de usuário para atribuição e rastreamento de retenção.
GET https://s2s.singular.net/api/v1/launchReferência completa: Referência da API do endpoint SESSION
Endpoint de evento
API de rastreamento de eventos
O endpoint EVENT rastreia eventos e receita in-app para análise de atribuição e otimização de campanhas.
GET https://s2s.singular.net/api/v1/evtReferência completa: Referência da API do endpoint EVENT
Parâmetros comuns
Estes parâmetros são compartilhados entre os endpoints SESSION e EVENT da REST API S2S da Singular. Esta seção contém suas definições canônicas; outros artigos S2S apontam para cá em vez de redefini-los.
Autenticação
| Parâmetro | Detalhes |
|---|---|
a
|
SDK Key da Singular para autenticação na API. Obtenha em: Singular UI → Menu principal → Developer Tools . Importante: Não use a Reporting API Key. As requisições serão rejeitadas.
Exemplo:
|
Identificadores de dispositivo
Os identificadores de dispositivo variam conforme a plataforma e a disponibilidade. Inclua todos os identificadores aplicáveis à sua plataforma. Omita qualquer identificador indisponível — nunca passe NULL ou uma string vazia.
| Parâmetro | Detalhes |
|---|---|
idfa
|
Plataforma: iOS Identifier for Advertisers (IDFA) habilita o rastreamento de anúncios e a atribuição de campanhas. Requisito de ATT: O iOS 14.5+ exige o consentimento do usuário por meio do framework App Tracking Transparency.
Exemplo:
|
idfv
|
Plataforma: iOS Identifier for Vendors (IDFV) permanece consistente em todos os aplicativos do mesmo fornecedor. Sempre obrigatório: Deve ser incluído independentemente do status do ATT ou da disponibilidade do IDFA.
Exemplo:
|
aifa
|
Plataforma:
Android
Google Advertising ID (GAID) habilita o rastreamento de publicidade redefinível pelo usuário no Android.
Exemplo:
|
asid
|
Plataforma:
Android
Android App Set ID fornece rastreamento entre aplicativos com foco em privacidade para o mesmo desenvolvedor. Sempre obrigatório: Deve ser incluído em dispositivos Google Play independentemente da disponibilidade do GAID.
Exemplo:
|
amid
|
Plataforma:
Android
Amazon Advertising ID para dispositivos Amazon sem os Google Play Services.
Exemplo:
|
oaid
|
Plataforma:
Android
Open Advertising Identifier (OAID) para dispositivos fabricados na China sem os Google Play Services (Huawei, Xiaomi, OPPO etc.).
Exemplo:
|
andi
|
Plataforma:
Android
O Android ID é um identificador de 64 bits gerado pelo dispositivo. Uso restrito: Proibido em dispositivos Google Play — use AIFA e ASID em vez dele. Envie apenas se nenhum outro identificador estiver disponível e o aplicativo não for distribuído pela Google Play.
Exemplo:
|
sdid
|
Plataforma: iOS, Android, PC, Xbox, PlayStation, Nintendo, MetaQuest, CTV O Singular Device ID é um UUIDv4 anonimizado gerado pelo cliente que representa uma instalação única do aplicativo. Identificador principal: Único identificador de dispositivo relevante para aplicativos de PC e console.
Exemplo:
|
Parâmetros de dispositivo
| Parâmetro | Detalhes |
|---|---|
p
|
Plataforma do aplicativo. Valores permitidos (diferencia maiúsculas de minúsculas):
Exemplo:
|
ip
|
Exemplo:
|
ve
|
Exemplo:
|
ma
iOS, Android |
Marca do dispositivo (nome do fabricante). Deve ser usado com
Recuperar a marca do dispositivo
Exemplo:
|
mo
iOS, Android |
Modelo do dispositivo. Deve ser usado com
Recuperar o modelo do dispositivo
Exemplo:
|
lc
iOS, Android |
Tag de locale IETF — código de idioma e de país de duas letras separados por um sublinhado. Recuperar o locale do dispositivo
Exemplo:
|
bd
iOS, Android |
Identificador de build do dispositivo, codificado em URL. Recuperar o build do dispositivo
Exemplo:
|
Parâmetros do aplicativo
| Parâmetro | Detalhes |
|---|---|
i
|
Identificador do aplicativo (diferencia maiúsculas de minúsculas).
Exemplo:
|
app_v
|
Exemplo:
|
att_authorization_status
iOS |
Código de status do App Tracking Transparency (ATT) (iOS 14.5+). Valores de status:
Sempre obrigatório:
Mesmo que o ATT não seja implementado, passe
Exemplo:
|
Parâmetros de rede e localização
| Parâmetro | Detalhes |
|---|---|
use_ip
|
Instrui a Singular a extrair o endereço IP da requisição HTTP em vez do
Limitações:
Exemplo:
|
country
|
Código de país de duas letras ISO 3166-1 alpha-2 .
Obrigatório quando:
O endereço IP não estiver disponível ou
Exemplo:
|
ua
|
String de User Agent codificada em URL.
Bruto:
Exemplo:
|
c
iOS, Android |
Tipo de conexão de rede.
Valores permitidos:
Exemplo:
|
cn
iOS, Android |
Exemplo:
|
Parâmetros de privacidade de dados
| Parâmetro | Detalhes |
|---|---|
data_sharing_options
|
Consentimento do usuário final para compartilhamento de dados em JSON codificado em URL. Deve persistir e ser passado em todas as requisições SESSION e EVENT subsequentes. Usuário consentiu (opt-in): Usuário recusou (opt-out):
Exemplo:
|
dnt
iOS, Android |
Status de Do Not Track.
Exemplo:
|
dntoff
iOS, Android |
Indica se o Do Not Track está DESATIVADO.
Exemplo:
|
Suporte a múltiplos dispositivos
| Parâmetro | Detalhes |
|---|---|
custom_user_id
|
Seu ID de usuário interno para rastreamento entre dispositivos. Sem PII: Não passe informações de identificação pessoal. Use um identificador interno com hash ou anonimizado de outra forma, e não endereços de e-mail, números de telefone ou nomes brutos.
Exemplo:
|
Fases de implementação
Uma integração S2S bem-sucedida exige quatro fases principais de implementação executadas sequencialmente para obter qualidade de dados e precisão de atribuição ideais.
Fase 1: Coleta de dados
Dados necessários
Estabeleça uma estratégia robusta de coleta de dados que capture todos os parâmetros necessários para a funcionalidade da plataforma Singular.
Todos os parâmetros obrigatórios são mandatórios: Omitir parâmetros obrigatórios resulta em discrepâncias de dados e erros de atribuição. Nenhum parâmetro é opcional.
Tratamento de funções assíncronas: Ao coletar dados do lado do cliente para transmissão ao servidor, aguarde a conclusão das funções assíncronas e trate os casos extremos. Problema comum que causa dados ausentes e atribuição parcial.
Recursos de implementação:
- Parâmetros obrigatórios do endpoint SESSION
- Parâmetros obrigatórios do endpoint EVENT
- Guia de recuperação de dados do dispositivo (exemplos de código para iOS/Android)
- Guia de implementação do SKAdNetwork 4 (dados específicos do iOS)
Fase 2: Streaming em tempo real
Requisitos críticos de tempo
O streaming de dados em tempo real mantém a precisão da atribuição e habilita recursos sensíveis ao tempo, como as atualizações de conversion value do SKAdNetwork.
Impacto na atribuição:
- Sessões atrasadas: Afetam gravemente a precisão da atribuição — o sistema exige dados temporais precisos para a associação de campanhas
- Timer do SKAdNetwork: A rigorosa janela do timer no dispositivo para os conversion values torna o streaming em tempo real crítico. Atrasos causam a perda de atualizações de conversion value e dados de campanha incompletos
Boas práticas:
- Implemente listeners de eventos do lado do servidor para os inícios de sessão do aplicativo
- Encaminhe os dados de sessão imediatamente, com todos os parâmetros necessários
- Implemente listeners de eventos do lado do servidor para os eventos in-app
- Encaminhe os dados de eventos imediatamente, com todos os parâmetros necessários
- Use uma arquitetura de webhook para uma transmissão de dados confiável
- Implemente mecanismos de repetição para requisições que falharem
- Monitore o fluxo de dados para garantia de qualidade
Fase 3: Tratamento de respostas
Comunicação bidirecional
O tratamento de respostas conecta as interações da API do lado do servidor com a funcionalidade do lado do cliente, habilitando o deferred deep linking e as atualizações de conversion value.
Principais tipos de resposta:
- Deferred Deep Links: A resposta da API contém dados de deep link pendentes que exigem repasse imediato ao aplicativo para roteamento e personalização do usuário
- Conversion Values: Os conversion values do SKAdNetwork no iOS devem ser prontamente encaminhados ao aplicativo para uma medição de campanha precisa
Boas práticas:
- Implemente o tratamento de respostas na infraestrutura do servidor
- Faça o parsing e valide as respostas da API da Singular
- Encaminhe os dados de resposta relevantes ao aplicativo cliente (essencial para o SKAdNetwork no iOS)
- Implemente o processamento de respostas do lado do cliente
- Trate os erros de forma adequada com os códigos de status HTTP apropriados
- Registre as respostas com falha para os mecanismos de repetição
Fase 4: Testes e validação
Verificação do fluxo de dados
A fase de testes valida a funcionalidade completa do pipeline de dados e a precisão da atribuição antes da implantação em produção.
Processos de atribuição de sessão:
- Primeira sessão (nova instalação): A Singular reconhece a nova instalação e aciona o processo de atribuição de instalação
- Reengajamento qualificado: A Singular aciona o processo de atribuição de reengajamento ( FAQ de reengajamento )
- Sessão padrão: A Singular registra a sessão para as métricas de atividade e retenção do usuário
Requisitos críticos de tempo:
- Sessão antes dos eventos: Uma única SESSION deve ser recebida antes de quaisquer eventos. O SDK aciona a sessão na abertura do aplicativo e depois envia os eventos in-app. Após mais de 1 minuto em segundo plano, a sessão expira. Uma nova sessão é enviada quando o aplicativo retorna ao primeiro plano. Use eventos de ciclo de vida do aplicativo e timers para o gerenciamento de sessões
- Eventos em tempo real: Os eventos que ocorrem no aplicativo devem ser enviados em tempo real após a sua respectiva sessão
Checklist de validação:
- Teste o fluxo de dados de sessão — valide se a primeira e as sessões subsequentes têm os dados e valores corretos
- Confirme que os eventos são recebidos somente após a sessão ser reportada à Singular (eventos antes da sessão criam atribuição orgânica)
- Confirme que a resposta da sessão é tratada e repassada ao aplicativo cliente (crítico para os deferred deep links)
Integração concluída:
- ✓ Coleta e armazenamento de dados validados
- ✓ Streaming em tempo real para a Singular validado
- ✓ Tratamento de respostas e registro de logs validados
- ✓ Todos os fluxos de dados de teste validados
Guia de testes: Guia de testes de integração S2S
Recursos adicionais
Implemente rastreamento entre dispositivos, rastreamento de receita, monitoramento de desinstalações e conformidade com a privacidade de dados para uma análise abrangente.
Rastreamento entre dispositivos
Implementação do Custom User ID
Utilize o
custom_user_id
parâmetro para associar usuários a
sessões em nível de dispositivo para relatórios entre dispositivos e análises em nível de usuário.
Conformidade com privacidade:
Cumpra as políticas de privacidade de dados
evitando informações de identificação pessoal (PII) em
custom_user_id
. Use um nome de usuário com hash, e-mail ou uma string
gerada aleatoriamente como identificador de usuário único.
Habilita relatórios abrangentes entre dispositivos, exportações de dados em nível de usuário e postbacks de BI interno, mantendo a privacidade do usuário.
Mais informações: Parâmetro Custom User ID
Rastreamento de receita
Relatório de compras in-app
Rastreie a receita de compras in-app para análise de ROI, medição de desempenho de campanhas e enriquecimento de exportações/postbacks.
Use o endpoint EVENT com parâmetros de receita :
-
is_revenue_event: Marca o evento como evento de receita (pule se o nome do evento for__iap__ou o valor for > 0) -
purchase_receipt: Objeto de compra in-app do Android/iOS — altamente recomendado para detalhes da transação e enriquecimento de relatórios -
receipt_signature(Android): Altamente recomendado para validação de transações e prevenção de fraudes -
amt: Valor da receita como Double (por exemplo, "amt=1.99") -
cur: Código de moeda ISO 4217 (por exemplo, "cur=USD")
Guia de implementação: Gerenciamento do estado de assinaturas
Conformidade com a privacidade de dados
Tratamento do consentimento do usuário
Notifique a Singular sobre o consentimento do usuário final para compartilhamento de dados a fim de cumprir o GDPR, a CCPA e outras regulamentações de privacidade.
Use o
data_sharing_options
parâmetro para comunicar a escolha do usuário:
-
{"limit_data_sharing":false}: O usuário consentiu (opt-in) em compartilhar informações -
{"limit_data_sharing":true}: O usuário recusou compartilhar informações
A Singular usa o
limit_data_sharing
nos
Postbacks de privacidade do usuário
e repassa as informações aos parceiros que exigem conformidade.
Opcional, mas recomendado: Parâmetro opcional, mas algumas informações de atribuição só são compartilhadas pelos parceiros quando o usuário fez explicitamente o opt-in.
Mais informações: Privacidade do usuário e Limit Data Sharing