Server-to-Server - Guia de Integração

Implemente a REST API da Singular para tracking completo no lado do servidor como alternativa à integração via SDK, permitindo controle total sobre coleta, transmissão de dados e fluxos de atribuição.

Visão geral

Caso de uso Server-to-Server

A integração server-to-server (S2S) fornece endpoints REST API para construir soluções completas de atribuição e analytics executadas a partir da sua infraestrutura de backend, sem incorporar o Singular SDK nas aplicações cliente.

Abordagens de integração:

• S2S puro: implementação 100% no lado do servidor, lidando com o tracking tanto de sessão quanto de eventos
• Híbrido: o Singular SDK gerencia as sessões enquanto o lado do servidor lida com o tracking de eventos

Padrão de integração híbrida

A integração híbrida combina o Singular SDK para gerenciamento de sessões com a EVENT API no lado do servidor para o tracking de eventos no backend, equilibrando facilidade de implementação com flexibilidade no lado do servidor.

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

1. Fluxo gerenciado pelo cliente: capture os pontos de dados necessários no cliente e os encaminhe ao servidor por meio de uma API interna para uso com o endpoint EVENT da Singular
2. Postback de BI interno: configure o postback de BI interno da Singular para receber, em tempo real, um payload JSON com os identificadores de dispositivo após install, re-engajamento ou eventos ( Guia de configuração )

Recursos de implementação:

• Parâmetros obrigatórios do endpoint EVENT
• Guia de obtenção de dados do dispositivo (exemplos de código iOS/Android)

Princípios-chave de integração

Requisitos de integração

A integração S2S pura exige a implementação de um pipeline de dados abrangente para o tracking de sessão e eventos.

1. Coleta de dados: colete os pontos de dados necessários a partir das aplicações cliente
2. Device graph: encaminhe os dados ao servidor e mantenha o armazenamento dos identificadores de dispositivo
3. Requisições de sessão: envie notificações de sessão via SESSION API
4. Tratamento de respostas: processe e repasse as respostas da Singular de volta ao app cliente
5. Requisições de eventos: encaminhe os eventos via EVENT API

Endpoints REST API

A Singular fornece dois endpoints REST API principais para o tracking de sessão e eventos server-to-server.

Endpoint de sessão

API de tracking de sessão

O endpoint SESSION notifica a Singular sobre eventos de abertura do app para inicializar as sessões do usuário para tracking de atribuição e retenção.

GET https://s2s.singular.net/api/v1/launch

Referência completa: Referência da API do endpoint SESSION

Endpoint de evento

API de tracking de eventos

O endpoint EVENT rastreia eventos in-app e receita para análise de atribuição e otimização de campanhas.

GET https://s2s.singular.net/api/v1/evt

Referência completa: Referência da API do endpoint EVENT

Fases de implementação

Uma integração S2S bem-sucedida exige quatro fases-chave de implementação executadas de forma sequencial para qualidade de dados e precisão de atribuição ideais.

Fase 1: Coleta de dados

Pontos de dados necessários

Estabeleça uma estratégia robusta de coleta de dados que capture todos os parâmetros necessários para o funcionamento da plataforma Singular.

Recursos de implementação:

• Parâmetros obrigatórios do endpoint SESSION
• Parâmetros obrigatórios do endpoint EVENT
• Guia de obtenção de dados do dispositivo (exemplos de código iOS/Android)
• Guia de implementação do SKAdNetwork 4 (pontos de dados específicos de iOS)

Fase 2: Streaming em tempo real

Requisitos críticos de timing

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.

Melhores práticas:

• Implemente event listeners no lado do servidor para os inícios de sessão do app
• Encaminhe os dados de sessão imediatamente com todos os parâmetros obrigatórios
• Implemente event listeners no lado do servidor para eventos in-app
• Encaminhe os dados de evento imediatamente com todos os parâmetros obrigatórios
• Use uma arquitetura de webhook para uma transmissão de dados confiável
• Implemente mecanismos de retry para requisições com falha
• 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 no lado do servidor com a funcionalidade no 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 app para roteamento e personalização do usuário
• Conversion values: os conversion values do SKAdNetwork no iOS devem ser prontamente encaminhados ao app para uma medição de campanha precisa

Melhores práticas:

• Implemente o tratamento de respostas na infraestrutura do servidor
• Faça o parsing e a validação das respostas da Singular API
• Encaminhe os dados de resposta relevantes ao app cliente (essencial para o SKAdNetwork no iOS)
• Implemente o processamento de respostas no lado do cliente
• Trate os erros de forma adequada com os códigos de status HTTP corretos
• Registre as respostas com falha para os mecanismos de retry

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 (novo install): a Singular reconhece o novo install e dispara o processo de atribuição de install
• Re-engajamento qualificado: a Singular dispara 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 do usuário

Checklist de validação:

• Teste o fluxo de dados de sessão—valide que a primeira sessão e as subsequentes tenham 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 app cliente (crítico para os deferred deep links)

Guia de testes: Guia de testes de integração S2S

Recursos avançados

Aprimore a integração S2S com tratamento avançado de atribuição, deep linking, tracking entre dispositivos e capacidades específicas de cada plataforma.

Atribuição do Apple Search Ads

Integração do Search Ads no iOS

O Apple Search Ads é uma Self-Attributing Network (SAN) que exige uma implementação de atribuição específica da plataforma por meio dos frameworks da Apple.

Suporte de frameworks:

• iOS 14.2 e anteriores: framework iAd
• iOS 14.3 e superiores: framework AdServices (recomendado)

Guia completo: Documentação de integração do Apple Search Ads

Implementação do framework iAd

Obtenha e envie os dados de atribuição do Apple Search Ads por meio do framework iAd para iOS 14.2 e anteriores.

Etapa 1: Obter os dados de atribuição

#import <iAd/iAd.h>

Class ADClientClass = NSClassFromString(@"ADClient");

if (ADClientClass) {
    id sharedClient = [ADClientClass performSelector:@selector(sharedClient)];

    if ([sharedClient respondsToSelector:@selector(requestAttributionDetailsWithBlock:)]) {
        [sharedClient requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error) {
            if (attributionDetails && attributionDetails.count  0) {
                // REPORT attributionDetails FROM YOUR APP TO YOUR SERVER
            }
        }];
    }
}

Etapa 2: Enviar à Singular

Reporte um evento com o nome reservado __iAd_Attribution__ via endpoint EVENT , passando o JSON de atribuição como o parâmetro e .

Implementação do framework AdServices

Obtenha e envie o attribution token por meio do framework AdServices para iOS 14.3 e superiores.

Etapa 1: Obter o attribution token

#import <AdServices/AdServices.h>

NSError *error = nil;
Class AAAttributionClass = NSClassFromString(@"AAAttribution");
if (AAAttributionClass) {
    NSString *attributionToken = [AAAttributionClass attributionTokenWithError:&error];
    if (!error && attributionToken) {
        // Handle attributionToken
    }
}

Etapa 2: Enviar à Singular

Faça o URL-encode do token e o anexe ao endpoint SESSION como o parâmetro attribution_token na primeira sessão após cada install e reinstall.

Google Play Install Referrer

Atribuição de install no Android

O Google Play Install Referrer fornece a atribuição de install mais precisa do Android, contendo informações sobre a origem do usuário antes da chegada à Play Store.

Mais informações: Documentação do Google Install Referrer

Etapas de implementação:

1. Obtenha o install referrer na primeira abertura do app usando a Play Install Referrer API
2. Reporte a sessão via endpoint SESSION incluindo o parâmetro JSON install_ref com os atributos obrigatórios

Atributos de install_ref:

Meta Install Referrer

Aprimoramento da atribuição do Facebook

O Meta Referrer é uma solução de medição específica do Android que fornece dados granulares de atribuição em nível de usuário para installs de apps, combinando as tecnologias Google Play Install Referrer e Meta Install Referrer.

Saiba mais: FAQ do Meta Referrer

Etapas de implementação:

1. Obtenha o Meta install referrer na primeira abertura do app conforme a documentação da Meta
2. Reporte a sessão via endpoint SESSION incluindo o parâmetro JSON meta_ref com os atributos obrigatórios

Atributos de meta_ref:

Singular Links e Deep Linking

Implemente o deep linking e o deferred deep linking para os tracking links da Singular, de modo que os usuários passem de uma campanha diretamente para uma tela específica do seu app.

Um deep link é um link clicável que abre um conteúdo específico dentro de um app. Há dois cenários a suportar:

• Deep link (direto): o usuário já tem o app instalado. Ele toca em um Singular Link e o app abre diretamente no conteúdo correto.
• Deferred deep link (DDL): o usuário ainda não tem o app. Ele toca no link, instala a partir da loja e, na primeira abertura, o app ainda o direciona ao conteúdo pretendido.

