Documento

Verificar a atribuição de dispositivos

Guia abrangente para validar a atribuição de dispositivos usando o aplicativo Singular Device Assist e o ponto de extremidade da API Attribution Details para testes de integração e verificação de links de rastreamento.

A Singular fornece dois métodos para verificar a atribuição do dispositivo: Device Assist app para testes mobile e Attribution Details API endpoint para verificação programática.

A verificação da atribuição é parte essencial do teste de novas integrações SDK/S2S e da validação de Singular Links antes da implementação da campanha.

Público-alvo	Gerentes de UA, desenvolvedores, engenheiros de QA
Pré-requisitos	Dispositivo móvel para teste (método do aplicativo Device Assist) Chave de API Singular (método de endpoint de API) Identificador de publicidade do dispositivo (IDFA, IDFV, GAID, etc.)

Casos de uso de verificação de atribuição

Quando verificar a atribuição

A verificação da atribuição do dispositivo é crítica em várias fases do ciclo de vida da integração e da implementação da campanha.

Caso de uso	Finalidade
Teste de integração SDK/S2S	Validar o SDK rastreando corretamente as instalações e atribuindo às fontes corretas durante o desenvolvimento da integração. Guia completo da consola de testes
Validação de links de rastreamento	Teste novos Singular Links antes da implementação da campanha para garantir a atribuição e a passagem de parâmetros corretas. Como testar o link de rastreamento
Solução de problemas de campanha	Diagnostique problemas de atribuição em campanhas ao vivo verificando o status da atribuição do dispositivo de teste
Verificação de integração de parceiros	Confirme se os dados de atribuição estão fluindo corretamente dos parceiros de publicidade para a plataforma Singular

Comparação de métodos

Escolhendo o método de verificação

Selecionar o método de verificação apropriado com base nos requisitos de teste e capacidades técnicas.

Método de verificação	Melhor para	Requisitos	Limitações
Aplicação de assistência ao dispositivo	Teste manual rápido Utilizadores não técnicos Verificação visual	Dispositivo móvel Instalação da aplicação	Processo manual, automatização limitada
API de detalhes de atribuição	Teste automatizado Verificação programática Integração CI/CD	Chave da API Identificador de dispositivo Cliente HTTP	Apenas para testes (beta), requer conhecimentos técnicos

Método 1: Aplicação de assistência ao dispositivo

Aplicação móvel que fornece uma verificação visual rápida do estado de atribuição do dispositivo, detalhes da instalação e resumo do seguimento de eventos diretamente no dispositivo de teste.

Visão geral da aplicação Device Assist

Recursos do aplicativo

O aplicativo Device Assist exibe informações abrangentes de atribuição gravadas no Singular para um dispositivo específico.

Dados de atribuição exibidos:

Atribuição de instalação: Carimbo de data e hora da instalação, rede atribuída e nome da campanha
Atribuição de reengajamento: Carimbo de data/hora de reengajamento, rede atribuída e detalhes da campanha
Resumo do evento: Sessões e eventos in-app rastreados pelo Singular para o dispositivo
Identificadores de dispositivo: IDFA, IDFV, GAID ou outros identificadores usados para rastreamento

Utilização da aplicação Device Assist

Procedimento passo a passo

