Verificación de la atribución del dispositivo

Guía completa para validar la atribución del dispositivo mediante la aplicación Singular Device Assist y el endpoint de la API de detalles de atribución para pruebas de integración y verificación de enlaces de seguimiento.

Singular ofrece dos métodos para verificar la atribución del dispositivo: la aplicación Device Assist para pruebas en dispositivos móviles y el endpoint de la API de detalles de atribución para verificación programática.

Verificar la atribución es una parte esencial de las pruebas de nuevas integraciones SDK/S2S y de la validación de Singular Links antes del lanzamiento de campañas.

Público objetivo	Gerentes de UA, Desarrolladores, Ingenieros de QA
Requisitos previos	Dispositivo móvil para pruebas (método de la aplicación Device Assist) Clave API de Singular (método del endpoint de API) Identificador publicitario del dispositivo (IDFA, IDFV, GAID, etc.)

Casos de uso de verificación de atribución

Cuándo verificar la atribución

La verificación de atribución del dispositivo es fundamental en múltiples etapas del ciclo de vida de la integración y el despliegue de campañas.

Caso de uso	Propósito
Pruebas de integración SDK/S2S	Validar que el SDK realice correctamente el seguimiento de instalaciones y las atribuya a las fuentes correctas durante el desarrollo de la integración. Guía completa de la Consola de pruebas
Validación de enlace de seguimiento	Probar nuevos Singular Links antes del lanzamiento de campañas para garantizar una atribución y un paso de parámetros correctos. Cómo probar un enlace de seguimiento
Resolución de problemas de campaña	Diagnosticar problemas de atribución en campañas activas verificando el estado de atribución del dispositivo de prueba
Verificación de integración de socios	Confirmar que los datos de atribución fluyen correctamente desde los socios publicitarios hacia la plataforma Singular

Comparación de métodos

Cómo elegir el método de verificación

Selecciona el método de verificación más adecuado según los requisitos de prueba y las capacidades técnicas.

Método	Ideal para	Requisitos	Limitaciones
Aplicación Device Assist	Pruebas manuales rápidas Usuarios no técnicos Verificación visual	Dispositivo móvil Instalación de la aplicación	Proceso manual, automatización limitada
API de detalles de atribución	Pruebas automatizadas Verificación programática Integración CI/CD	Clave API Identificador del dispositivo Cliente HTTP	Solo para pruebas (beta), requiere conocimientos técnicos

Método 1: Aplicación Device Assist

Aplicación móvil que ofrece una verificación visual rápida del estado de atribución del dispositivo, los detalles de instalación y el resumen de seguimiento de eventos directamente en el dispositivo de prueba.

Descripción general de la aplicación Device Assist

Funcionalidades de la aplicación

La aplicación Device Assist muestra información de atribución completa registrada en Singular para el dispositivo específico.

Datos de atribución mostrados:

Atribución de instalación: Marca de tiempo de instalación, red atribuida y nombre de campaña
Atribución de reincorporación: Marca de tiempo de reincorporación, red atribuida y detalles de campaña
Resumen de eventos: Sesiones y eventos in-app rastreados por Singular para el dispositivo
Identificadores del dispositivo: IDFA, IDFV, GAID u otros identificadores utilizados para el seguimiento

Uso de la aplicación Device Assist

Procedimiento paso a paso

