Verificação da atribuição do dispositivo

Guia completo para validar a atribuição do dispositivo usando o aplicativo Singular Device Assist e o endpoint da API de detalhes de atribuição para testes de integração e verificação de links de rastreamento.

O Singular oferece dois métodos para verificar a atribuição do dispositivo: o aplicativo Device Assist para testes em dispositivos móveis e o endpoint da API de detalhes de atribuição para verificação programática.

Verificar a atribuição é uma parte essencial dos testes de novas integrações SDK/S2S e da validação de Singular Links antes do lançamento de campanhas.

Público-alvo	Gerentes de UA, Desenvolvedores, Engenheiros de QA
Pré-requisitos	Dispositivo móvel para testes (método do aplicativo Device Assist) Chave de API do Singular (método do endpoint de API) Identificador publicitário do dispositivo (IDFA, IDFV, GAID, etc.)

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

Quando verificar a atribuição

A verificação da atribuição do dispositivo é fundamental em múltiplos estágios do ciclo de vida da integração e do lançamento de campanhas.

Caso de uso	Objetivo
Testes de integração SDK/S2S	Validar se o SDK está rastreando corretamente as instalações e atribuindo às fontes corretas durante o desenvolvimento da integração. Guia completo do Console de testes
Validação de link de rastreamento	Testar novos Singular Links antes do lançamento de campanhas para garantir atribuição correta e passagem de parâmetros. Como testar um link de rastreamento
Solução de problemas de campanha	Diagnosticar problemas de atribuição em campanhas ativas verificando o status de atribuição do dispositivo de teste
Verificação de integração de parceiros	Confirmar que os dados de atribuição estão fluindo corretamente dos parceiros de publicidade para a plataforma Singular

Comparação de métodos

Como escolher o método de verificação

Selecione o método de verificação mais adequado com base nos requisitos de teste e nas capacidades técnicas.

Método	Ideal para	Requisitos	Limitações
Aplicativo Device Assist	Testes manuais rápidos Usuários não técnicos Verificação visual	Dispositivo móvel Instalação do aplicativo	Processo manual, automação limitada
API de detalhes de atribuição	Testes automatizados Verificação programática Integração CI/CD	Chave de API Identificador do dispositivo Cliente HTTP	Somente para testes (beta), requer conhecimento técnico

Método 1: Aplicativo Device Assist

Aplicativo móvel que fornece verificação visual rápida do status de atribuição do dispositivo, detalhes de instalação e resumo de rastreamento de eventos diretamente no dispositivo de teste.

Visão geral do aplicativo Device Assist

Funcionalidades do aplicativo

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

Dados de atribuição exibidos:

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

Usando o aplicativo Device Assist

Procedimento passo a passo

1	Baixar o aplicativo Device Assist Instale o aplicativo Singular Device Assist no dispositivo de teste: iOS: Baixar na App Store Android: Baixar no Google Play
2	Iniciar a verificação de atribuição Abra o aplicativo Device Assist e selecione Verificar implementação no menu principal. Recursos adicionais: O aplicativo Device Assist também oferece ferramentas de pesquisa de identificador do dispositivo e verificação de implementação do SDK acessíveis pelo menu principal.
3	Selecionar o identificador do dispositivo O aplicativo seleciona automaticamente o identificador de dispositivo adequado para a plataforma. Confirme a seleção e toque em Verificar implementação novamente para continuar. Seleção de identificador: iOS: IDFA (se ATT autorizado) ou IDFV (se ATT não autorizado ou não implementado) Android: GAID (Google Advertising ID) ou identificadores alternativos se GAID indisponível
4	Revisar os detalhes de atribuição O aplicativo exibe as informações de atribuição completas do dispositivo conforme registradas na plataforma Singular. Informações de atribuição exibidas Detalhes de atribuição de instalação # Data/hora de instalação: Data e hora do primeiro início do aplicativo (evento de instalação) Rede atribuída: Rede de anúncios ou fonte creditada com a instalação (ex.: Facebook, Google Ads, Orgânico) Nome da campanha: Campanha de marketing atribuída à instalação Parâmetros adicionais: Parâmetros específicos da campanha transmitidos pelo link de rastreamento Interpretando a atribuição de instalação "Organic": Nenhum ponto de contato correspondente encontrado dentro da janela de atribuição — instalação não atribuída a campanha paga "Unattributed": 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 # Data/hora do reengajamento: Data e hora da sessão de reengajamento mais recente Rede atribuída: Fonte creditada por trazer o usuário de volta ao aplicativo Nome da campanha: Campanha de reengajamento atribuída à sessão Redes de autoatribuição: Atribuições de reengajamento de redes de autoatribuição (Twitter, Facebook, Google Ads, Snapchat, etc.) podem aparecer como "Unattributed" por razões de privacidade. Requisitos para atribuição de reengajamento Para que a atribuição de reengajamento ocorra: O usuário deve ter instalação existente (não ser novo dispositivo) 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: FAQ de atribuição de reengajamento Resumo de rastreamento de eventos # O aplicativo Device Assist exibe um resumo de todos os eventos in-app rastreados pelo Singular para o dispositivo. Informações de eventos exibidas: Nome do evento: Nome do evento rastreado (session, purchase, level_complete, etc.) Hora do primeiro evento: Data/hora da primeira ocorrência Hora do último evento: 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 de eventos para verificar: Sessões sendo rastreadas corretamente Eventos personalizados aparecendo com os nomes corretos Eventos de receita capturando os valores corretamente Datas/horas dos eventos correspondendo às ações reais do usuário

