Documento

Verificación de la atribución de dispositivos

Guía completa para validar la atribución de dispositivos utilizando la aplicación Singular Device Assist y el punto final de la API Attribution Details para pruebas de integración y verificación de enlaces de seguimiento.

Singular ofrece dos métodos para comprobar la atribución de dispositivos: Device Assist app para pruebas móviles y Attribution Details API endpoint para verificación programática.

La verificación de la atribución es una parte esencial de las pruebas de la nueva integración SDK/S2S y de la validación de Singular Links antes del despliegue de la campaña.

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

Casos de uso de la verificación de la atribución

Cuándo verificar la atribución

La verificación de la atribución de dispositivos es crítica en múltiples etapas del ciclo de vida de integración y despliegue de campañas.

Caso de uso	Propósito
Pruebas de integración SDK/S2S	Validar que el SDK rastrea correctamente las instalaciones y atribuye a las fuentes correctas durante el desarrollo de la integración. Guía completa de la consola de pruebas
Validación de enlaces de seguimiento	Probar nuevos Enlaces Singulares antes del despliegue de la campaña para asegurar la correcta atribución y paso de parámetros. Cómo probar el enlace de seguimiento
Resolución de problemas de campaña	Diagnostique problemas de atribución en campañas en directo comprobando el estado de atribución del dispositivo de prueba.
Verificación de la integración de socios	Confirme que los datos de atribución fluyen correctamente desde los socios publicitarios a la plataforma Singular.

Comparación de métodos

Elección del método de verificación

Seleccione el método de verificación adecuado en función de los requisitos de prueba y las capacidades técnicas.

Método	Mejor 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	Verificación automatizada Verificación programática Integración CI/CD	Clave API Identificador de dispositivo Cliente HTTP	Sólo en pruebas (beta), requiere conocimientos técnicos

Método 1: Aplicación Device Assist

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

Descripción general de la aplicación Device Assist

Funciones de la aplicación

La aplicación Device Assist muestra toda la información de atribución registrada en Singular para un dispositivo específico.

Datos de atribución mostrados:

Atribución de instalación: Hora de instalación, red atribuida y nombre de la campaña
Re-engagement Attribution: Marca de tiempo de reconexión, red atribuida y detalles de la campaña.
Resumen de eventos: Sesiones y eventos dentro de la aplicación rastreados por Singular para el dispositivo.
Identificadores de dispositivo: IDFA, IDFV, GAID u otros identificadores utilizados para el seguimiento

Uso de la aplicación Device Assist

Procedimiento paso a paso

1	Descarga de la aplicación Device Assist Instale la aplicación Singular Device Assist en el dispositivo de prueba: iOS:Descargar desde App Store Android:Descargar desde Google Play
2	Inicie Attribution Check Abra la aplicación Device Assist y seleccione Check Implementationen el menú principal. Funciones adicionales: La app Device Assist también proporciona herramientas de búsqueda de identificadores de dispositivos y de verificación de implementación de SDK accesibles desde el menú principal.
3	Seleccionar identificador de dispositivo La aplicación selecciona automáticamente el identificador de dispositivo adecuado para la plataforma. Confirme la selección y vuelva a pulsar Comprobar implementaciónpara continuar. Selección del identificador: iOS: IDFA (si ATT está autorizada) o IDFV (si ATT no está autorizada o no está implementada) Android: GAID (Google Advertising ID) o identificadores alternativos si GAID no está disponible.
4	Revisar detalles de atribución La aplicación muestra la información de atribución completa para el dispositivo tal y como se registra en la plataforma Singular. Información de atribución mostrada Instalar detalles de atribución # Install Timestamp: Fecha y hora del primer lanzamiento de la aplicación (evento de instalación) Red atribuida: Red publicitaria o fuente a la que se atribuye la instalación (por ejemplo, Facebook, Google Ads, orgánica) Nombre de la campaña: Campaña de marketing atribuida a la instalación Parámetros adicionales: Parámetros específicos de la campaña pasados a través del enlace de seguimiento Interpretación de la atribución de la instalación "Orgánica": No se ha encontrado ningún punto de contacto coincidente dentro de la ventana de atribución - la instalación no se atribuye a la campaña de pago "No atribuida": Dispositivo rastreado pero decisión de atribución pendiente o incompleta Nombre de la red: Instalación atribuida correctamente a un socio publicitario específico Detalles de la atribución de reconexión # Marca de tiempo de la reconexión:Fecha y hora de la última sesión de reconexión Red atribuida: Fuente a la que se atribuye el regreso del usuario a la aplicación Nombre de la campaña: Campaña de reconexión atribuida a la sesión Redes autoatribuidas :Las atribuciones de reconexión de redes autoatribuidas (Twitter, Facebook, Google Ads, Snapchat, etc.) pueden mostrarse como "No atribuidas" por motivos de privacidad. Requisitos para la atribución de reconexión Para que se produzca la reatribución: El usuario debe tener una instalación existente (no un dispositivo nuevo) El clic en la campaña de reconexión debe producirse dentro de la ventana de atribución configurada. La sesión debe producirse después del clic de reconexión Más información: Preguntas frecuentes sobre la atribución de reconexión Resumen de seguimiento de eventos # La aplicación Device Assist muestra un resumen de todos los eventos dentro de la aplicación rastreados por Singular para el dispositivo. Se muestra la información del evento: Nombre del evento: Nombre del evento rastreado (sesión, compra, level_complete, etc.) Hora del primer evento: fecha y hora del primer evento. Hora del último evento: Fecha y hora del evento más reciente. Recuento de eventos: Número total de veces que ocurrió el evento Ingresos: Total de ingresos por eventos Validación del seguimiento de eventos Utilice el resumen de eventos para verificar Las sesiones se rastrean correctamente Los eventos personalizados aparecen con los nombres correctos Los eventos de ingresos capturan los importes correctamente Las marcas de tiempo de los eventos coinciden con las acciones reales de los usuarios

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 aún no se ha abierto en el dispositivo
Identificador incorrecto: Identificador de comprobación de Device Assist no utilizado por el SDK de la aplicación
SDK no inicializado: SDK Singular no inicializado correctamente en la app
Atribución pendiente: La decisión de atribución aún no ha finalizado (suele tardar entre 1 y 5 minutos)