1	Descargar la aplicación Device Assist Instala la aplicación Singular Device Assist en el dispositivo de prueba: iOS: Descargar desde App Store Android: Descargar desde Google Play
2	Iniciar la verificación de atribución Abre la aplicación Device Assist y selecciona Verificar implementación en el menú principal. Funciones adicionales: La aplicación Device Assist también proporciona herramientas de búsqueda de identificadores de dispositivo y verificación de implementación de SDK accesibles desde el menú principal.
3	Seleccionar el identificador del dispositivo La aplicación selecciona automáticamente el identificador de dispositivo adecuado para la plataforma. Confirma la selección y toca Verificar implementación de nuevo para continuar. Selección de identificador: iOS: IDFA (si ATT está autorizado) o IDFV (si ATT no está autorizado o no está implementado) Android: GAID (Google Advertising ID) o identificadores alternativos si GAID no está disponible
4	Revisar los detalles de atribución La aplicación muestra la información de atribución completa del dispositivo según lo registrado en la plataforma Singular. Información de atribución mostrada Detalles de atribución de instalación # Marca de tiempo de instalación: Fecha y hora del primer inicio de la aplicación (evento de instalación) Red atribuida: Red publicitaria o fuente a la que se acredita la instalación (por ejemplo, Facebook, Google Ads, Orgánico) Nombre de campaña: Campaña de marketing atribuida a la instalación Parámetros adicionales: Parámetros específicos de la campaña transmitidos a través del enlace de seguimiento Interpretación de la atribución de instalación "Organic": No se encontró ningún punto de contacto coincidente dentro de la ventana de atribución; la instalación no se atribuyó a ninguna campaña de pago "Unattributed": Dispositivo rastreado, pero la decisión de atribución está pendiente o incompleta Nombre de red: Instalación atribuida exitosamente a un socio publicitario específico Detalles de atribución de reincorporación # Marca de tiempo de reincorporación: Fecha y hora de la sesión de reincorporación más reciente Red atribuida: Fuente a la que se acredita haber traído al usuario de vuelta a la aplicación Nombre de campaña: Campaña de reincorporación atribuida a la sesión Redes de autoatribución: Las atribuciones de reincorporación de redes de autoatribución (Twitter, Facebook, Google Ads, Snapchat, etc.) pueden mostrarse como "Unattributed" por razones de privacidad. Requisitos para la atribución de reincorporación Para que se produzca la atribución de reincorporación: El usuario debe tener una instalación previa (no ser un dispositivo nuevo) El clic en la campaña de reincorporación debe ocurrir dentro de la ventana de atribución configurada La sesión debe ocurrir después del clic de reincorporación Más información: Preguntas frecuentes sobre atribución de reincorporación Resumen de seguimiento de eventos # La aplicación Device Assist muestra un resumen de todos los eventos in-app rastreados por Singular para el dispositivo. Información de eventos mostrada: Nombre del evento: Nombre del evento rastreado (session, purchase, level_complete, etc.) Hora del primer evento: Marca de tiempo de la primera ocurrencia Hora del último evento: Marca de tiempo de la ocurrencia más reciente Recuento de eventos: Número total de veces que ocurrió el evento Ingresos: Ingresos totales para eventos de ingresos Validación del seguimiento de eventos Usa el resumen de eventos para verificar: Que las sesiones se estén rastreando correctamente Que los eventos personalizados aparezcan con los nombres correctos Que los eventos de ingresos capturen los montos correctamente Que las marcas de tiempo de eventos coincidan con las acciones reales del usuario

Solución de problemas de Device Assist

Problemas comunes

No se muestran datos de atribución

Posibles causas

Aplicación no instalada: La aplicación de prueba no está instalada o no se ha abierto aún en el dispositivo
Identificador incorrecto: Device Assist está verificando un identificador que no utiliza el SDK de la aplicación
SDK no inicializado: El SDK de Singular no está correctamente inicializado en la aplicación
Atribución pendiente: La decisión de atribución aún no está finalizada (normalmente tarda entre 1 y 5 minutos)

Pasos de resolución

Verificar que la aplicación de prueba esté instalada y abierta al menos una vez en el dispositivo
Confirmar que el identificador del dispositivo coincide con el tipo de identificador utilizado en el SDK (IDFA vs IDFV para iOS)
Esperar de 5 a 10 minutos después del inicio de la aplicación y verificar la atribución nuevamente
Verificar la integración del SDK usando la Consola de pruebas

Atribución a la fuente incorrecta

Posibles causas

Uso previo del dispositivo: El dispositivo fue usado anteriormente para pruebas con atribución en caché
Múltiples puntos de contacto: Múltiples clics en campañas dentro de la ventana de atribución
Coincidencia por huella digital: La atribución probabilística coincidió con el clic incorrecto

