Activar segmentos de audiencia bajo demanda en destinos por lotes mediante la API de activación ad hoc

Información general

La API de activación ad hoc permite a los especialistas en marketing activar mediante programación segmentos de audiencia en destinos de forma rápida y eficaz en situaciones en las que se requiera la activación inmediata.

Utilice la API de activación ad-hoc para exportar archivos completos al sistema de recepción de archivos deseado. La activación de audiencias ad hoc solo es compatible con destinos basados en archivos por lotes.

El diagrama siguiente ilustra el flujo de trabajo completo para activar segmentos a través de la API de activación ad-hoc, incluidos los trabajos de segmentación que se realizan en Platform cada 24 horas.

Casos de uso

Flashes de ventas o promociones

Un minorista en línea está preparando una venta flash limitada y quiere avisar a los clientes con poco tiempo de antelación. A través de la API de activación ad hoc de Experience Platform, el equipo de marketing puede exportar segmentos bajo demanda y enviar rápidamente correos electrónicos promocionales a la base de clientes.

Eventos actuales o noticias de última hora

Un hotel espera un tiempo inclemente en los próximos días, y el equipo quiere informar a los huéspedes que llegan rápidamente, para que puedan planificar en consecuencia. El equipo de marketing puede utilizar la API de activación ad-hoc de Experience Platform para exportar segmentos bajo demanda y notificar a los invitados.

Pruebas de integración

Los administradores de TI pueden utilizar la API de activación ad hoc de Experience Platform para exportar segmentos bajo demanda, de modo que puedan probar su integración personalizada con Adobe Experience Platform y asegurarse de que todo funciona correctamente.

Mecanismos de protección

Tenga en cuenta las siguientes protecciones al utilizar la API de activación ad-hoc.

• Actualmente, cada trabajo de activación ad-hoc puede activar hasta 80 segmentos. Si se intenta activar más de 80 segmentos por trabajo, el trabajo fallará. Este comportamiento está sujeto a cambios en futuras versiones.
• Los trabajos de activación ad hoc no se pueden ejecutar en paralelo con los programados trabajos de exportación de segmentos. Antes de ejecutar un trabajo de activación ad-hoc, asegúrese de que el trabajo de exportación de segmentos programado haya finalizado. Consulte monitorización del flujo de datos de destino para obtener información sobre cómo monitorizar el estado de los flujos de activación. Por ejemplo, si el flujo de datos de activación muestra un Procesando estado, espere a que finalice antes de ejecutar el trabajo de activación ad-hoc.
• No ejecute más de un trabajo de activación ad hoc simultáneo por segmento.

Consideraciones de segmentación

Adobe Experience Platform ejecuta trabajos de segmentación programados una vez cada 24 horas. La API de activación ad hoc se ejecuta en función de los resultados de segmentación más recientes.

Paso 1: Requisitos previos

Para poder realizar llamadas a las API de Adobe Experience Platform, asegúrese de cumplir los siguientes requisitos previos:

• Tiene una cuenta de organización de IMS con acceso a Adobe Experience Platform.
• Su cuenta de Experience Platform tiene el developer y user funciones habilitadas para el perfil de producto de la API de Adobe Experience Platform. Póngase en contacto con su Admin Console para habilitar estas funciones en su cuenta.
• Tiene un Adobe ID. Si no dispone de un Adobe ID, vaya al Consola de Adobe Developer y cree una nueva cuenta.

Paso 2: Recopilar credenciales

Para realizar llamadas a las API de Platform, primero debe completar el tutorial de autenticación. Al completar el tutorial de autenticación, se proporcionan los valores de cada uno de los encabezados necesarios en todas las llamadas a la API de Experience Platform, como se muestra a continuación:

• Autorización: Portador {ACCESS_TOKEN}
• x-api-key: {API_KEY}
• x-gw-ims-org-id: {ORG_ID}

Los recursos de Experience Platform se pueden aislar en zonas protegidas virtuales específicas. En las solicitudes a las API de Platform, puede especificar el nombre y el ID de la zona protegida en la que se realizará la operación. Son parámetros opcionales.

• x-sandbox-name: {SANDBOX_NAME}

Todas las solicitudes que contienen una carga útil (POST, PUT, PATCH) requieren un encabezado de tipo de medios adicional:

• Content-Type: application/json