Pasos de resolución

Compruebe que la aplicación de prueba se ha instalado y abierto al menos una vez en el dispositivo.
Confirme que el identificador del dispositivo coincide con el tipo de identificador utilizado en el SDK (IDFA frente a IDFV para iOS)
Espere de 5 a 10 minutos tras el inicio de la aplicación y vuelva a comprobar la atribución
Verifique la integración del SDK mediante la consola de pruebas

Atribución a una fuente incorrecta

Posibles causas

Uso anterior del dispositivo: Dispositivo utilizado previamente para pruebas con atribución en caché
Puntos de contacto múltiples: Múltiples clics de campaña dentro de la ventana de atribución
Coincidencia de huella digital: la atribución probabilística coincidió con un clic incorrecto

Pasos de resolución

Reinicie el dispositivo y borre la atribución:
- Borrar aplicación de prueba
- Restablecer identificador de publicidad
- Eliminar el dispositivo de la consola de pruebassi está registrado
Utilice un dispositivo nuevo o restablezca el identificador antes de realizar la prueba
Utilice la atribución determinista (identificador de dispositivo en el enlace de seguimiento) en lugar de la huella digital para las pruebas
Revise los ajustes de la ventana de atribución en Configuración de socios

Instalar atribución como orgánica en lugar de campaña

Posibles causas

Ventana de atribución superada: La instalación se produjo fuera de la ventana de atribución configurada
No Matching Touchpoint: No se ha encontrado ningún clic que coincida con el dispositivo
Huella digital no coincidente: La huella digital del dispositivo ha cambiado entre el clic y la instalación
Enlace no pulsado: Aplicación instalada directamente desde la tienda sin hacer clic en el enlace de seguimiento

Pasos de resolución

Compruebe que se ha hecho clic en el enlace de seguimiento antes de instalar la aplicación
Compruebe que la configuración de la ventana de atribución deja tiempo suficiente para la instalación
Utilice el ID del dispositivo en el enlace de seguimiento (atribución determinista) para realizar pruebas fiables.
Asegúrese de que la conexión a la red es estable durante el clic y la instalación
Pruebe en otro dispositivo o restablezca el identificador y vuelva a intentarlo.

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

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

Aviso de función beta: El punto final de la API de detalles de atribución es una función beta. Utilícela únicamente con fines de prueba; no la utilice en aplicaciones de producción ni en entornos de gran volumen.

Especificación del punto final de la API

Formato de solicitud

URL del punto final:

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 obligatorios

Parámetro Tipo Descripción

api_key

Cadena

Clave API de Reporting Singular de la plataforma.

Ubicación: Panel → Herramientas para desarrolladores → Claves API → Clave API de informes.

