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

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

Visão geral

Caso de uso de servidor para servidor

A integração servidor-para-servidor (S2S) fornece pontos de extremidade da API REST para criar soluções completas de atribuição e análise executadas a partir de sua infraestrutura de back-end sem incorporar o SDK da Singular em aplicativos clientes.

Abordagens de integração:

• S2S puro: implementação 100% do lado do servidor que lida com rastreamento de sessões e eventos
• Híbrido: O Singular SDK gerencia as sessões enquanto o lado do servidor lida com o rastreamento de eventos

Padrão de integração híbrida

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

Métodos de recolha de dados do dispositivo:

1. Fluxo gerido pelo cliente: captura os pontos de dados necessários no cliente e encaminha para o servidor através da API interna para utilização com o ponto de extremidade Singular EVENT
2. Postback de BI Interno: Configurar o postback do Singular Internal BI para receber uma carga JSON em tempo real com identificadores de dispositivo após a instalação, reengajamento ou eventos(Guia de Configuração)

Recursos de implementação:

• Parâmetros necessários do ponto de extremidade EVENT
• Guia de recuperaçã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 requer uma implementação abrangente do pipeline de dados para rastreamento de sessões e eventos.

1. Recolha de dados: Recolher os pontos de dados necessários a partir de aplicações cliente
2. Gráfico do dispositivo: Encaminhar dados para o servidor e manter o armazenamento de identificadores de dispositivos
3. Pedidos de sessão: Enviar notificações de sessão através da API SESSION
4. Tratamento de respostas: Processar e retransmitir respostas Singular de volta à aplicação cliente
5. Pedidos de eventos: Encaminhar eventos através da API EVENT

Pontos de extremidade da API REST

O Singular fornece dois endpoints primários da API REST para rastreamento de sessões e eventos de servidor para servidor.

Ponto final de sessão

API de rastreamento de sessão

O endpoint SESSION notifica a Singular sobre eventos de abertura de aplicativos para inicializar sessões de usuários para rastreamento de atribuição e retenção.

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

Referência completa: Referência da API do ponto de extremidade SESSION

Ponto de extremidade de evento

API de rastreamento de eventos

O endpoint EVENT rastreia eventos e receitas in-app 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 ponto de extremidade EVENT

Fases de implementação

A integração bem-sucedida do S2S requer quatro fases principais de implementação executadas sequencialmente para obter a melhor qualidade de dados e precisão de atribuição.

Fase 1: Coleta de dados

Pontos de dados necessários

Estabelecer uma estratégia robusta de coleta de dados capturando todos os parâmetros necessários para a funcionalidade da plataforma Singular.

Recursos de implementação:

• Parâmetros necessários do ponto de extremidade SESSION
• Parâmetros necessários do ponto de extremidade EVENT
• Guia de recuperação de dados do dispositivo(exemplos de código iOS/Android)
• Guia de implementação da SKAdNetwork 4(pontos de 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 permite recursos sensíveis ao tempo, como atualizações do valor de conversão da SKAdNetwork.

Melhores práticas:

• Implementar ouvintes de eventos do lado do servidor para o início da sessão da aplicação
• Encaminhar imediatamente os dados da sessãocom todos os parâmetros necessários
• Implementar ouvintes de eventos do lado do servidor para eventos in-app
• Reencaminhar imediatamente os dados do eventocom todos os parâmetros necessários
• Utilizar a arquitetura webhook para uma transmissão de dados fiável
• Implementar mecanismos de repetição para pedidos falhados
• Monitorizar o fluxo de dados para garantir a qualidade

Fase 3: Tratamento de respostas

Comunicação bidirecional

O tratamento de respostas faz a ponte entre as interações da API do lado do servidor e a funcionalidade do lado do cliente, permitindo ligações profundas diferidas e actualizações de valores de conversão.

Principais tipos de resposta:

• Deep Links diferidos: A resposta da API contém dados de deep link pendentes que requerem retransmissão imediata para a aplicação para encaminhamento e personalização do utilizador
• Valores de conversão: os valores de conversão de SKAdNetwork para iOS devem ser encaminhados imediatamente para o aplicativo para uma mensuração precisa da campanha

Melhores práticas:

• Implementar o tratamento de respostas na infraestrutura do servidor
• Analisar e validar respostas da API Singular
• Encaminhar dados de resposta relevantes para o aplicativo cliente (essencial para iOS SKAdNetwork)
• Implementar o processamento de respostas no lado do cliente
• Tratar os erros de forma graciosa com códigos de estado HTTP adequados
• Registar respostas falhadas para mecanismos de repetição

Fase 4: Teste e validação

Verificação do fluxo de dados

A fase de teste valida a funcionalidade completa do pipeline de dados e a precisão da atribuição antes da implementação na produção.

Processos de atribuição de sessão:

• Primeira sessão (nova instalação): O Singular reconhece a nova instalação e aciona o processo de atribuição de instalação
• Reengajamento qualificado: O Singular aciona o processo de atribuição de reengajamento(FAQ sobre reengajamento)
• Sessão padrão: A Singular registra a sessão para métricas de atividade e retenção de usuários

Lista de verificação de validação:

• Testar o fluxo de dados da sessão - validar se a primeira sessão e as subsequentes têm pontos e valores de dados corretos
• Confirmar eventos recebidos somente após a sessão reportada à Singular (eventos antes da sessão criam atribuição orgânica)
• Confirmar se a resposta da sessão foi tratada e passada para o aplicativo cliente (essencial para deep links diferidos)

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

Funcionalidades avançadas

Melhore a integração do S2S com tratamento avançado de atribuição, deep linking, rastreamento entre dispositivos e recursos específicos da plataforma.

Atribuição de anúncios de pesquisa da Apple

Integração de anúncios de pesquisa do iOS

O Apple Search Ads é uma rede de auto-atribuição (SAN) que requer a implementação de atribuição específica da plataforma através de estruturas da Apple.

Suporte de estruturas:

• iOS 14.2 e inferior: estrutura iAd
• iOS 14.3 e superior: estrutura AdServices(recomendada)

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

Implementação da estrutura iAd

Recupere e envie dados de atribuição do Apple Search Ads por meio da estrutura iAd para iOS 14.2 e posterior.

Passo 1: Recuperar 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
            }
        }];
    }
}