Solução de problemas do Device Assist

Problemas comuns

Nenhum dado de atribuição exibido

Possíveis causas

Aplicativo não instalado: O aplicativo de teste não foi instalado ou ainda não foi aberto no dispositivo
Identificador incorreto: O Device Assist está verificando um identificador não usado pelo SDK do aplicativo
SDK não inicializado: O SDK do Singular não foi inicializado corretamente no aplicativo
Atribuição pendente: Decisão de atribuição ainda não finalizada (normalmente leva de 1 a 5 minutos)

Passos de resolução

Verificar se o aplicativo de teste está instalado e foi aberto pelo menos uma vez no dispositivo
Confirmar se o identificador do dispositivo corresponde ao tipo de identificador usado no SDK (IDFA vs IDFV para iOS)
Aguardar de 5 a 10 minutos após o início do aplicativo e verificar a atribuição novamente
Verificar a integração do SDK usando o Console de testes

Atribuição à fonte incorreta

Possíveis causas

Uso anterior do dispositivo: Dispositivo usado anteriormente para testes com atribuição em cache
Múltiplos pontos de contato: Múltiplos cliques em campanhas dentro da janela de atribuição
Correspondência por impressão digital: Atribuição probabilística correspondeu ao clique incorreto

Passos de resolução

Redefinir o dispositivo e limpar a atribuição:
- Excluir o aplicativo de teste
- Redefinir o identificador publicitário
- Excluir o dispositivo do Console de testes se registrado
Usar um dispositivo novo ou redefinir o identificador antes dos testes
Usar atribuição determinística (ID do dispositivo no link de rastreamento) em vez de impressão digital para testes
Revisar as configurações de janela de atribuição na Configuração de parceiros

Instalação atribuída como orgânica em vez de à campanha

Possíveis causas

Janela de atribuição excedida: A instalação ocorreu fora da janela de atribuição configurada
Nenhum ponto de contato correspondente: Nenhum clique encontrado correspondente ao dispositivo
Impressão digital não correspondente: A impressão digital do dispositivo mudou entre o clique e a instalação
Link não clicado: Aplicativo instalado diretamente da loja sem clicar no link de rastreamento

Passos de resolução

Verificar se o link de rastreamento foi clicado antes de instalar o aplicativo
Verificar se as configurações de janela de atribuição permitem tempo suficiente para a instalação
Usar o ID do dispositivo no link de rastreamento (atribuição determinística) para testes confiáveis
Garantir conexão de rede estável durante o clique e a instalação
Testar em um dispositivo diferente ou redefinir o identificador e tentar novamente

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

Endpoint de API programático que permite a verificação automatizada de atribuição para testes de integração e pipelines CI/CD.

Aviso de recurso beta: O endpoint da API de detalhes de atribuição é um recurso beta. Use somente para fins de teste — não chame dentro de aplicativos em produção ou em ambientes de alto volume.

Especificação do endpoint de API

Formato da requisição

URL do endpoint:

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

Método da requisição: GET

Exemplo de requisição completa:

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 obrigatórios

Parâmetro Tipo Descrição


        api_key

String