Importante: Utilice la clave de la API de informes, no la clave del SDK. Diferentes claves sirven para diferentes propósitos.

device_id

Cadena

Valor del identificador de publicidad del dispositivo.

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

keyspace

Cadena (Enum)

Tipo de identificador de publicidad proporcionado en device_id:

idfa - Identificador iOS para anunciantes (requiere autorización de la ATT)
idfv - Identificador iOS para vendedores (alternativa cuando IDFA no está disponible)
aifa - Identificador Android para publicidad (también conocido como GAID)
sdid - Identificador de dispositivo singular para seguimiento web (se recupera utilizando singularSdk.getSingularDeviceId() tras la inicialización del SDK)

Respuesta de la API

Formato de la respuesta

La API devuelve una matriz JSON con los detalles de atribución del dispositivo solicitado.

Ejemplo de respuesta

[
  {
    "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 paquete de aplicaciones (por ejemplo, com.example.myapp)
`app_name`	Nombre de visualización de la aplicación configurado en la plataforma Singular
`install_info`	Objeto que contiene detalles de atribución de instalación e información de decisión: `install_time` - Fecha y hora de la primera sesión de la aplicación (instalación) `network` - Red publicitaria a la que se atribuye la instalación `campaign_name` - Nombre de la campaña atribuida a la instalación `view_through_attribution` - Booleano que indica la atribución basada en la impresión del anuncio (verdadero) frente al clic del anuncio (falso). Más información: Proceso de atribución de instalación de Singular `additional_parameters` - Parámetros personalizados pasados a través del enlace de seguimiento. Detalles: Parámetros del enlace de seguimiento y dimensiones del informe
`re_engagement_info`	Objeto con la misma estructura que `install_info`pero para la atribución de reenganche. Más información: Preguntas frecuentes sobre la atribución de reconexión Nota sobre privacidad: las atribuciones de reconexión de redes de autoatribución (Facebook, Google Ads, Twitter, Snapchat) aparecen como "No atribuidas" para cumplir con la privacidad.
`events`	Conjunto de objetos que contienen el resumen de eventos dentro de la aplicación rastreados por el SDK: `event_name` - Nombre del evento rastreado `first_event_time` - Fecha y hora del primer evento `last_event_time` - Fecha y hora del evento más reciente `event_count` - Número total de eventos `revenue` - Ingresos totales de los eventos de ingresos (si procede)
`uninstall_pre_requisites`	Objeto que contiene la configuración de seguimiento de desinstalación: `apns` (iOS) - Token del servicio de notificaciones push de Apple Configuración: Seguimiento de desinstalaciones de iOS `gcm_token` (Android) - Token de Firebase Cloud Messaging. Configuración: Seguimiento de desinstalación de 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"

Rastreo 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);
});

Resolución de problemas de la API

Problemas comunes de la API

Respuesta de matriz vacía

Problema

La API devuelve una matriz vacía [] en lugar de datos de atribución.

Posibles causas

No hay datos de atribución: El dispositivo nunca instaló la aplicación o no se rastreó la sesión
Identificador incorrecto: ID de dispositivo o espacio clave incorrecto
Problema de tiempo: Los datos de atribución aún no se han procesado (normalmente entre 1 y 5 minutos después de la instalación).

Pasos de resolución

Compruebe que el identificador del dispositivo se ha copiado correctamente, sin espacios adicionales.
Confirmar que el espacio clave coincide con el tipo de identificador (idfa frente a idfv para iOS)
Espere de 5 a 10 minutos tras la instalación de la aplicación y vuelva a intentar la consulta
Compruebe la atribución del dispositivo mediante la aplicación Device Assist para verificar que la aplicación se ha instalado y rastreado.

Error de autenticación

Problema

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

Posibles causas

Clave de API no válida: Clave de API incorrecta o no proporcionada
Tipo de clave incorrecto: Uso de SDK Key en lugar de Reporting API Key
Clave caducada: Clave de API revocada o regenerada

Pasos para la resolución

Vaya a Panel de control → Herramientas de desarrollador → Claves API → Clave API de informes
Copie la clave API de informes (NO la clave SDK)
Compruebe que la clave de API se ha pegado correctamente en la solicitud
Si la clave se ha regenerado recientemente, asegúrese de utilizar el nuevo valor de clave

Advertencia de seguridad: Nunca envíe claves de API al control de versiones ni las exponga en código del lado del cliente. Utilice variables de entorno o una gestión segura de la configuración.

Error de limitación de velocidad

Problema

La API devuelve 429 Demasiadas solicitudes o error de límite de velocidad.