1	Descarregar a aplicação Device Assist Instalar a aplicação Singular Device Assist no dispositivo de teste: iOS:Descarregar da App Store Android:Descarregar a partir do Google Play
2	Iniciar o Attribution Check Abra a aplicação Device Assist e selecione Verificar Implementaçãono menu principal. Funcionalidades adicionais: A aplicação Device Assist também fornece ferramentas de pesquisa do identificador do dispositivo e de verificação da implementação do SDK, acessíveis a partir do menu principal.
3	Selecionar identificador do dispositivo A aplicação seleciona automaticamente o identificador de dispositivo adequado para a plataforma. Confirme a seleção e toque novamente em Verificar implementaçãopara continuar. Seleção do identificador: iOS: IDFA (se a ATT autorizar) ou IDFV (se a ATT não autorizar ou não implementar) Android: GAID (Google Advertising ID) ou identificadores alternativos se o GAID não estiver disponível
4	Rever detalhes de atribuição A aplicação apresenta informações de atribuição completas para o dispositivo, conforme registado na plataforma Singular. Informações de atribuição exibidas Instalar detalhes de atribuição # Carimbo de data/hora da instalação: Data e hora da primeira inicialização do aplicativo (evento de instalação) Rede atribuída: Rede de anúncios ou fonte creditada com a instalação (por exemplo, Facebook, Google Ads, Orgânico) Nome da campanha: Campanha de marketing atribuída à instalação Parâmetros adicionais: Parâmetros específicos da campanha passados pelo link de rastreamento Interpretando a atribuição da instalação "Orgânico": Nenhum ponto de contato correspondente encontrado dentro da janela de atribuição - instalação não atribuída à campanha paga "Não atribuído": Dispositivo rastreado, mas decisão de atribuição pendente ou incompleta Nome da rede: Instalação atribuída com sucesso a um parceiro de publicidade específico Detalhes de atribuição de reengajamento # Carimbo de data/hora do reengajamento:Data e hora da última sessão de reengajamento Rede atribuída: Fonte creditada por trazer o utilizador de volta à aplicação Nome da campanha: Campanha de reengajamento atribuída à sessão Redesde auto-atribuição :As atribuições de reengajamento de redes de auto-atribuição (Twitter, Facebook, Google Ads, Snapchat, etc.) podem ser exibidas como "Não atribuído" por motivos de privacidade. Requisitos de atribuição de reengajamento Para que a atribuição de reengajamento ocorra: O utilizador tem de ter uma instalação existente (não um dispositivo novo) O clique na campanha de reengajamento deve ocorrer dentro da janela de atribuição configurada A sessão deve ocorrer após o clique de reengajamento Saiba mais: Perguntas frequentes sobre atribuição de reengajamento Resumo do rastreamento de eventos # O aplicativo Device Assist exibe um resumo de todos os eventos in-app rastreados pela Singular para o dispositivo. Informações do evento mostradas: Nome do evento: Nome do evento rastreado (sessão, compra, level_complete, etc.) Hora do primeiro evento: Carimbo de data/hora da primeira ocorrência Hora do último evento: Carimbo de data/hora da ocorrência mais recente Contagem de eventos: Número total de vezes que o evento ocorreu Receita: Receita total para eventos de receita Validando o rastreamento de eventos Use o resumo do evento para verificar: Sessões sendo rastreadas corretamente Os eventos personalizados aparecem com os nomes corretos Eventos de receita capturando valores corretamente Os carimbos de data e hora do evento correspondem às acções reais do utilizador

Solução de problemas do Device Assist

Problemas comuns

Não são apresentados dados de atribuição

Causas possíveis

Aplicação não instalada: A aplicação de teste não está instalada ou ainda não foi aberta no dispositivo
Identificador errado: Identificador de verificação do Device Assist não utilizado pelo SDK da aplicação
SDK não inicializado: O SDK Singular não foi inicializado corretamente na aplicação
Atribuição pendente: A decisão de atribuição ainda não foi finalizada (normalmente leva de 1 a 5 minutos)

Etapas de resolução

Verifique se o aplicativo de teste foi instalado e aberto pelo menos uma vez no dispositivo
Confirme se o identificador do dispositivo corresponde ao tipo de identificador usado no SDK (IDFA vs IDFV para iOS)
Aguarde 5-10 minutos após o lançamento da aplicação e verifique novamente a atribuição
Verificar a integração do SDK utilizando a Consola de Testes

Atribuição à fonte errada

Causas possíveis

Uso anterior do dispositivo: Dispositivo usado anteriormente para testes com atribuição em cache
Vários pontos de contacto: Múltiplos cliques na campanha dentro da janela de atribuição
Correspondência de impressões digitais: a atribuição probabilística correspondeu ao clique errado

Etapas de resolução

Redefinir o dispositivo e limpar a atribuição:
- Eliminar aplicação de teste
- Repor o identificador de publicidade
- Eliminar o dispositivo da consola de testes, se estiver registado
Utilizar um dispositivo novo ou repor o identificador antes do teste
Utilizar atribuição determinística (ID do dispositivo na ligação de seguimento) em vez de impressões digitais para testes
Rever as definições da janela de atribuição na Configuração de parceiros