Chave da API de relatórios do Singular na plataforma.

Localização: Dashboard → Developer Tools → API Keys → Reporting API Key

Importante: Use a Reporting API Key, não a SDK Key. Chaves diferentes servem para propósitos diferentes.


        device_id

String

Valor do identificador publicitário do dispositivo.

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


        keyspace

String (Enum)

Tipo de identificador publicitário fornecido em device_id :

idfa - Identificador iOS para anunciantes (requer autorização ATT)
idfv - Identificador iOS para fornecedores (alternativa quando IDFA indisponível)
aifa - Identificador Android para publicidade (também conhecido como GAID)
sdid - ID de dispositivo Singular para rastreamento web (recuperar usando singularSdk.getSingularDeviceId() após a inicialização do SDK)

Resposta da API

Formato da resposta

A API retorna um array JSON contendo os detalhes de atribuição para o dispositivo solicitado.

Resposta de exemplo

[
  {
    "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 bundle do aplicativo (ex.: com.example.myapp)
`app_name`	Nome de exibição do aplicativo conforme configurado na plataforma Singular
`install_info`	Objeto contendo os detalhes de atribuição de instalação e informações da decisão: `install_time` - Data/hora da primeira sessão do aplicativo (instalação) `network` - Rede de anúncios creditada pela instalação `campaign_name` - Nome da campanha atribuída à instalação `view_through_attribution` - Booleano indicando atribuição baseada em impressão publicitária (true) vs clique publicitário (false). Saiba mais: Processo de atribuição de instalações do Singular `additional_parameters` - Parâmetros personalizados transmitidos pelo link de rastreamento. Detalhes: Parâmetros do link de rastreamento e dimensões de relatórios
`re_engagement_info`	Objeto com a mesma estrutura de `install_info` mas para atribuição de reengajamento. Saiba mais: FAQ de atribuição de reengajamento Nota de privacidade: Atribuições de reengajamento de redes de autoatribuição (Facebook, Google Ads, Twitter, Snapchat) aparecem como "Unattributed" por conformidade de privacidade.
`events`	Array de objetos contendo o resumo de eventos in-app rastreados pelo SDK: `event_name` - Nome do evento rastreado `first_event_time` - Data/hora da primeira ocorrência `last_event_time` - Data/hora da ocorrência mais recente `event_count` - Número total de ocorrências do evento `revenue` - Receita total para eventos de receita (se aplicável)
`uninstall_pre_requisites`	Objeto contendo a configuração de rastreamento de desinstalação: `apns` (iOS) - Token do Apple Push Notification Service. Configuração: Rastreamento de desinstalação no iOS `gcm_token` (Android) - Token do Firebase Cloud Messaging. Configuração: Rastreamento de desinstalação no 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 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);
});

Solução de problemas da API

Problemas comuns da API

Resposta de array vazio

Problema

A API retorna array vazio [] em vez de dados de atribuição.

Possíveis causas

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

Passos de resolução

Verificar se o ID do dispositivo foi copiado corretamente sem espaços extras
Confirmar se o keyspace corresponde ao tipo de identificador (idfa vs idfv para iOS)
Aguardar de 5 a 10 minutos após a instalação do aplicativo e tentar a consulta novamente
Verificar a atribuição do dispositivo usando o aplicativo Device Assist para confirmar se o aplicativo está instalado e sendo rastreado

Erro de autenticação

Problema

A API retorna erro de autenticação ou resposta 401 Não autorizado.

Possíveis causas

Chave de API inválida: Chave de API incorreta ou não fornecida
Tipo de chave incorreto: Usando SDK Key em vez da Reporting API Key
Chave expirada: Chave de API revogada ou regenerada

Passos de resolução

Navegar para Dashboard → Developer Tools → API Keys → Reporting API Key
Copiar a Reporting API Key (NÃO a SDK Key)
Verificar se a chave de API foi colada corretamente na requisição
Se a chave foi regenerada recentemente, garantir que o novo valor está sendo usado

Aviso de segurança: Nunca faça commit de chaves de API no controle de versão ou as exponha em código do lado do cliente. Use variáveis de ambiente ou gerenciamento seguro de configuração.

Erro de limite de taxa

Problema

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

Possíveis causas

Requisições excessivas: Muitas chamadas de API em curto período de tempo
Uso em produção: API usada em ambiente de produção (uso não previsto)

Passos de resolução