Passo 2: Enviar para o Singular

Reportar evento com o nome reservado __iAd_Attribution__ através do ponto de extremidade EVENT, passando o JSON de atribuição como parâmetro e.

Implementação da estrutura de AdServices

Recupere e envie o token de atribuição através da estrutura AdServices para iOS 14.3 e superior.

Passo 1: Recuperar o Token de atribuição

#import <AdServices/AdServices.h>

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

Passo 2: Enviar para o Singular

URL - codificar o token e anexar ao ponto de extremidade SESSIONcomo parâmetro attribution_token na primeira sessão após cada instalação e reinstalação.

Referenciador de instalação do Google Play

Atribuição de instalação do Android

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

Mais informações: Documentação do referenciador de instalação do Google

Etapas de implementação:

1. Recuperar o referenciador de instalação na primeira abertura de aplicativo usando a API de referenciador de instalação do Play
2. Comunicar a sessão através do ponto final SESSION, incluindo o parâmetro install_ref JSON com os atributos necessários

install_ref Atributos:

Meta Referenciador de instalação

Aprimoramento da atribuição do Facebook

O Meta Referrer é uma solução de mensuração específica para Android que fornece dados granulares de atribuição no nível do usuário para instalações de aplicativos, combinando as tecnologias Google Play Install Referrer e Meta Install Referrer.

Saiba mais: FAQ do Meta Referrer

Etapas de implementação:

1. Recupere o referenciador de instalação do Meta na primeira abertura do aplicativo de acordo com a documentação do Meta
2. Relatar a sessão por meio do ponto de extremidade SESSION, incluindo o parâmetro meta_ref JSON com os atributos necessários

Atributos meta_ref:

Links Singulares & Deep Linking

Implemente o suporte a deep linking e deferred deep linking para links de rastreamento Singular para permitir experiências de usuário perfeitas de campanhas para conteúdo específico no aplicativo.

As ligações profundas são ligações clicáveis que conduzem os utilizadores a conteúdos específicos dentro das aplicações. Quando o usuário clica no deep link em um dispositivo com o aplicativo instalado, o aplicativo é aberto e mostra o produto ou a experiência específica.

Recursos: Perguntas frequentes sobre linksprofundos | Perguntas frequentes sobre links singulares

Pré-requisitos

Configuração da plataforma

O aplicativo cliente deve reconhecer os Singular Links como iOS Universal Links ou Android App Links.

Guia de configuração: Pré-requisitos de Singular Links

Implementação do Deep Link

Capturando links profundos

Quando o aplicativo for aberto por meio de um link profundo, capture e adicione openURL à solicitação SESSION anexando o valor da URL ao parâmetro openuri. Necessário ao usar links singulares.

Parâmetros de link singular:

• _ios_dl e _android_dl: Presente quando o link é gerado com diferentes valores de deep link por plataforma
• _dl Presente quando os valores do deep link são os mesmos para iOS e Android
• _p Presente quando o parâmetro passthrough está incluído

Código do manipulador de links profundos

O aplicativo deve ter um código de manipulador analisando openURL e manipulando os parâmetros do Singular Link adequadamente.

class DeepLinkHandler {
    func handleURL(_ url: URL) {
        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: true) else {
            return
        }

        var params: [String: String] = [:]

        // Parse query parameters
        if let queryItems = components.queryItems {
            for item in queryItems {
                switch item.name {
                case "_dl":
                    params["deeplink"] = item.value
                case "_ios_dl":
                    params["ios_deeplink"] = item.value
                case "_p":
                    params["passthrough"] = item.value
                default:
                    break
                }
            }
        }

        // Handle the parsed parameters
        processDeepLinkParameters(params)
    }

    private func processDeepLinkParameters(_ params: [String: String]) {
        // Process the parameters as needed
        print("Processed parameters: \(params)")
    }
}