Instalar Atribuído como Orgânico em vez de Campanha

Causas possíveis

Janela de atribuição excedida: A instalação ocorreu fora da janela de atribuição configurada
Nenhum ponto de contacto correspondente: Não foi encontrado nenhum clique correspondente ao dispositivo
Incompatibilidade de impressão digital: A impressão digital do dispositivo foi alterada entre o clique e a instalação
Link não clicado: Aplicação instalada diretamente da loja sem clicar na ligação de seguimento

Passos de resolução

Verificar se a ligação de seguimento foi clicada antes de instalar a aplicação
Verificar se as definições da janela de atribuição permitem tempo suficiente para a instalação
Utilizar o ID do dispositivo na ligação de seguimento (atribuição determinística) para testes fiáveis
Assegurar uma ligação de rede estável durante o clique e a instalação
Teste em outro dispositivo ou redefina o identificador e tente novamente

Método 2: API de detalhes de atribuição

Ponto de extremidade da API programática que permite a verificação de atribuição automatizada para testes de integração e pipelines de CI/CD.

Aviso de recurso beta: O ponto de extremidade da API Attribution Details é um recurso beta. Use apenas para fins de teste - não chame dentro do aplicativo de produção ou ambientes de alto volume.

Especificação do ponto de extremidade da API

Formato da solicitação

URL do ponto final:

https://api.singular.net/api/attribution/attribution_details

Método de pedido: GET

Exemplo de pedido completo:

https://api.singular.net/api/attribution/attribution_details?keyspace=idfa&device_id=12345678-1234-1234-1234-123456789012&api_key=your_api_key_here

Parâmetros de consulta

Parâmetros necessários

Parâmetro Tipo de parâmetro Descrição do parâmetro

api_key

Cadeia de caracteres

Chave da API do relatório singular da plataforma.

Localização: Dashboard → Ferramentas do desenvolvedor → Chaves de API → Chave da API de relatórios

Importante: use a chave da API de relatórios, não a chave do SDK. Chaves diferentes têm finalidades diferentes.

device_id

Cadeia de caracteres

Valor do identificador de publicidade do dispositivo.

Deve corresponder ao tipo de identificador especificado no parâmetro keyspace.

keyspace

Cadeia de caracteres (Enum)

Tipo de identificador de publicidade fornecido em device_id:

idfa - Identificador iOS para anunciantes (requer autorização da ATT)
idfv - Identificador iOS para fornecedores (alternativa quando o IDFA não está disponível)
aifa - Identificador Android para publicidade (também conhecido como GAID)
sdid - ID de dispositivo singular para rastreio na Web (obter através de singularSdk.getSingularDeviceId() após a inicialização do SDK)

Resposta da API

Formato da resposta

A API devolve uma matriz JSON que contém detalhes de atribuição para o dispositivo solicitado.

Exemplo de resposta

[
  {
    "app_long_name": "com.example.myapp",
    "app_name": "My App",

    "install_info": {
      "install_time": "2020-06-10 11:58:46",
      "network": "Network 1",
      "additional_parameters": {
        "kw": "my keyword",
        "pcid": "1234"
      },
      "campaign_name": "Campaign Name",
      "view_through_attribution": false
    },

    "re_engagement_info": {
      "notes": "Attributions from Self-Attributing networks including: Twitter, Facebook, Google Ads, Snapchat, etc are redacted and always show as 'Unattributed'",
      "install_time": "2020-06-15 15:27:12",
      "network": "Unattributed"
    },

    "uninstall_pre_requisites": {
      "gcm_token": "enE8iQR10RI:APA91bERgfA_xm8T7zgqH9OW_1s05SFFmKnle1zIm0cMrDfuaSxEmC_3j72dj4qN36vh5V8TAEnrXa3Pq3SmLW-XNOHP7daMwcBrBTibdkv_pKMJbN9SbefV6_9nuEfIeI5Zhtz0nlLY"
    },

    "events": [
      {
        "event_name": "Session",
        "first_event_time": "2020-04-02 00:09:55",
        "last_event_time": "2020-04-07 20:59:55",
        "event_count": 2
      },
      {
        "event_name": "Save New Transaction",
        "first_event_time": "2020-04-02 00:11:51",
        "last_event_time": "2020-04-02 00:11:51",
        "event_count": 1
      }
    ]
  }
]

