Fluxos S2S do SKAdNetwork: Como Verificar Postbacks de Redes de Anúncios

Como as DSPs lidam com postbacks do SKAdNetwork? Platapostas de Oferta (DSPs) e redes de anúncios lidam com postbacks do SKAdNetwork estabelecendo endpoints seguros de ingestão via HTTP POST, construindo a string de mensagem UTF-8 serializada usando o delimitador U+2063, verificando a assinatura criptográfica ECDSA P-256 da Apple em relação à chave pública publicada pela Apple e registrando IDs de transação verificados para evitar o processamento duplicado antes de atualizar os modelos de lances.

Um postback de validação de instalação do SKAdNetwork é uma notificação HTTPS POST assinada pela Apple que o sistema operacional envia para uma rede de anúncios qualificada e, para atribuições vencedoras, opcionalmente para o endpoint de cópia configurado do desenvolvedor do aplicativo anunciado. Para garantir a integridade dos dados, os sistemas de ingestão de backend devem verificar a assinatura ECDSA P-256 da Apple, validar a serialização de parâmetros e aplicar a desduplicação em nível de transação.

A Arquitetura de Ingestão de Postbacks do SKAdNetwork para DSPs e Redes de Anúncios

O Pipeline de Ingestão Dupla: Entrega Direta na Rede de Anúncios vs. Endpoints de Postback do Desenvolvedor

Quando ocorre a instalação de um aplicativo iOS atribuído, o subsistema de atribuição da Apple despacha postbacks de validação de instalação via HTTPS POST:

• Ingestão da Rede de Anúncios: O dispositivo entrega o postback vencedor principal (did-win: true) diretamente para a URL do servidor registrada sob o ad-network-id correspondente no registro da Apple.
• Ingestão de Cópia do Desenvolvedor: Se o aplicativo anunciado especificar a chave NSAdvertisingAttributionReportEndpoint em seu Info.plist, o dispositivo despacha simultaneamente uma cópia exata do postback vencedor diretamente para o servidor do desenvolvedor.
• Roteamento de Postbacks Não Vencedores: A partir do SKAdNetwork 3.0, se várias redes de anúncios se qualificaram para a atribuição, mas não venceram, o dispositivo envia até cinco postbacks não vencedores (did-win: false) diretamente para essas redes de anúncios qualificadas secundárias. Os postbacks não vencedores não são entregues ao endpoint de cópia do desenvolvedor.

Os endpoints de ingestão de backend devem responder com HTTP 200 OK. Se o dispositivo não receber uma resposta 200, ele poderá tentar novamente a entrega até nove vezes ao longo de um período máximo de nove dias.

O Papel de NSAdvertisingAttributionReportEndpoint na Auditoria do Desenvolvedor

O NSAdvertisingAttributionReportEndpoint permite que os desenvolvedores de aplicativos recebam cópias diretas de postbacks vencedores independentemente do encaminhamento da rede de anúncios:

• Auditoria Independente: Os desenvolvedores recebem cópias exatas de todos os postbacks vencedores gerados para seus aplicativos, permitindo a validação interna dos relatórios da rede de anúncios.
• Caminho de Endpoint Dedicado: O servidor do desenvolvedor deve hospedar o endpoint em https://<domain>/.well-known/skadnetwork/report-attribution/.
• Diferenciação do AdAttributionKit: Para o AdAttributionKit, a Apple define uma configuração separada de roteamento para https://<domain>/.well-known/appattribution/report-attribution/, que utiliza uma arquitetura de verificação JSON Web Signature (JWS).

Como as MMPs Ingerem, Agregam e Normalizam Fluxos de Eventos S2S de Múltiplas Redes

Dependendo das integrações comerciais, os Parceiros de Mensuração Mobile (MMPs) podem ingerir dados do SKAdNetwork por meio de encaminhamento do lado do desenvolvedor, integrações de redes de anúncios ou fluxos de servidores de parceiros personalizados:

• Ingestão de Múltiplas Fontes: Ingerir dados de postback verificados encaminhados de endpoints de desenvolvedores juntamente com fluxos de relatórios diretos de redes de anúncios.
• Desduplicação entre Fluxos: Normalizar e desduplicar registros usando o transaction-id exclusivo em cópias compartilhadas de redes de anúncios e desenvolvedores.
• Normalização para BI a Jusante: Mapear valores de conversão de nível granular e agregado para modelos de receita definidos pelo cliente e eventos de funil.

Veja Também: SKAdNetwork ──> Modelo de Atribuição Mobile

