Visão geral

Este guia aborda os sinais de atribuição específicos para dispositivos móveis que se somam à mecânica S2S compartilhada: Apple Search Ads, install referrers do Google Play e da Meta, rastreamento de desinstalações e o recibo de instalação do iOS. Ele se aplica a integrações de apps iOS e Android que reportam sessões e eventos server-to-server.

Esses recursos pressupõem que você já tenha o fluxo de requisições S2S compartilhado implementado. Para os endpoints, a autenticação e os parâmetros comuns sobre os quais eles se baseiam, comece pelo hub de fundamentos e pelas duas referências de endpoint.

Atribuição do Apple Search Ads

Integração do iOS Search Ads

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

Suporte a frameworks:

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

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

Implementação do framework iAd

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

Etapa 1: Recuperar 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 para a Singular

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

Implementação do framework AdServices

Recupere e envie o attribution token por meio do framework AdServices para iOS 14.3 e posteriores.

Etapa 1: Recuperar 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 para a Singular

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

Install Referrer do Google Play

Atribuição de instalação no Android

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

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

Etapas de implementação:

1. Recupere o install referrer na primeira abertura do app usando a Play Install Referrer API
2. Reporte a sessão por meio do 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 para Android que fornece dados de atribuição granulares em nível de usuário para instalações de apps, combinando as tecnologias do Google Play Install Referrer e do Meta Install Referrer.

Saiba mais: FAQ do Meta Referrer

Etapas de implementação:

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

Atributos de meta_ref:

Rastreamento de desinstalações

Configuração de notificações push silenciosas

Rastreie desinstalações usando notificações push silenciosas do dispositivo, enviando o push token com cada notificação de sessão.

Requisitos de configuração:

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

Recibo de instalação do iOS

Validação do recibo

Passe o recibo de instalação do iOS no parâmetro install_receipt ao reportar uma sessão do 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
            }
        }
    }
}