Com uma integração via SDK, a Singular lida com a maior parte disso automaticamente. Em uma integração server-to-server (S2S) não há SDK no dispositivo, portanto a sua equipe é responsável por duas tarefas adicionais: repassar à Singular o deep link que o seu app recebeu e ler o deferred deep link que a Singular retorna para rotear o usuário. Ambas fluem pelo endpoint SESSION:

GET https://s2s.singular.net/api/v1/launch

Recursos: FAQ de Deep Linking | FAQ de Singular Links

As três configurações em resumo

Etapa 1: Configuração em nível do app

Antes que qualquer deep link possa funcionar, os Singular Links devem ser reconhecidos pelo sistema operacional como iOS Universal Links e Android App Links, de modo que tocar em um link abra o seu app em vez de um navegador. Os esquemas de URI de app tradicionais são suportados como fallback.

Siga os guias de configuração canônicos para as etapas detalhadas de cada plataforma e, em seguida, confirme que cada item abaixo está concluído. As etapas detalhadas estão em Pré-requisitos dos Singular Links e Como configurar Deep Links. O checklist aqui fornece a ordem necessária e os pontos que as equipes mais costumam esquecer.

Checklist de configuração:

1. Adicione um subdomínio de link em Attribution > Manage Links > Manage Link Domains (por exemplo yourbrand.sng.link). Esse é o host usado pelos seus Singular Links.
2. iOS — Universal Links: habilite a capability Associated Domains para applinks:yourbrand.sng.link, depois copie o seu App Prefix / Team ID do Apple Developer Portal para Settings > Apps > [iOS app] > Show Advanced Settings. Opcionalmente, registre um fallback de app-scheme como um URL Type no Xcode.
3. Android — App Links: gere os seus fingerprints de assinatura SHA-256 (Play Console para produção, keytool para debug), adicione um intent filter autoVerify para o seu domínio Singular ao AndroidManifest.xml e, em seguida, cole o fingerprint em Settings > Apps > [Android app] > Show Advanced Settings > App Links SHA256 fingerprints.
4. Defina os deep links em Attribution > Manage Links > Create Link (veja o mapeamento de campos abaixo).

Mapeando os campos de redirecionamento do Manage Links

Ao criar o link, três campos de redirecionamento mapeiam diretamente para os três conceitos de deep link usados posteriormente na API:

Handoff para o time de desenvolvimento: a engenharia deve fornecer o(s) esquema(s) de deep link por plataforma e a lista de URLs de destino (por exemplo myapp://autumnfashion).

Etapa 2: SESSION (entrada) — envie o deep link à Singular

Quando o app abre a partir de um Singular Link, capture a URL de abertura completa e a envie à Singular na requisição SESSION pelo parâmetro openuri (URL-encoded). É assim que a Singular atribui a sessão ao link e reporta o resultado do deep link. Obrigatório ao usar Singular Links.

Parâmetros de Singular Link presentes na URL

Capture a URL de abertura no app

O app precisa de um código handler que receba a URL de abertura e a encaminhe ao seu servidor para inclusão na requisição SESSION.

iOS (Swift):

// Custom scheme / direct opens
func scene(_ scene: UIScene,
           openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    SessionReporter.report(openURL: url.absoluteString)
}

// Universal Links arrive via:
func scene(_ scene: UIScene,
           continue userActivity: NSUserActivity) {
    if let url = userActivity.webpageURL {
        SessionReporter.report(openURL: url.absoluteString)
    }
}

Android (Kotlin):

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    intent?.data?.let { uri ->
        SessionReporter.report(uri.toString())
    }
}

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    intent?.data?.let { SessionReporter.report(it.toString()) }
}

Envie a requisição SESSION com openuri

A partir do seu servidor, inclua a URL capturada (URL-encoded) como openuri:

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "openuri=myapp://home/page?queryparam1=value1"

Resolução de short link

Se o usuário abriu um Singular Link encurtado, envie também singular_link_resolve_required=true. A Singular retorna o long link expandido para que você possa fazer o parsing do deep link e dos valores de passthrough.

Exemplo de resposta:

{
  "status": "ok",
  "resolved_singular_link": "https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue"
}

Parâmetros de passthrough dinâmico

Se a sua organização configurou o passthrough dinâmico para um link, a URL do deep link inclui o parâmetro _p com uma string JSON URL-encoded ou uma string não estruturada para roteamento de conteúdo. Veja Parâmetros de Passthrough Dinâmico.