Verificação Criptográfica: Validando a Assinatura ECDSA P-256 da Apple

Compreendendo a Pilha Criptográfica: Curva NIST P-256 (secp256r1) com SHA-256

Cada postback do SKAdNetwork inclui um campo attribution-signature. Essa assinatura criptográfica é gerada pela Apple usando o Algoritmo de Assinatura Digital de Curva Elíptica (ECDSA) com a curva NIST P-256 (secp256r1) e um resumo SHA-256.

A assinatura valida duas propriedades fundamentais de segurança:

• Autenticidade: O postback foi gerado diretamente pelo subsistema de plataforma da Apple em um dispositivo verificado, e não falsificado por um cliente ou proxy mal-intencionado.
• Integridade: Os parâmetros cobertos pela assinatura não foram alterados em trânsito.

Usando a Chave Pública Publicada do SKAdNetwork da Apple

Para verificar a assinatura, o servidor de ingestão deve carregar a chave pública oficial da Apple. Para o SKAdNetwork 2.1 e posterior, a Apple publica uma chave pública NIST P-256 dedicada em sua documentação para desenvolvedores:

• Inicialização da Chave: A chave pública é carregada na memória como um objeto de chave pública X.509/DER padrão durante a inicialização do servidor.
• Verificação de Assinatura Assimétrica: O motor de verificação reconstrói a string de mensagem serializada em UTF-8 exata, computa o hash SHA-256 e verifica a attribution-signature decodificada em Base64 em relação à mensagem reconstruída.

[Device / Subsystem] ──► [Dispatches Signed JSON Postback]
                                     │
                                     ▼
                  [DSP / Ad Network Ingestion Endpoint]
                  (HTTPS POST to registered postback URL)
                                     │
                                     ▼
                  [Parse JSON & Reconstruct Message String]
                  (Concatenate UTF-8 fields with \u2063)
                                     │
                                     ▼
                  [ECDSA P-256 Public Key Signature Verification]
                                     │
                      ┌──────────────┴──────────────┐
                      ▼                                                          ▼
               [Signature Valid]                                         [Signature Invalid]
                      │                                                          │
                      ▼                                                          ▼
            [Atomic Deduplication]                                       [Log Error & Discard]
            (Check transaction-id)
                      │
                      ▼
            [Process Attribution]

Por que Apenas um Hash é Insuficiente: Verificação de Assinatura Assimétrica

Como a Apple assina o payload usando sua chave privada e não distribui um segredo compartilhado, a validação simétrica (como HMAC-SHA256) não pode ser usada. Os mecanismos de ingestão devem implementar a verificação padrão de assinatura de chave pública assimétrica usando bibliotecas criptográficas padrão (como OpenSSL, crypto do Node.js ou cryptography do Python).

Construindo a String de Mensagem para Verificação de Assinatura

O Protocolo de Serialização Rigoroso: O Papel do Separador Invisível (\u2063)

A Apple especifica um formato exato de serialização de bytes UTF-8 para construir a string de mensagem para validação de assinatura. Os parâmetros devem ser concatenados em uma sequência precisa, separados pelo caractere Unicode invisível \u2063 (Separador Invisível U+2063, sequência de bytes UTF-8 0xE2 0x81 0xA3):

A substituição de espaços em branco, pontuação padrão ou separadores Unicode alternativos resultará em falha na verificação criptográfica.

Ordenação de Parâmetros Específica da Versão para o SKAN 4.0

De acordo com a Documentação para Desenvolvedores da Apple sobre a Verificação de um Postback de Validação de Instalação, os parâmetros para postbacks do SKAdNetwork 4.0 devem ser serializados na seguinte ordem exata:

1. version (por exemplo, "4.0")
2. ad-network-id (por exemplo, "example123.skadnetwork")
3. source-identifier (por exemplo, "4821")
4. app-id (por exemplo, 1234567890)
5. transaction-id (por exemplo, "6a8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d")
6. redownload (por exemplo, "true" ou "false" como uma string em letras minúsculas)
7. source-app-id (para anúncios de app para app) OU source-domain (para anúncios de web para app no Safari), incluído apenas se estiver presente no postback
8. fidelity-type (por exemplo, 1 para anúncios renderizados pelo StoreKit ou anúncios da web atribuídos ao SKAdNetwork; 0 para anúncios visualizados - view-through)
9. did-win (por exemplo, "true" ou "false" como uma string em letras minúsculas)
10. postback-sequence-index (por exemplo, 0, 1 ou 2)

Especificação Crucial do SKAN 4: Os Valores de Conversão São Excluídos da Assinatura