Pasos de resolución

Restablecer el dispositivo y borrar la atribución:
- Eliminar la aplicación de prueba
- Restablecer el identificador publicitario
- Eliminar el dispositivo de la Consola de pruebas si está registrado
Usar un dispositivo nuevo o restablecer el identificador antes de las pruebas
Usar atribución determinística (ID del dispositivo en el enlace de seguimiento) en lugar de huella digital para las pruebas
Revisar la configuración de ventana de atribución en la Configuración de socios

Instalación atribuida como orgánica en lugar de a una campaña

Posibles causas

Ventana de atribución superada: La instalación ocurrió fuera de la ventana de atribución configurada
Sin punto de contacto coincidente: No se encontró ningún clic que coincida con el dispositivo
Huella digital no coincide: La huella digital del dispositivo cambió entre el clic y la instalación
Enlace no clicado: La aplicación se instaló directamente desde la tienda sin hacer clic en el enlace de seguimiento

Pasos de resolución

Verificar que se haya hecho clic en el enlace de seguimiento antes de instalar la aplicación
Comprobar que la configuración de ventana de atribución permite tiempo suficiente para la instalación
Usar el ID del dispositivo en el enlace de seguimiento (atribución determinística) para pruebas confiables
Garantizar una conexión de red estable durante el clic y la instalación
Probar en un dispositivo diferente o restablecer el identificador y volver a intentar

Método 2: API de detalles de atribución

Endpoint de API programático que permite la verificación automatizada de atribución para pruebas de integración y pipelines CI/CD.

Aviso de función beta: El endpoint de la API de detalles de atribución es una función beta. Úsala solo para pruebas; no la invoques dentro de aplicaciones en producción ni en entornos de alto volumen.

Especificación del endpoint de API

Formato de solicitud

URL del endpoint:

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

Método de solicitud: GET

Ejemplo de solicitud 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 requeridos

Parámetro Tipo Descripción


        api_key

String

Clave de la API de informes de Singular desde la plataforma.

Ubicación: Dashboard → Developer Tools → API Keys → Reporting API Key

Importante: Usa la Reporting API Key, no la SDK Key. Las distintas claves sirven para propósitos diferentes.


        device_id

String

Valor del identificador publicitario del dispositivo.

Debe coincidir con el tipo de identificador especificado en el parámetro keyspace .


        keyspace

String (Enum)

Tipo de identificador publicitario proporcionado en device_id :

idfa - Identificador para anunciantes de iOS (requiere autorización ATT)
idfv - Identificador de iOS para proveedores (alternativa cuando IDFA no está disponible)
aifa - Identificador de Android para publicidad (también conocido como GAID)
sdid - ID de dispositivo Singular para seguimiento web (obtener usando singularSdk.getSingularDeviceId() después de la inicialización del SDK)

Respuesta de la API

Formato de respuesta

La API devuelve un array JSON que contiene los detalles de atribución del dispositivo solicitado.

Respuesta de ejemplo

[
  {
    "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 respuesta

Campos de la respuesta JSON

Campo	Descripción
`app_long_name`	Identificador del bundle de la aplicación (por ejemplo, com.example.myapp)
`app_name`	Nombre de visualización de la aplicación según la configuración en la plataforma Singular
`install_info`	Objeto que contiene los detalles de atribución de instalación e información de la decisión: `install_time` - Marca de tiempo de la primera sesión de la aplicación (instalación) `network` - Red publicitaria a la que se acredita la instalación `campaign_name` - Nombre de campaña atribuido a la instalación `view_through_attribution` - Booleano que indica si la atribución se basa en una impresión publicitaria (true) o en un clic publicitario (false). Más información: Proceso de atribución de instalaciones de Singular `additional_parameters` - Parámetros personalizados transmitidos a través del enlace de seguimiento. Detalles: Parámetros del enlace de seguimiento y dimensiones de informes
`re_engagement_info`	Objeto con la misma estructura que `install_info` pero para la atribución de reincorporación. Más información: Preguntas frecuentes sobre atribución de reincorporación Nota de privacidad: Las atribuciones de reincorporación de redes de autoatribución (Facebook, Google Ads, Twitter, Snapchat) aparecen como "Unattributed" por cumplimiento de privacidad.
`events`	Array de objetos que contiene el resumen de eventos in-app rastreados por el SDK: `event_name` - Nombre del evento rastreado `first_event_time` - Marca de tiempo de la primera ocurrencia `last_event_time` - Marca de tiempo de la ocurrencia más reciente `event_count` - Número total de ocurrencias del evento `revenue` - Ingresos totales para eventos de ingresos (si aplica)
`uninstall_pre_requisites`	Objeto que contiene la configuración de seguimiento de desinstalaciones: `apns` (iOS) - Token del servicio de notificaciones push de Apple. Configuración: Seguimiento de desinstalaciones en iOS `gcm_token` (Android) - Token de Firebase Cloud Messaging. Configuración: Seguimiento de desinstalaciones en Android

Ejemplos de uso de la API

Ejemplos de implementación

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"

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

Implementación en 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')}")

Implementación en 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);
});