// In SceneDelegate or AppDelegate
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    let handler = DeepLinkHandler()
    handler.handleURL(url)
}

class DeepLinkHandler {
    fun handleDeepLink(intent: Intent) {
        val data: Uri? = intent.data

        data?.let { uri ->
            val params = mutableMapOf<String, String>()

            // Parse query parameters
            uri.queryParameterNames?.forEach { name ->
                when (name) {
                    "_dl" -> params["deeplink"] = uri.getQueryParameter(name) ?: ""
                    "_android_dl" -> params["android_deeplink"] = uri.getQueryParameter(name) ?: ""
                    "_p" -> params["passthrough"] = uri.getQueryParameter(name) ?: ""
                }
            }

            processDeepLinkParameters(params)
        }
    }

    private fun processDeepLinkParameters(params: Map<String, String>) {
        // Process the parameters as needed
        println("Processed parameters: $params")
    }
}

// In your Activity
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Handle deep link if activity was launched from a deep link
        intent?.let { DeepLinkHandler().handleDeepLink(it) }
    }

    override fun onNewIntent(intent: Intent?) {
        super.onNewIntent(intent)
        // Handle deep link if app was already running
        intent?.let { DeepLinkHandler().handleDeepLink(it) }
    }
}

Deep Linking diferido

Links diretos na primeira instalação

Quando o aplicativo for aberto pela primeira vez desde a instalação, habilite o deferred deep linking adicionando parâmetros ao relatar a sessão para o Singular.

Parâmetros necessários:

• install=true
• ddl_enabled=true

O Singular verifica se o aplicativo foi instalado por meio do link de rastreamento com o deferred deep link. Em caso afirmativo, a solicitação SESSION retorna:

• deferred_deeplink: Endereço do deep link analisado para mostrar aos usuários o produto/experiência correto
• deferred_passthrough Parâmetros de passagem adicionados ao deep link

Exemplo de resposta:

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

Parâmetros de passagem dinâmicos

Os links de rastreamento singulares podem incluir parâmetros de passagem dinâmicos para experiências de usuário personalizadas.

Se a organização configurou a passagem dinâmica para o link, o URL do link profundo inclui o parâmetro _p com valor de string JSON codificado por URL ou string não estruturada para roteamento de conteúdo/experiência.

Mais informações: Parâmetros de passagem dinâmica

Resolução de links curtos

Quando o aplicativo é aberto a partir de um link singular encurtado, inclua o parâmetro na solicitação SESSION para resolver o link curto para o link longo.

Parâmetro obrigatório: singular_link_resolve_required=true

O Singular retorna um link longo não encurtado para analisar o deep link e os parâmetros de passagem no manipulador de links.

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"
}

Recursos adicionais

Implemente o rastreio entre dispositivos, o rastreio de receitas, a monitorização da desinstalação e a conformidade com a privacidade dos dados para uma análise abrangente.

Rastreamento entre dispositivos

Implementação de ID de utilizador personalizado

Utilize o parâmetro custom_user_id para associar utilizadores a sessões ao nível do dispositivo para relatórios entre dispositivos e análises ao nível do utilizador.

Permite relatórios abrangentes entre dispositivos, exportações de dados ao nível do utilizador e postbacks de BI interno, mantendo a privacidade do utilizador.

Mais informações: Parâmetro de ID de utilizador personalizado

Controlo de receitas

Relatórios de compras na aplicação

Rastreie a receita de compras in-app para análise de ROI, medição de desempenho de campanha e enriquecimento de exportação/postback.

Use o ponto de extremidade EVENTcom parâmetros de receita:

• is_revenue_event Marca o evento como evento de receita (ignorar se o nome do evento for __iap__ ou o montante > 0)
• purchase_receipt Objeto de compra no aplicativo para Android/iOS - altamente recomendado para detalhes da transação e enriquecimento de relatórios
• receipt_signature (Android): Altamente recomendado para validação de transacçõ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: Gestão do estado da subscrição

Controlo de desinstalação

Configuração de notificações push silenciosas

Acompanhe as desinstalações usando notificações push silenciosas do dispositivo enviando um token push com cada notificação de sessão.

Requisitos de configuração:

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

Recibo de instalação do iOS

Validação do recibo

Passe o recibo de instalação do iOS no parâmetro install_receipt ao comunicar a sessão 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 com a privacidade dos dados

Tratamento de consentimento do utilizador

Notificar a Singular sobre o consentimento do utilizador final para a partilha de dados para cumprir o GDPR, CCPA e outros regulamentos de privacidade.

Utilizar o parâmetro data_sharing_options para comunicar a escolha do utilizador:

• {"limit_data_sharing":false} O utilizador consentiu (optou por participar) na partilha de informações
• {"limit_data_sharing":true} O utilizador recusou a partilha de informações

A Singular utiliza limit_data_sharing nos Postbacks de privacidade do utilizadore transmite informações aos parceiros que exigem conformidade.

Mais informações: Privacidade do utilizador e limitação da partilha de dados