No SKAdNetwork 4.0, a assinatura da Apple não inclui conversion-value ou coarse-conversion-value, mesmo quando um desses campos está presente no payload JSON. A string serializada para o SKAN 4 termina com postback-sequence-index. Tentar anexar valores de conversão à string da mensagem fará com que a verificação falhe.

O payload JSON abaixo ilustra um esquema completo de postback do SKAdNetwork 4.0. A assinatura abaixo é um espaço reservado ilustrativo e não passará na verificação criptográfica; para testes unitários, use os exemplos assinados da Apple na documentação oficial de verificação:

{
  "version": "4.0",
  "ad-network-id": "example123.skadnetwork",
  "source-identifier": "4821",
  "app-id": 1234567890,
  "transaction-id": "6a8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "redownload": false,
  "source-app-id": 9876543210,
  "fidelity-type": 1,
  "did-win": true,
  "postback-sequence-index": 0,
  "conversion-value": 47,
  "attribution-signature": "MEQCIFz8...SAMPLE_CRYPTOGRAPHIC_SIGNATURE...=="
}

Lidando com Payloads Multi-Janela do SKAN 4.0 e Endpoints de Desenvolvedores

Analisando postback-sequence-index em Janelas de Conversão Sequenciais

No SKAdNetwork 4.0, as conversões geram postbacks de janelas de conversão que abrangem até 35 dias após o primeiro lançamento do aplicativo, com a entrega real ocorrendo após os atrasos pós-janela randomizados da Apple. Os sistemas de ingestão de backend analisam o campo postback-sequence-index para atribuir dados de conversão à janela de ciclo de vida correta:

• Índice 0 (Janela 1: Dia 0–2): Contém um valor de conversão de nível granular (0–63) ou um valor de conversão agregado (low, medium, high), ou o campo está ausente.
• Índice 1 (Janela 2: Dia 3–7): Para os níveis de dados de postback 1–3, pode divulgar um coarse-conversion-value (low, medium, high) quando fornecido; o nível 0 não é elegível para segundo ou terceiro postbacks.
• Índice 2 (Janela 3: Dia 8–35): Para os níveis de dados de postback 1–3, pode divulgar um coarse-conversion-value (low, medium, high) quando fornecido; o nível 0 não é elegível para segundo ou terceiro postbacks.

Gerenciando Valores de Conversão Granulares vs. Agregados

Os decodificadores de ingestão devem considerar a variabilidade do payload:

• Exclusividade Mútua: A Apple especifica que um postback de validação de instalação pode conter um conversion-value ou um coarse-conversion-value, mas nunca ambos simultaneamente.
• Valores de Conversão Ausentes: Se o nível de dados de postback atribuído for baixo (Nível 0), os campos de valor de conversão serão omitidos do payload JSON.

Protegendo-se Contra Ataques de Replay e Payloads de Conversão Falsificados

O Papel do transaction-id como Chave de Desduplicação

Cada postback do SKAdNetwork contém um UUID transaction-id exclusivo. A documentação da Apple aconselha os receptores a usarem esse identificador como uma chave de idempotência para detectar e descartar postbacks de conversão duplicados.

Como os ouvintes de postback são endpoints HTTPS acessíveis publicamente, atores mal-intencionados podem tentar ataques de replay capturando um postback válido e reenviando-o repetidamente para inflar artificialmente as métricas de conversão.

Implementando Cache Distribuído em Memória e Registros Persistentes

A Apple não prescreve um período universal de retenção de desduplicação. Os receptores de produção devem manter um registro de idempotência durável para IDs de transação verificados de acordo com seus requisitos de reconciliação e defesa contra replay; o TTL do Redis pode ser usado como uma otimização de cache rápido em vez do único ledger de duplicatas autoritativo:

1. Verificação Criptográfica Primeiro: Verifique totalmente a assinatura ECDSA em relação à chave pública da Apple antes de confirmar o ID da transação no armazenamento.
2. Desduplicação Atômica: Execute uma operação de gravação atômica (por exemplo, Redis SET key value NX EX <seconds>) apoiada por uma restrição exclusiva de banco de dados relacional ou de documentos persistente.
3. Horizonte de Desduplicação: Defina uma janela de retenção operacional na camada de cache que cubra a entrega esperada de postbacks, novas tentativas de rede (a Apple tenta novamente entregas com falha por até 9 dias) e reconciliação a jusante.

A implementação de backend abaixo demonstra a validação de assinatura, validação de esquema e desduplicação atômica em Python:

import base64
import json
import redis
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.primitives.serialization import load_der_public_key
from cryptography.exceptions import InvalidSignature

# Initialize Redis client for hot-cache transaction deduplication
redis_client = redis.Redis(host='localhost', port=6379, db=0, decode_responses=True)

# Official Apple SKAdNetwork 2.1+ Public Key (Base64 DER encoded, published by Apple)
APPLE_SKAN_PUBLIC_KEY_B64 = (
    "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEWdp8GPcGqmhgzEFj9Z2nSpQVdday"
    "aPe4FMzqM9wib1+aHaaIzoHoLN9zW4K8y4SPykE3YVK3sVqW6Af0lfx3gg=="
)

# Exact Apple-specified invisible separator: U+2063 INVISIBLE SEPARATOR (UTF-8: 0xE2 0x81 0xA3)
SEPARATOR = "\u2063"

def construct_skan4_message_bytes(payload: dict) -> bytes:
    """
    Constructs the serialized UTF-8 message string for SKAN 4.0 signature verification.
    Apple specification explicitly EXCLUDES conversion-value and coarse-conversion-value from the signature.
    """
    parts = [
        str(payload["version"]),
        str(payload["ad-network-id"]),
        str(payload["source-identifier"]),
        str(payload["app-id"]),
        str(payload["transaction-id"]),
        "true" if payload["redownload"] is True else "false"
    ]

    # Include source-app-id (app ad) OR source-domain (web ad) if present
    if payload.get("source-app-id") is not None:
        parts.append(str(payload["source-app-id"]))
    elif payload.get("source-domain") is not None:
        parts.append(str(payload["source-domain"]))

    parts.append(str(payload["fidelity-type"]))
    parts.append("true" if payload["did-win"] is True else "false")
    parts.append(str(payload["postback-sequence-index"]))

    # Join with U+2063 separator and encode to UTF-8
    message_string = SEPARATOR.join(parts)
    return message_string.encode('utf-8')

def verify_and_ingest_skan4_postback(postback_json_str: str) -> dict:
    """
    Validates payload schema, verifies the ECDSA P-256 signature against Apple's public key,
    and performs atomic transaction-id deduplication.
    """
    try:
        payload = json.loads(postback_json_str)
    except Exception:
        return {"status": "REJECTED", "reason": "INVALID_JSON_FORMAT"}

    # Version Gate: Enforce SKAN 4.0 payload handling
    if payload.get("version") != "4.0":
        return {"status": "REJECTED", "reason": "UNSUPPORTED_SKAN_VERSION"}

    # Schema Validation: Required fields for SKAN 4.0
    required_fields = [
        "version", "ad-network-id", "source-identifier", "app-id",
        "transaction-id", "redownload", "fidelity-type", "did-win",
        "postback-sequence-index", "attribution-signature"
    ]
    for field in required_fields:
        if field not in payload:
            return {"status": "REJECTED", "reason": f"MISSING_REQUIRED_FIELD_{field.upper()}"}

    # Strict Type Validation
    if not isinstance(payload["redownload"], bool):
        return {"status": "REJECTED", "reason": "INVALID_TYPE_REDOWNLOAD"}
    if not isinstance(payload["did-win"], bool):
        return {"status": "REJECTED", "reason": "INVALID_TYPE_DID_WIN"}
    if payload["postback-sequence-index"] not in (0, 1, 2):
        return {"status": "REJECTED", "reason": "INVALID_SEQUENCE_INDEX"}
    if payload["fidelity-type"] not in (0, 1):
        return {"status": "REJECTED", "reason": "INVALID_FIDELITY_TYPE"}

    # Enforce mutual exclusivity between source-app-id and source-domain
    has_source_app = payload.get("source-app-id") is not None
    has_source_domain = payload.get("source-domain") is not None
    if has_source_app and has_source_domain:
        return {"status": "REJECTED", "reason": "CONFLICTING_SOURCE_FIELDS"}

    signature_b64 = payload["attribution-signature"]
    transaction_id = payload["transaction-id"]

    try:
        # Step 1: Reconstruct the exact UTF-8 serialized message
        message_bytes = construct_skan4_message_bytes(payload)
        signature_der = base64.b64decode(signature_b64, validate=True)

        # Step 2: Verify ECDSA P-256 / SHA-256 signature using Apple's published public key
        apple_public_key = load_der_public_key(base64.b64decode(APPLE_SKAN_PUBLIC_KEY_B64))
        apple_public_key.verify(
            signature_der,
            message_bytes,
            ec.ECDSA(hashes.SHA256())
        )
    except InvalidSignature:
        return {"status": "REJECTED", "reason": "INVALID_CRYPTOGRAPHIC_SIGNATURE"}
    except Exception as e:
        return {"status": "ERROR", "reason": f"VERIFICATION_FAILED: {str(e)}"}

    # Step 3: Atomic Deduplication via Redis (Hot cache layer)
    # Note: In production, pair this hot cache with a persistent unique database constraint.
    # 14-day TTL (1,209,600 seconds) serves as an illustrative receiver cache policy covering retries.
    is_new = redis_client.set(f"skan_tx:{transaction_id}", "1", nx=True, ex=1209600)
    if not is_new:
        return {"status": "DUPLICATE", "reason": "TRANSACTION_ALREADY_PROCESSED"}

    return {
        "status": "VERIFIED",
        "transaction_id": transaction_id,
        "sequence_index": payload["postback-sequence-index"],
        "did_win": payload["did-win"]
    }