Solución de problemas de la API

Problemas comunes de la API

Respuesta de array vacío

Problema

La API devuelve un array vacío [] en lugar de datos de atribución.

Posibles causas

Sin datos de atribución: El dispositivo nunca instaló la aplicación o no se registró ninguna sesión
Identificador incorrecto: El ID del dispositivo o el keyspace son incorrectos
Problema de tiempo: Los datos de atribución aún no se procesaron (normalmente tarda entre 1 y 5 minutos después de la instalación)

Pasos de resolución

Verificar que el ID del dispositivo se copió correctamente sin espacios adicionales
Confirmar que el keyspace coincide con el tipo de identificador (idfa vs idfv para iOS)
Esperar de 5 a 10 minutos después de la instalación de la aplicación y volver a consultar
Verificar la atribución del dispositivo usando la aplicación Device Assist para confirmar que la aplicación está instalada y con seguimiento

Error de autenticación

Problema

La API devuelve un error de autenticación o una respuesta 401 No autorizado.

Posibles causas

Clave API inválida: La clave API es incorrecta o no se proporcionó
Tipo de clave incorrecto: Se usa la SDK Key en lugar de la Reporting API Key
Clave expirada: La clave API fue revocada o regenerada

Pasos de resolución

Navegar a Dashboard → Developer Tools → API Keys → Reporting API Key
Copiar la Reporting API Key (NO la SDK Key)
Verificar que la clave API se pegó correctamente en la solicitud
Si la clave fue regenerada recientemente, asegurarse de usar el nuevo valor

Advertencia de seguridad: Nunca confirmes claves API en control de versiones ni las expongas en código del lado del cliente. Usa variables de entorno o gestión de configuración segura.

Error de límite de tasa

Problema

La API devuelve el error 429 Too Many Requests o un error de límite de tasa.

Posibles causas

Solicitudes excesivas: Demasiadas llamadas a la API en un corto período de tiempo
Uso en producción: La API se usa en un entorno de producción (uso no previsto)

Pasos de resolución

Implementar lógica de retroceso exponencial y reintentos en el código
Espaciar las solicitudes de API (se recomienda un mínimo de 1 segundo entre llamadas)
Almacenar en caché los datos de atribución cuando sea posible para reducir las llamadas a la API
Contactar al soporte de Singular si las pruebas legítimas requieren límites de tasa más altos

Limitación beta: La API de detalles de atribución está diseñada solo para pruebas. No la uses en aplicaciones de producción con altos volúmenes de solicitudes.

Mejores prácticas

Recomendaciones para una verificación de atribución efectiva durante las pruebas de integración y la validación de campañas.

Flujo de trabajo de pruebas

Proceso de pruebas recomendado