Posibles causas

Solicitudes excesivas: Demasiadas llamadas a la API en poco tiempo
Uso de producción: API utilizada en un entorno de producción (caso de uso no previsto)

Pasos de resolución

Implementar en el código una lógica exponencial de reintento.
Espaciar las peticiones a la API (se recomienda un mínimo de 1 segundo entre llamadas)
Almacene en caché los datos de atribución cuando sea posible para reducir las llamadas a la API.
Póngase en contacto con el soporte de Singular si las pruebas legítimas requieren límites de velocidad más altos

Limitación Beta: La API de detalles de atribución está diseñada únicamente para pruebas. No utilizar en aplicaciones de producción con grandes volúmenes de peticiones.

Mejores prácticas

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

Flujo de trabajo de las pruebas

Proceso de prueba recomendado

Utilice dispositivos nuevos: Pruebe con dispositivos limpios o restablezca los identificadores de publicidad antes de la prueba para evitar la atribución en caché
Verificar inmediatamente: Compruebe la atribución a los 5-10 minutos de la instalación para obtener información rápida durante las pruebas.
Pruebe múltiples escenarios: Valide la atribución para diferentes fuentes (orgánica, campañas de pago, reenganche)
Documente los resultados: Registre los resultados de la verificación de la atribución para la documentación de validación de la integración
Automatice cuando sea posible: Utilice la API de detalles de atribución en conjuntos de pruebas automatizadas para una validación continua.

Guía de selección de métodos

Cuándo utilizar cada método

Escenario	Método recomendado
Pruebas manuales rápidas	Device Assist App - verificación visual más rápida durante el desarrollo
Pruebas automatizadas	API de detalles de atribución: verificación programática en procesos CI/CD
Pruebas no técnicas	Aplicación Device Assist: no requiere codificación ni conocimientos de API
Verificación de dispositivos por lotes	API de detalles de atribución: verificación programada de varios dispositivos
Validación de seguimiento de eventos	Ambos métodos: Device Assist para una comprobación rápida y API para un análisis detallado de los eventos.

Lista de comprobación de la validación de la integración

Lista de verificación de la atribución

Validaciónde atribución completa:

Instalación atribuida a la red/fuente correcta
El nombre de la campaña coincide con la campaña esperada
La marca de tiempo de atribución es razonable (dentro del plazo previsto)
Método de atribución adecuado (clic o impresión)
Los parámetros personalizados se pasan correctamente a través del enlace de seguimiento
Eventos de sesión rastreados correctamente
Los eventos personalizados aparecen con los nombres correctos
Los eventos de ingresos capturan los importes y la moneda
Funcionamiento de la atribución de reconexión (si procede)
Seguimiento de desinstalación configurado (si está implementado)

Recursos adicionales

Documentación completa para pruebas de atribución, integración 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 del SDK
Cómo probar unenlace de seguimiento - Procedimientos de validación de enlaces de seguimiento
Comprender Singular Mobile App Attribution- Metodología y proceso de atribución
Parámetros del enlace de seguimiento y dimensiones del informe- Referencia completa de parámetros
Re-engagement Attribution FAQ- Documentación sobre la atribución de reenganche

Cómo verificar la atribución de dispositivos

Verificación de la atribución de dispositivos

Casos de uso de la verificación de la atribución

Cuándo verificar la atribución

Comparación de métodos

Elección del método de verificación

Método 1: Aplicación Device Assist

Descripción general de la aplicación Device Assist

Funciones de la aplicación

Uso de la aplicación Device Assist

Procedimiento paso a paso

Descarga de la aplicación Device Assist

Inicie Attribution Check

Seleccionar identificador de dispositivo

Revisar detalles de atribución

Información de atribución mostrada

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

Requisitos para la atribución de reconexió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 punto final de la API

Formato de solicitud

Parámetros de consulta

Parámetros obligatorios

Respuesta de la API

Formato de la respuesta

Ejemplo de respuesta

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)

Rastreo Web (SDID)

Implementación en Python

Implementación en JavaScript

Resolución de problemas de la API

Problemas comunes de la API

Problema

Posibles causas

Pasos de resolución

Problema

Posibles causas

Pasos para la resolución

Problema

Posibles causas

Pasos de resolución

Mejores prácticas

Flujo de trabajo de las pruebas

Proceso de prueba recomendado

Guía de selección de métodos

Cuándo utilizar cada método

Lista de comprobación de la validación de la integración

Lista de verificación de la atribución

Recursos adicionales

Documentación relacionada