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 coleta, transmissão e fluxos de trabalho de atribuição de dados.

Escolhendo sua integração: SDK ou S2S? Se você puder incorporar um SDK 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 de S2S para Mobile, Web e PC/Console.

Visão geral

Caso de uso Server-to-Server

A integração server-to-server (S2S) fornece endpoints da REST API para construir 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, lidando com o rastreamento de sessões e de eventos
Híbrido: O SDK da Singular gerencia as sessões enquanto o lado do servidor lida com o rastreamento de eventos

Integração S2S pura

O S2S puro é uma implementação totalmente do lado do servidor: seu backend coleta os dados necessários, mantém o device graph e entrega tanto as sessões quanto os eventos para a Singular. Consulte as Fases de implementação abaixo para o pipeline passo a passo.

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 facilidade de implementação com flexibilidade do lado do servidor.

Benefícios do modelo híbrido:

O SDK lida automaticamente com a lógica complexa de sessões, deep linking e coleta de dados do dispositivo
O servidor envia eventos para transações processadas nos sistemas de backend
Menor complexidade de implementação do lado do cliente
O endpoint SESSION não é necessário—o SDK gerencia o ciclo de vida da sessão

Fluxo de dados S2S híbrido

Métodos de recuperação de dados do dispositivo:

Fluxo gerenciado pelo cliente: Capture os pontos de 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 Internal BI da Singular para receber um payload JSON em tempo real com identificadores de dispositivo após instalação, re-engajamento ou eventos ( Guia de configuração )

Manutenção do device graph: Ambos os métodos exigem lógica do lado do servidor para manter o device graph. Quando o SDK detectar alterações no identificador do dispositivo, atualize o servidor de acordo para garantir um rastreamento preciso.

Recursos relacionados:

Guia de recuperação de dados do dispositivo (exemplos de código iOS/Android)

Princípios-chave da integração

Esses princípios se aplicam a toda integração S2S, seja qual for sua plataforma ou abordagem:

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 corretos 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 em ordem cronológica
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

Fases de implementação

Uma integração S2S completa passa por quatro fases, executadas em ordem, cada uma construída sobre a anterior.

Fase 1: Coleta de dados

Pontos de dados necessários

Configure a coleta de dados que capture todos os parâmetros necessários, para que a Singular tenha tudo o que precisa para atribuir e reportar com precisão.

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 perda de dados 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 iOS/Android)
Guia de implementação do SKAdNetwork 4 (pontos de dados específicos do iOS)

Fase 2: Streaming em tempo real

Requisitos críticos de temporização

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: Impactam severamente a precisão da atribuição—o sistema requer dados temporais precisos para a associação de campanhas
Timer do SKAdNetwork: A rígida janela do timer no dispositivo para conversion values torna o streaming em tempo real crítico. Atrasos causam atualizações de conversion value perdidas e dados de campanha incompletos

Boas práticas:

Implemente event listeners do lado do servidor para os inícios de sessão do app
Encaminhe os dados de sessão imediatamente com todos os parâmetros necessários
Implemente event listeners do lado do servidor para os eventos in-app
Encaminhe os dados de evento imediatamente com todos os parâmetros necessários
Use uma arquitetura de webhook para uma transmissão de dados confiável
Implemente mecanismos de retry 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 chamadas de API do lado do servidor de volta ao aplicativo cliente, que é o que habilita 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 app para roteamento e personalização do usuário
Conversion values: Os conversion values do SKAdNetwork do iOS devem ser encaminhados prontamente ao app para uma medição de campanha precisa

Boas práticas:

Implemente o tratamento de respostas na infraestrutura do servidor
Analise e valide as respostas da API da Singular
Encaminhe os dados de resposta relevantes ao aplicativo cliente (essencial para o SKAdNetwork do iOS)
Implemente o processamento de respostas do lado do cliente
Trate os erros de forma adequada com os códigos de status HTTP corretos
Registre em log as respostas que falharem para os mecanismos de retry

Fase 4: Testes & Validação

Verificação do fluxo de dados

Antes de implantar em produção, valide todo o pipeline de dados de ponta a ponta e confirme que a atribuição está precisa.

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
Re-engajamento qualificado: A Singular aciona o processo de atribuição de re-engajamento ( FAQ de re-engajamento )
Sessão padrão: A Singular registra a sessão para métricas de atividade e retenção de usuários

Requisitos críticos de temporização:

Sessão antes dos eventos: Uma única SESSION deve ser recebida antes de qualquer evento. O SDK aciona a sessão na abertura do app e, em seguida, 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 app retorna ao primeiro plano. Use eventos de ciclo de vida do app e timers para o gerenciamento de sessões
Eventos em tempo real: Os eventos que ocorrem no app devem ser enviados em tempo real após a respectiva sessão

Checklist de validação:

Teste o fluxo de dados de sessão—valide se a primeira sessão e as subsequentes têm os pontos de dados e valores corretos
Confirme que os eventos são recebidos apenas 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 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 logging 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 privacidade de dados para uma análise abrangente.

Rastreamento entre dispositivos

Implementação de Custom User ID

Aproveite o parâmetro custom_user_id para associar usuários a sessões em nível de dispositivo para relatórios entre dispositivos e análise 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) no custom_user_id . Use um nome de usuário com hash, e-mail ou uma string gerada aleatoriamente como identificador único de usuário.

Permite relatórios abrangentes entre dispositivos, exportações de dados em nível de usuário e postbacks de Internal BI, 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: Defina como true para um evento de receita; false caso contrário.
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 privacidade de dados

Tratamento do consentimento do usuário

Notifique a Singular sobre o consentimento do usuário final para o compartilhamento de dados a fim de cumprir o GDPR, o CCPA e outras regulamentações de privacidade.

Use o parâmetro data_sharing_options 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 User Privacy Postbacks e repassa as informações aos parceiros que exigem conformidade.

Opcional, mas recomendado: O parâmetro é opcional, mas algumas informações de atribuição só são compartilhadas pelos parceiros quando o usuário fez opt-in explicitamente.

Mais informações: Privacidade do usuário e Limit Data Sharing

Referência de endpoints

Cada referência de endpoint documenta inline seus parâmetros obrigatórios e opcionais completos. Para as tabelas completas de parâmetros, consulte o seguinte:

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 o detalhamento completo dos parâmetros.

Guias por plataforma

Guias de recursos