Ingerindo Postbacks em Modelos de Lances em Tempo Real e Otimizadores de CPA

Desacoplando a Ingestão de Borda do Processamento Assíncrono

DSPs de alto volume processam volumes substanciais de postbacks durante períodos de pico de campanhas. O processamento síncrono a jusante pode introduzir gargalos de latência.

As arquiteturas empresariais implementam um pipeline assíncrono:

1. Receptor de Borda: Aceita o HTTP POST recebido, verifica a autenticidade da assinatura, executa a desduplicação atômica no transaction-id e retorna imediatamente um HTTP 200 OK.
2. Fila de Eventos: Publica o payload verificado em um agente de eventos distribuído (por exemplo, Apache Kafka ou AWS SQS).
3. Workers de Lances e Análise: Consome o fluxo de eventos, mapeia valores de conversão para métricas de receita e atualiza os modelos de CPA alvo de Lances em Tempo Real (RTB).

Utilizando o Identificador de Origem Hierárquico

O primeiro postback vencedor pode expor dois, três ou quatro dígitos do source-identifier hierárquico, dependendo do nível de dados do postback. O significado semântico desses dígitos é definido pela própria taxonomia de identificadores de origem da rede de anúncios. Os sistemas de lances devem resolver o identificador de origem recebido em relação aos metadados de campanha da própria rede, em vez de assumir um mapeamento universal entre o comprimento dos dígitos e posicionamentos específicos ou granularidade criativa.

Matriz Comparativa: Entrega Direta da Apple versus Ingestão S2S de MMP

Resumo e Estrutura de Decisão

Lidar com postbacks do SKAdNetwork em escala exige a combinação de ingestão de borda de baixa latência com validação criptográfica rigorosa e desduplicação em nível de transação. Como os postbacks da Apple influenciam diretamente a alocação de orçamento e os algoritmos de lances, a validação de assinaturas ECDSA e a aplicação da idempotência de transaction-id protegem os pipelines de ingestão contra postbacks falsificados ou adulterados e o processamento de replays duplicados.

Para complementar os relatórios do SKAdNetwork mediados pela plataforma com integração de usuários em micro-nível e roteamento instantâneo de deep links, as equipes de engenharia implantam arquiteturas de roteamento de primeira parte juntamente com as APIs da plataforma.

Para saber mais sobre a configuração de postbacks de atribuição do lado do servidor e pipelines de deep linking, reveja a documentação do OpoInstall.

Materiais Relacionados

• Conceitos: Postbacks S2S, Verificação Criptográfica, ECDSA P-256, Defesa contra Ataques de Replay, Desduplicação de Transações

• Tecnologias: Apple SKAdNetwork, Apple AdAttributionKit, Cache em Memória do Redis, SDK Mobile OpoInstall

• Padrões: IETF RFC 8259 (Intercâmbio de Dados JSON), RFC 5480 (Criptografia de Curva Elíptica)

• APIs: API StoreKit SKAdNetwork, Especificação de Entrega de Postbacks S2S da Apple, API S2S do OpoInstall

Documentação Oficial

• Documentação para Desenvolvedores da Apple sobre a Verificação de um Postback de Validação de Instalação

• Documentação para Desenvolvedores da Apple sobre a Identificação dos Parâmetros em Postbacks de Validação de Instalação

• Documentação para Desenvolvedores da Apple sobre a Configuração de um Aplicativo Anunciado

• Documentação para Desenvolvedores da Apple sobre o SKAdNetwork

• Documentação para Desenvolvedores da Apple sobre o AdAttributionKit