Parâmetros de resposta

Campos da resposta JSON

Campo	Descrição
`app_long_name`	Identificador do pacote de aplicações (por exemplo, com.example.myapp)
`app_name`	Nome de exibição do aplicativo conforme configurado na plataforma Singular
`install_info`	Objeto que contém detalhes de atribuição de instalação e informações de decisão: `install_time` - Carimbo de data/hora da primeira sessão da aplicação (instalação) `network` - Rede de anúncios creditada com a instalação `campaign_name` - Nome da campanha atribuída à instalação `view_through_attribution` - Booleano indicando a atribuição com base na impressão do anúncio (verdadeiro) ou no clique do anúncio (falso). Saiba mais: Processo de atribuição de instalação da Singular `additional_parameters` - Parâmetros personalizados passados pelo link de rastreamento. Detalhes: Parâmetros do link de rastreamento e dimensões do relatório
`re_engagement_info`	Objeto com a mesma estrutura de `install_info`, mas para atribuição de reengajamento. Saiba mais: Perguntas frequentes sobre atribuição de reengajamento Nota sobre privacidade: as atribuições de reengajamento de redes de auto-atribuição (Facebook, Google Ads, Twitter, Snapchat) aparecem como "Não atribuído" para conformidade com a privacidade.
`events`	Conjunto de objectos que contêm o resumo do evento in-app monitorizado pelo SDK: `event_name` - Nome do evento monitorizado `first_event_time` - Carimbo de data/hora da primeira ocorrência `last_event_time` - Carimbo de data/hora da ocorrência mais recente `event_count` - Número total de ocorrências de eventos `revenue` - Receita total para eventos de receita (se aplicável)
`uninstall_pre_requisites`	Objeto que contém a configuração de seguimento de desinstalação: `apns` (iOS) - token do serviço de notificação por push da Apple Configuração: rastreamento de desinstalação do iOS `gcm_token` (Android) - token do Firebase Cloud Messaging Configuração: rastreamento de desinstalação do Android

Exemplos de uso da API

Exemplos de implementação

Dispositivo iOS (IDFA)

curl -X GET "https://api.singular.net/api/attribution/attribution_details?keyspace=idfa&device_id=12345678-1234-1234-1234-123456789012&api_key=your_api_key_here"

Dispositivo Android (GAID)

curl -X GET "https://api.singular.net/api/attribution/attribution_details?keyspace=aifa&device_id=12345678-1234-1234-1234-123456789012&api_key=your_api_key_here"

Rastreamento da Web (SDID)

curl -X GET "https://api.singular.net/api/attribution/attribution_details?keyspace=sdid&device_id=singular_device_id_value&api_key=your_api_key_here"

Implementação em Python

import requests
import json

def check_attribution(keyspace, device_id, api_key):
    """
    Check device attribution using Singular API
    
    Args:
        keyspace: Device identifier type (idfa, idfv, aifa, sdid)
        device_id: Device identifier value
        api_key: Singular Reporting API key
    
    Returns:
        Attribution data as JSON or None if error
    """
    url = "https://api.singular.net/api/attribution/attribution_details"
    
    params = {
        'keyspace': keyspace,
        'device_id': device_id,
        'api_key': api_key
    }
    
    try:
        response = requests.get(url, params=params)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error checking attribution: {e}")
        return None

# Example usage
attribution_data = check_attribution(
    keyspace='idfa',
    device_id='12345678-1234-1234-1234-123456789012',
    api_key='your_api_key_here'
)

if attribution_data:
    print(json.dumps(attribution_data, indent=2))
    
    # Extract install info
    if attribution_data and len(attribution_data)  0:
        install_info = attribution_data[0].get('install_info', {})
        print(f"\nInstall Network: {install_info.get('network')}")
        print(f"Campaign: {install_info.get('campaign_name')}")
        print(f"Install Time: {install_info.get('install_time')}")

