Audiencias: API de identificadores adicionales

Para:

Marketers Desarrolladores

Última actualización: 19 de noviembre de 2024 11:14

De un vistazo: Utiliza la API de identificadores adicionales de audiencias para cargar masivamente identificadores de usuarios desde tus sistemas internos (como BI y CRM) a AppsFlyer Audiences, lo que permite una comunicación más amplia con socios relevantes basándose en estos identificadores.

Acerca de la API

La API de identificadores adicionales de audiencias se puede usar para añadir los siguientes identificadores de usuario desde tus sistemas internos a AppsFlyer Audiences:

Hasta 2 direcciones de correo electrónico cifradas
Número de teléfono cifrado
Número de teléfono E164 cifrado

Luego puedes optar por enviar estos identificadores a tus socios de Audiencias (sujeto a tu política de identificadores de usuario a nivel de cuenta), lo que les permitirá identificar de manera más precisa tus audiencias objetivo. Ten en cuenta que no todos los socios publicitarios admiten todos los identificadores.

¿Cuándo debo utilizar esta API?

Esta API está diseñada para usarse cuando necesitas cargar un gran volumen de datos de identificadores. Generalmente, esto se refiere a datos recopilados a lo largo del tiempo (por ejemplo, correos electrónicos en formato hash recopilados de todos los usuarios de una aplicación durante los últimos 12 meses). Para actualizaciones individuales en tiempo real de identificadores de dispositivos específicos, configura identificadores adicionales en el SDK de AppsFlyer o la API S2S-mobile.

¡Importante!

Cifrado: Todos los valores de identificadores adicionales deben estar cifrados con hash SHA256. Los identificadores no cifrados no serán procesados.

Tiempo: Para asegurar una coincidencia precisa de los identificadores, la API de identificadores adicionales de audiencias puede utilizarse tan pronto como el día posterior al reporte de los identificadores clave a través del SDK de AppsFlyer (UTC). Por ejemplo, los identificadores clave reportados el 3 de enero de 2022 (UTC) pueden actualizarse a través de esta API el 4 de enero de 2022 (UTC) o después.

Acciones

Autenticación

La solicitud debe incluir un encabezado HTTP que contenga el token API de AppsFlyer V2.0 de tu cuenta. Pide al administrador de tu cuenta que obtenga este token desde el panel de AppsFlyer.

Especificaciones de la API y código de ejemplo

Añadir/modificar identificadores (PUT)

URL de solicitud de la API

https://hq1.appsflyer.com/api/audience-bulk-api/v1/additional-identifiers/app/{app-id}

Parámetro	Descripción	Obligatorio
{id de la aplicación}	ID de la aplicación desde la que se recopilaron los identificadores (tal como aparece en el panel de AppsFlyer)	Sí

Cuerpo de la solicitud de API

{
  "key_type": "<key_type>",
  "action": "add",
  "data": [
    {
      "key_value": "<key_value>",
      "identifiers": {
        "hashed_emails": [
          "<hashed_email_value>",
          "<hashed_email_value>"
        ],
        "phone_number_sha256": "<phone_number_sha256_value>",
        "phone_number_e164_sha256": "<phone_number_e164_sha256_value>"
      }
    },
    {
      "key_value": "<key_value>",
      "identifiers": {
        "hashed_emails": [
          "<hashed_email_value>",
          "<hashed_email_value>"
        ],
        "phone_number_sha256": "<phone_number_sha256_value>",
        "phone_number_e164_sha256": "<phone_number_e164_sha256_value>"
      }
    }
  ]
}

Parámetro	Descripción	Obligatorio
{tipo_de_clave}	El identificador usado como valor único para representar al usuario en cada fila de datos de la solicitud. El valor especificado aquí se aplica a todas las filas de la solicitud. Valores posibles: idfa gaid idfv customer_user_id imei oaid	Sí
{acción}	agregar	No Valor por defecto: agregar
{valor_clave}	Valor de identificador válido para el tipo de clave especificado	Sí
{identificadores}	Objeto que contiene los nombres y valores de los identificadores a agregar: {hashed_emails} {phone_number_sha256} {phone_number_e164_sha256}	Sí * Debe incluir un valor para al menos uno de estos tres identificadores
{hashed_emails}	Un array de hasta dos direcciones de correo electrónico cifradas Formato: En minúsculas Sin espacios en blanco Con hash SHA256 Valor de ejemplo antes del hash: nombre@dominio.com	No
{phone_number_sha256}	Número de teléfono (ver nota a continuación) Formato: Sin símbolos, letras ni ceros iniciales Incluir código de país Con hash SHA256 Valor de ejemplo antes del hash: 442070313000	No
{phone_number_e164_sha256}	Número de teléfono en formato E164 (ver nota a continuación) Formato Número de teléfono E164 Con hash SHA256 Valor de ejemplo antes del hash: +442070313000	No

Nota

Diferentes socios publicitarios admiten distintos formatos de números de teléfono. Por lo tanto, si decide agregar un número de teléfono, se recomienda enviar ambos identificadores: phone_number_sha256 y phone_number_e164_sha256.

Restricciones