Paso 3: Crear un flujo de activación en la interfaz de usuario de Platform

Para poder activar segmentos a través de la API de activación ad-hoc, primero debe tener configurado un flujo de activación en la interfaz de usuario de Platform para el destino elegido.

Esto incluye entrar en el flujo de trabajo de activación, seleccionar los segmentos, configurar una programación y activarlos. Puede utilizar la interfaz de usuario o la API de para crear un flujo de activación:

• Utilice la interfaz de usuario de Platform para crear un flujo de activación para los destinos de exportación de perfiles por lotes
• Utilice la API de Flow Service para conectarse a destinos de exportación de perfiles por lotes y activar datos

Paso 4: Obtener el ID de trabajo de exportación de segmentos más reciente (no obligatorio en la versión 2)

Después de configurar un flujo de activación para el destino del lote, los trabajos de segmentación programados comienzan a ejecutarse automáticamente cada 24 horas.

Para poder ejecutar el trabajo de activación ad-hoc, debe obtener el ID del último trabajo de exportación de segmentos. Debe pasar este ID en la solicitud de trabajo de activación ad-hoc.

Siga las instrucciones descritas aquí para recuperar una lista de todos los trabajos de exportación de segmentos.

En la respuesta, busque el primer registro que incluya la propiedad de esquema a continuación.

"schema":{
   "name":"_xdm.context.profile"
}

El ID del trabajo de exportación de segmentos se encuentra en id , como se muestra a continuación.

Paso 5: Ejecutar el trabajo de activación ad-hoc

Adobe Experience Platform ejecuta trabajos de segmentación programados una vez cada 24 horas. La API de activación ad hoc se ejecuta en función de los resultados de segmentación más recientes.

Antes de ejecutar un trabajo de activación ad-hoc, asegúrese de que el trabajo de exportación de segmentos programado para sus segmentos haya finalizado. Consulte monitorización del flujo de datos de destino para obtener información sobre cómo monitorizar el estado de los flujos de activación. Por ejemplo, si el flujo de datos de activación muestra un Procesando estado, espere a que finalice antes de ejecutar el trabajo de activación ad-hoc para exportar un archivo completo.

Una vez completado el trabajo de exportación de segmentos, puede almacenar la activación en déclencheur.

Solicitud

curl --location --request POST 'https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun' \
--header 'x-gw-ims-org-id: 5555467B5D8013E50A494220@AdobeOrg' \
--header 'Authorization: Bearer {{token}}' \
--header 'x-sandbox-id: 6ef74723-3ee7-46a4-b747-233ee7a6a41a' \
--header 'x-sandbox-name: {sandbox-id}' \
--header 'Accept: application/vnd.adobe.adhoc.activation+json; version=2' \
--header 'Content-Type: application/json' \
--data-raw '{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ],
      "destinationId2":[
         "segmentId2",
         "segmentId3"
      ]
   }
}'

Solicitud con ID de exportación (para dejar de utilizar)

curl -X POST https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -d '
{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ],
      "destinationId2":[
         "segmentId2",
         "segmentId3"
      ]
   },
   "exportIds":[
      "exportId1"
   ]
}

Respuesta

Una respuesta correcta devuelve el estado HTTP 200.

{
   "order":[
      {
         "segment":"db8961e9-d52f-45bc-b3fb-76d0382a6851",
         "order":"ef2dcbd6-36fc-49a3-afed-d7b8e8f724eb",
         "statusURL":"https://platform.adobe.io/data/foundation/flowservice/runs/88d6da63-dc97-460e-b781-fc795a7386d9"
      }
   ]
}

Administración de errores de API

Los extremos de la API de Destination SDK siguen los principios generales del mensaje de error de la API de Experience Platform. Consulte Códigos de estado de API y errores de encabezado de solicitud en la guía de solución de problemas de Platform.

Códigos de error de API y mensajes específicos de la API de activación ad hoc

Al utilizar la API de activación ad hoc, puede encontrar mensajes de error específicos de este extremo de API. Revise la tabla para comprender cómo abordarlos cuando aparecen.

Información relacionada

• Conéctese a destinos por lotes y active los datos mediante la API de Flow Service
• (Beta) Exportar archivos bajo demanda a destinos por lotes mediante la interfaz de usuario de Experience Platform

Recursos de Business.Adobe.com