Implementação em JavaScript

/**
 * Check device attribution using Singular API
 * 
 * @param {string} keyspace - Device identifier type (idfa, idfv, aifa, sdid)
 * @param {string} deviceId - Device identifier value
 * @param {string} apiKey - Singular Reporting API key
 * @returns {Promise} Attribution data or error
 */
async function checkAttribution(keyspace, deviceId, apiKey) {
    const url = 'https://api.singular.net/api/attribution/attribution_details';
    
    const params = new URLSearchParams({
        keyspace: keyspace,
        device_id: deviceId,
        api_key: apiKey
    });
    
    try {
        const response = await fetch(`${url}?${params.toString()}`);
        
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        
        return await response.json();
    } catch (error) {
        console.error('Error checking attribution:', error);
        throw error;
    }
}

// Example usage
checkAttribution(
    'idfa',
    '12345678-1234-1234-1234-123456789012',
    'your_api_key_here'
)
.then(data = {
    console.log('Attribution Data:', JSON.stringify(data, null, 2));
    
    // Extract install info
    if (data && data.length  0) {
        const installInfo = data[0].install_info || {};
        console.log('\nInstall Network:', installInfo.network);
        console.log('Campaign:', installInfo.campaign_name);
        console.log('Install Time:', installInfo.install_time);
    }
})
.catch(error = {
    console.error('Failed to check attribution:', error);
});

Resolução de problemas da API

Problemas comuns da API

Resposta de matriz vazia

Problema

A API retorna uma matriz vazia [] em vez de dados de atribuição.

Causas possíveis

Sem dados de atribuição: O dispositivo nunca instalou o aplicativo ou nenhuma sessão foi rastreada
Identificador incorreto: ID do dispositivo ou espaço-chave incorreto
Problema de tempo: Os dados de atribuição ainda não foram processados (normalmente 1-5 minutos após a instalação)

Passos de resolução

Verificar se o ID do dispositivo foi copiado corretamente sem espaços extra
Confirme se o espaço-chave corresponde ao tipo de identificador (idfa vs idfv para iOS)
Aguarde 5-10 minutos após a instalação da aplicação e repita a consulta
Verificar a atribuição do dispositivo utilizando a aplicação Device Assist para verificar se a aplicação foi instalada e monitorizada

Erro de autenticação

Problema

A API devolve um erro de autenticação ou uma resposta 401 Não autorizado.

Causas possíveis

Chave de API inválida: Chave de API incorrecta ou não fornecida
Tipo de chave incorreto: Usando a chave SDK em vez da chave da API de relatório
Chave expirada: Chave de API revogada ou regenerada

Etapas de resolução

Navegue até Dashboard → Ferramentas do desenvolvedor → Chaves de API → Chave da API de relatórios
Copiar a chave da API de relatórios (NÃO a chave SDK)
Verificar se a chave da API foi colada corretamente no pedido
Se a chave foi regenerada recentemente, certifique-se de que utiliza o novo valor da chave

Aviso de segurança: Nunca submeta as chaves da API ao controlo de versões ou as exponha no código do lado do cliente. Use variáveis de ambiente ou gerenciamento de configuração seguro.

Erro de limitação de taxa

Problema

A API retorna 429 Too Many Requests ou erro de limite de taxa.

Causas possíveis

Solicitações excessivas: Demasiadas chamadas à API num curto período de tempo
Utilização em produção: API utilizada em ambiente de produção (caso de utilização não previsto)

Etapas de resolução

Implementar backoff exponencial e lógica de repetição no código
Espaçar os pedidos de API (recomenda-se um intervalo mínimo de 1 segundo entre as chamadas)
Armazenar em cache os dados de atribuição quando possível para reduzir as chamadas de API
Contactar o Singular Support se os testes legítimos exigirem limites de taxa mais elevados

Limitação Beta: A API Attribution Details foi projetada apenas para testes. Não utilizar em aplicações de produção com elevados volumes de pedidos.

Melhores práticas

Recomendações para uma verificação eficaz da atribuição durante o teste de integração e a validação da campanha.

Fluxo de trabalho de teste

Processo de teste recomendado