Implementar lógica de backoff exponencial e repetição no código
Espaçar as requisições de API (mínimo de 1 segundo entre chamadas recomendado)
Armazenar dados de atribuição em cache quando possível para reduzir chamadas de API
Contatar o suporte do Singular se os testes legítimos exigirem limites de taxa mais altos

Limitação beta: A API de detalhes de atribuição foi projetada apenas para testes. Não use em aplicativos de produção com altos volumes de requisições.

Melhores práticas

Recomendações para uma verificação de atribuição eficaz durante os testes de integração e a validação de campanhas.

Fluxo de trabalho de testes

Processo de testes recomendado

Usar dispositivos novos: Testar com dispositivos limpos ou redefinir identificadores publicitários antes dos testes para evitar atribuição em cache
Verificar imediatamente: Verificar a atribuição dentro de 5 a 10 minutos após a instalação para feedback rápido durante os testes
Testar múltiplos cenários: Validar a atribuição para diferentes fontes (orgânica, campanhas pagas, reengajamento)
Documentar os resultados: Registrar os resultados de verificação de atribuição para a documentação de validação de integração
Automatizar quando possível: Usar a API de detalhes de atribuição em suites de testes automatizados para validação contínua

Guia de seleção de método

Quando usar cada método

Cenário	Método recomendado
Testes manuais rápidos	Aplicativo Device Assist — verificação visual mais rápida durante o desenvolvimento
Testes automatizados	API de detalhes de atribuição — verificação programática em pipelines CI/CD
Testes não técnicos	Aplicativo Device Assist — não requer programação ou conhecimento de API
Verificação de múltiplos dispositivos	API de detalhes de atribuição — script para verificar múltiplos 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 de validação de integração

Lista de verificação de atribuição

Validação completa de atribuição:

Instalação atribuída à rede/fonte correta
Nome da campanha corresponde à campanha esperada
Data/hora de atribuição razoável (dentro do prazo esperado)
Método de atribuição apropriado (clique vs impressão)
Parâmetros personalizados transmitidos corretamente pelo link de rastreamento
Eventos de sessão rastreados corretamente
Eventos personalizados aparecendo com os nomes corretos
Eventos de receita capturando valores e moeda
Atribuição de reengajamento funcionando (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 testes - Guia completo de testes de integração de SDK
Como testar um link de rastreamento - Procedimentos de validação de links de rastreamento
Entendendo a atribuição de aplicativos móveis do Singular - Metodologia e processo de atribuição
Parâmetros do link de rastreamento e dimensões de relatórios - Referência completa de parâmetros
FAQ de atribuição de reengajamento - Documentação sobre atribuição de reengajamento

Como verificar a atribuição do dispositivo

Verificação da atribuição do dispositivo

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

Quando verificar a atribuição

Comparação de métodos

Como escolher o método de verificação

Método 1: Aplicativo Device Assist

Visão geral do aplicativo Device Assist

Funcionalidades do aplicativo

Usando o aplicativo Device Assist

Procedimento passo a passo

Baixar o aplicativo Device Assist

Iniciar a verificação de atribuição

Selecionar o identificador do dispositivo

Revisar os detalhes de atribuição

Informações de atribuição exibidas

Interpretando a atribuição de instalação

Requisitos para atribuição de reengajamento

Validando o rastreamento de eventos

Solução de problemas do Device Assist

Problemas comuns

Possíveis causas

Passos de resolução

Possíveis causas

Passos de resolução

Possíveis causas

Passos de resolução

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

Especificação do endpoint de API

Formato da requisição

Parâmetros de consulta

Parâmetros obrigatórios

Resposta da API

Formato da resposta

Resposta de exemplo

Parâmetros de resposta

Campos da resposta JSON

Exemplos de uso da API

Exemplos de implementação

Dispositivo iOS (IDFA)

Dispositivo Android (GAID)

Rastreamento web (SDID)

Implementação em Python

Implementação em JavaScript

Solução de problemas da API

Problemas comuns da API

Problema

Possíveis causas

Passos de resolução

Problema

Possíveis causas

Passos de resolução

Problema

Possíveis causas

Passos de resolução

Melhores práticas

Fluxo de trabalho de testes

Processo de testes recomendado

Guia de seleção de método

Quando usar cada método

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

Lista de verificação de atribuição

Recursos adicionais

Documentação relacionada