Las siguientes restricciones se aplican a la solicitud Agregar/modificar identificadores:

Los valores existentes previamente (si los hay) serán sobrescritos por los valores enviados en la solicitud.
El objeto {data} puede incluir un máximo de 4000 filas (key_values) por solicitud.

Solicitud de ejemplo para agregar identificadores

HTTP PUT
body:
{
  "key_type": "idfv",
  "action": "add",
  "data": [
    {
      "key_value": "CDDA802e-AAAA-BBBB-CCCC-DDDDDDDDDDDD",
      "identifiers": {
        "hashed_emails": [
          "34d31be18022626de6b311d6a76e791176d2691b6eef406f524d8f56364c187a",
          "d8c2aec999baad2464e521873ee4465caaf7ff6db8c8b4a25b09ca07694e4dee"
        ],
        "phone_number_sha256": "6c91c4c640f6ef0162833260db4f13dec0df2b683092f4dba7e874bef1acea37",
        "phone_number_e164_sha256": "f3d7e96c73fb0de1b66acfce541d7af758fbd4f3fa3af0ea4e10110000d3625e"
      }
    }
  ]
}

Eliminar identificadores (PUT)

URL de solicitud de la API

https://hq1.appsflyer.com/api/audience-bulk-api/v1/additional-identifiers/app/{app-id}

Parámetro	Descripción	Obligatorio
{id de la aplicación}	ID de la aplicación desde la que se recopilaron los identificadores (tal como aparece en el panel de AppsFlyer)	Sí

Cuerpo de la solicitud de API

{
  "key_type": "<key_type>",
  "action": "remove",
  "data": [
    {
      "key_value": ",<key_value>",
      "identifiers": [
        "hashed_emails",
        "phone_number_sha256",
        "phone_number_e164_sha256"
      ]
    },
    {
      "key_value": ",<key_value>",
      "identifiers": [
        "hashed_emails",
        "phone_number_sha256",
        "phone_number_e164_sha256"
      ]
    }
  ]
}

Parámetro	Descripción	Obligatorio
{tipo_de_clave}	El identificador usado como valor único para representar al usuario en cada fila de datos de la solicitud. El valor especificado aquí se aplica a todas las filas de la solicitud. Valores posibles: idfa gaid idfv customer_user_id imei oaid	Sí
{valor_clave}	Valor de identificador válido para el tipo de clave especificado	Sí
{acción}	eliminar	No Valor por defecto: agregar
{identificadores}	Un array que contiene los nombres de los identificadores cuyos valores deben eliminarse: {hashed_emails} {phone_number_sha256} {phone_number_e164_sha256}	Sí * Debe incluir al menos uno de estos tres identificadores

Restricciones

El objeto {data} puede incluir un máximo de 4000 filas (key_values) por solicitud.

Solicitud de ejemplo para eliminar identificadores

HTTP PUT
body:
{
  "key_type": "gaid",
  "action": "remove",
  "data": [
    {
      "key_value": "cdda802e-aaaa-bbbb-cccc-dddddddddddd",
      "identifiers": [
        "hashed_emails",
        "phone_number_sha256",
        "phone_number_e164_sha256"
      ]
    }
  ]
}

Respuestas

Código	Mensaje	Descripción
202	Aceptado para su procesamiento	La solicitud se aplicará en la siguiente ventana de procesamiento.
400	El cuerpo de la solicitud debe incluir un tipo de clave válido	Los siguientes tipos de clave son compatibles: idfa gaid idfv customer_user_id imei oaid
400	La solicitud debe contener 'datos' con al menos un elemento	La lista de datos no puede estar vacía.
400	La solicitud de 'datos' no debe superar los 4000 en una sola petición	La lista de datos puede contener un máximo de 4000 filas.
400	Los datos pedidos contienen demasiados elementos 'datos' no válidos	Más del 10% de los datos a modificar no son válidos según lo especificado.
404	AppsFlyer - Página no encontrada	Verifique que: El {app-id}, tal como se especifica en la URL de la solicitud de API, es correcto. El encabezado HTTP contiene el token API de AppsFlyer V2.0 correcto. El administrador de su cuenta puede obtener este token en el panel de control de AppsFlyer.

Ejemplos de respuestas

{
"message": "Accepted for processing",
"received": 1000,"invalid": 2,
"trace-id": "698ed323-c787-45b5-b792-463c67c94064"
}

{
"error": "Request body must have a valid key_type",
"trace-id": "18a5f685-ea4d-4ca9-beab-a542a3786d12"
}

{
"error": "Request must have 'data' with at least 1 element",
"trace-id": "c155a7fa-b573-4efe-9bfb-5ae7de40e7fd"
}

{
"error": "Request 'data' should not exceeds the size of 4000 in a single request”,
"trace-id": "b325a7fa-b573-4efe-9bfb-5ae7de40e72c"
}

{
"error": "Request data has too many invalid 'data' elements",
"valid": 2,
"invalid": 30,
"trace-id": "33551c1d-5682-405e-a959-c8729ca74735"
}

Limitaciones de tasa

5 solicitudes por segundo
350 solicitudes por minuto