Utilizar dispositivos novos: Teste com dispositivos limpos ou redefina os identificadores de publicidade antes do teste para evitar a atribuição em cache
Verificar imediatamente: Verifique a atribuição dentro de 5 a 10 minutos após a instalação para obter feedback rápido durante o teste
Teste vários cenários: Valide a atribuição para diferentes fontes (orgânicas, campanhas pagas, reengajamento)
Documentar resultados: Registre os resultados da verificação de atribuição para a documentação de validação da integração
Automatize quando possível: Use a API Attribution Details em conjuntos de testes automatizados para validação contínua

Guia de seleção de métodos

Quando usar cada método

Cenário	Método recomendado
Teste manual rápido	Aplicação Device Assist - verificação visual mais rápida durante o desenvolvimento
Testes automatizados	API Attribution Details - verificação programática em pipelines de CI/CD
Testes não técnicos	Device Assist App - não requer conhecimento de codificação ou API
Verificação de dispositivos em lote	API Attribution Details - script de verificações de vários dispositivos
Validação de rastreamento de eventos	Ambos os métodos - Device Assist para verificação rápida, API para análise detalhada de eventos

Lista de verificação da validação da integração

Lista de verificação de atribuição

Validação completa da atribuição:

Instalação atribuída à rede/fonte correta
O nome da campanha corresponde à campanha esperada
Carimbo de data/hora da atribuição razoável (dentro do período de tempo esperado)
Método de atribuição apropriado (clique vs. impressão)
Parâmetros personalizados passados corretamente através do link de rastreamento
Eventos de sessão rastreados corretamente
Eventos personalizados que aparecem com nomes corretos
Eventos de receita que capturam valores e moeda
Atribuição de reengajamento a funcionar (se aplicável)
Rastreamento de desinstalação configurado (se implementado)

Recursos adicionais

Documentação completa para testes de atribuição, integração de SDK e configuração de links de rastreamento.

Documentação relacionada

Usando o console de teste- Guia completo de teste de integração do SDK
Como testar um link de rastreamento- Procedimentos de validação de links de rastreamento
Understanding Singular Mobile App Attribution- Metodologia e processo de atribuição
Parâmetros do link de rastreamento e dimensões do relatório- Referência completa de parâmetros
Perguntas frequentes sobre atribuição de reengajamento- Documentação sobre atribuição de reengajamento

Como verificar a atribuição de dispositivos

Verificar a atribuição de dispositivos

Casos de uso de verificação de atribuição

Quando verificar a atribuição

Comparação de métodos

Escolhendo o método de verificação

Método 1: Aplicação de assistência ao dispositivo

Visão geral da aplicação Device Assist

Recursos do aplicativo

Utilização da aplicação Device Assist

Procedimento passo a passo

Descarregar a aplicação Device Assist

Iniciar o Attribution Check

Selecionar identificador do dispositivo

Rever detalhes de atribuição

Informações de atribuição exibidas

Interpretando a atribuição da instalação

Requisitos de atribuição de reengajamento

Validando o rastreamento de eventos

Solução de problemas do Device Assist

Problemas comuns

Causas possíveis

Etapas de resolução

Causas possíveis

Etapas de resolução

Causas possíveis

Passos de resolução

Método 2: API de detalhes de atribuição

Especificação do ponto de extremidade da API

Formato da solicitação

Parâmetros de consulta

Parâmetros necessários

Resposta da API

Formato da resposta

Exemplo de resposta

Parâmetros de resposta

Campos da resposta JSON

Exemplos de uso da API

Exemplos de implementação

Dispositivo iOS (IDFA)

Dispositivo Android (GAID)

Rastreamento da Web (SDID)

Implementação em Python

Implementação em JavaScript

Resolução de problemas da API

Problemas comuns da API

Problema

Causas possíveis

Passos de resolução

Problema

Causas possíveis

Etapas de resolução

Problema

Causas possíveis

Etapas de resolução

Melhores práticas

Fluxo de trabalho de teste

Processo de teste recomendado

Guia de seleção de métodos

Quando usar cada método

Lista de verificação da validação da integração

Lista de verificação de atribuição

Recursos adicionais

Documentação relacionada