Referência: Referência da API do endpoint SESSION (Deep Linking Parameters).

Etapa 3: SESSION (saída) — repasse o deferred deep link ao app

Para um usuário que instala o app após tocar no link, o deferred deep link é retornado pela Singular na resposta SESSION na primeira sessão após o install. Seu servidor deve repassar esse valor de volta ao app para que ele possa rotear o usuário.

Solicite o DDL na primeira sessão

Na primeira requisição SESSION após um install, adicione estes dois parâmetros:

Exemplo de requisição SESSION (install + DDL habilitado):

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "install=true" \
  --data-urlencode "ddl_enabled=true"

Leia a resposta e a repasse ao app

Se o install veio de um tracking link que carregava um deferred deep link, a Singular retorna:

Exemplo de resposta SESSION:

{
  "deferred_deeplink": "myapp://deferred-deeplink",
  "status": "ok",
  "deferred_passthrough": "passthroughvalue"
}

Testes e validação

• Deferred deep link: em um dispositivo sem o app, toque no link e confirme que você chega à loja. Instale e abra, e o app deve exibir o conteúdo pretendido.
• Deep link direto: com o app instalado, toque no link e confirme que o app abre diretamente no conteúdo pretendido.
• Ordenação da SESSION: confirme que uma única SESSION é recebida antes de qualquer evento e que a resposta SESSION é parseada e repassada ao cliente (crítico para os deferred deep links).
• openuri preenchido: verifique que as aberturas por deep link enviam uma SESSION com openuri definido, independentemente da janela de timeout.

Guias de testes: Teste sua integração | Teste um Tracking Link

Recursos adicionais

Implemente tracking entre dispositivos, tracking de receita, monitoramento de desinstalação e conformidade de privacidade de dados para uma analytics abrangente.

Tracking entre dispositivos

Implementação de Custom User ID

Utilize o parâmetro custom_user_id para associar usuários a sessões em nível de dispositivo para relatórios entre dispositivos e analytics em nível de usuário.

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

Tracking de receita

Reporte de compras in-app

Rastreie a receita de compras in-app para análise de ROI, medição de desempenho de campanha 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 (ignore se o nome do evento for __iap__ ou o valor > 0)
• purchase_receipt : objeto In-App Purchase de Android/iOS—altamente recomendado para detalhes da transação e enriquecimento de relatórios
• receipt_signature (Android): altamente recomendado para validação de transação e prevenção de fraude
• 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 de estado de assinatura

Tracking de desinstalação

Configuração de silent push notification

Rastreie as desinstalações usando silent push notifications do dispositivo, enviando o push token a cada notificação de sessão.

Requisitos de configuração:

1. Siga a configuração de tracking de desinstalação específica da plataforma:
   • Configuração de tracking de desinstalação no iOS
   • Configuração de tracking de desinstalação no Android
2. Anexe o token específico da plataforma à requisição SESSION:
   • iOS: apns_token (token de dispositivo APNs)
   • Android: fcm (token de dispositivo FCM)

iOS Install Receipt

Validação de receipt

Passe o iOS install receipt no parâmetro install_receipt ao reportar a sessão de iOS.

import Foundation
import StoreKit

class ReceiptManager {
    static func getInstallReceipt() - String? {
        if #available(iOS 18.0, *) {
            let semaphore = DispatchSemaphore(value: 0)
            var result: String?

            Task {
                do {
                    let transaction = try await AppTransaction.shared
                    result = transaction.jwsRepresentation
                    semaphore.signal()
                } catch {
                    debugPrint("Failed to get app transaction: \(error.localizedDescription)")
                    semaphore.signal()
                }
            }

            semaphore.wait()
            return result

        } else {
            guard let receiptURL = Bundle.main.appStoreReceiptURL else {
                debugPrint("Receipt URL not found")
                return nil
            }

            do {
                let receiptData = try Data(contentsOf: receiptURL, options: .uncached)
                return receiptData.base64EncodedString(options: [])
            } catch {
                debugPrint("Failed to read receipt: \(error.localizedDescription)")
                return nil
            }
        }
    }
}

Conformidade de 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, a 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 (opted-in) em compartilhar informações
• {"limit_data_sharing":true} : o usuário recusou compartilhar informações

A Singular usa limit_data_sharing nos User Privacy Postbacks e repassa as informações aos parceiros que exigem conformidade.

Mais informações: User Privacy e Limit Data Sharing