Usar dispositivos nuevos: Probar con dispositivos limpios o restablecer identificadores publicitarios antes de las pruebas para evitar atribuciones en caché
Verificar de inmediato: Comprobar la atribución dentro de los 5 a 10 minutos después de la instalación para obtener retroalimentación rápida durante las pruebas
Probar múltiples escenarios: Validar la atribución para diferentes fuentes (orgánica, campañas de pago, reincorporación)
Documentar los resultados: Registrar los resultados de verificación de atribución para la documentación de validación de integración
Automatizar cuando sea posible: Usar la API de detalles de atribución en suites de pruebas automatizadas para una validación continua

Guía de selección de métodos

Cuándo usar cada método

Escenario	Método recomendado
Pruebas manuales rápidas	Aplicación Device Assist: verificación visual más rápida durante el desarrollo
Pruebas automatizadas	API de detalles de atribución: verificación programática en pipelines CI/CD
Pruebas no técnicas	Aplicación Device Assist: no requiere programación ni conocimientos de API
Verificación de múltiples dispositivos	API de detalles de atribución: script para verificar múltiples dispositivos
Validación de seguimiento de eventos	Ambos métodos: Device Assist para una verificación rápida, API para un análisis detallado de eventos

Lista de verificación de validación de integración

Lista de verificación de atribución

Validación completa de atribución:

Instalación atribuida a la red/fuente correcta
El nombre de campaña coincide con la campaña esperada
La marca de tiempo de atribución es razonable (dentro del plazo esperado)
El método de atribución es apropiado (clic vs impresión)
Los parámetros personalizados se transmiten correctamente a través del enlace de seguimiento
Los eventos de sesión se rastrean correctamente
Los eventos personalizados aparecen con los nombres correctos
Los eventos de ingresos capturan los montos y la moneda
La atribución de reincorporación funciona (si aplica)
El seguimiento de desinstalaciones está configurado (si está implementado)

Recursos adicionales

Documentación completa para pruebas de atribución, integración de SDK y configuración de enlaces de seguimiento.

Documentación relacionada

Uso de la Consola de pruebas - Guía completa de pruebas de integración de SDK
Cómo probar un enlace de seguimiento - Procedimientos de validación de enlaces de seguimiento
Entender la atribución de aplicaciones móviles de Singular - Metodología y proceso de atribución
Parámetros del enlace de seguimiento y dimensiones de informes - Referencia completa de parámetros
Preguntas frecuentes sobre atribución de reincorporación - Documentación sobre atribución de reincorporación

Cómo verificar la atribución del dispositivo

Verificación de la atribución del dispositivo

Casos de uso de verificación de atribución

Cuándo verificar la atribución

Comparación de métodos

Cómo elegir el método de verificación

Método 1: Aplicación Device Assist

Descripción general de la aplicación Device Assist

Funcionalidades de la aplicación

Uso de la aplicación Device Assist

Procedimiento paso a paso

Descargar la aplicación Device Assist

Iniciar la verificación de atribución

Seleccionar el identificador del dispositivo

Revisar los detalles de atribución

Información de atribución mostrada

Interpretación de la atribución de instalación

Requisitos para la atribución de reincorporación

Validación del seguimiento de eventos

Solución de problemas de Device Assist

Problemas comunes

Posibles causas

Pasos de resolución

Posibles causas

Pasos de resolución

Posibles causas

Pasos de resolución

Método 2: API de detalles de atribución

Especificación del endpoint de API

Formato de solicitud

Parámetros de consulta

Parámetros requeridos

Respuesta de la API

Formato de respuesta

Respuesta de ejemplo

Parámetros de respuesta

Campos de la respuesta JSON

Ejemplos de uso de la API

Ejemplos de implementación

Dispositivo iOS (IDFA)

Dispositivo Android (GAID)

Seguimiento web (SDID)

Implementación en Python

Implementación en JavaScript

Solución de problemas de la API

Problemas comunes de la API

Problema

Posibles causas

Pasos de resolución

Problema

Posibles causas

Pasos de resolución

Problema

Posibles causas

Pasos de resolución

Mejores prácticas

Flujo de trabajo de pruebas

Proceso de pruebas recomendado

Guía de selección de métodos

Cuándo usar cada método

Lista de verificación de validación de integración

Lista de verificación de atribución

Recursos adicionales

Documentación relacionada