Activation des audiences à la demande vers des destinations par lots via l’API d’activation ad hoc

Vue d’ensemble overview

L’API d’activation ad hoc permet aux marketeurs d’activer par programmation les audiences d’audience vers les destinations, de manière rapide et efficace, dans les cas où une activation immédiate est requise.

Utilisez l’API d’activation ad hoc pour exporter des fichiers complets vers le système de réception de fichiers souhaité. L’activation des audiences ad hoc est uniquement prise en charge par les destinations basées sur des fichiers de lot.

Le diagramme ci-dessous illustre le workflow de bout en bout pour activer les audiences via l’API d’activation ad hoc, y compris les tâches de segmentation qui ont lieu dans Platform toutes les 24 heures.

Cas d’utilisation use-cases

Ventes ou promotions de Flash

Un détaillant en ligne prépare une vente flash limitée et souhaite informer ses clients dans un court délai. Grâce à l’API d’activation ad hoc Experience Platform, l’équipe marketing peut exporter des audiences à la demande et envoyer rapidement des emails promotionnels à la base de clients.

Événements en cours ou informations de dernière minute

Un hôtel s'attend à des conditions météorologiques favorables les jours suivants et l'équipe veut informer rapidement les arrivants afin qu'ils puissent planifier en conséquence. L’équipe marketing peut utiliser l’API d’activation ad hoc Experience Platform pour exporter des audiences à la demande et en informer les invités.

Test d’intégration

Les responsables informatiques peuvent utiliser l’API d’activation ad hoc Experience Platform pour exporter des audiences à la demande, afin qu’ils puissent tester leur intégration personnalisée avec Adobe Experience Platform et s’assurer que tout fonctionne correctement.

Mécanismes de sécurisation guardrails

Gardez à l’esprit les barrières de sécurité suivantes lors de l’utilisation de l’API d’activation ad hoc.

Considérations relatives à la segmentation segmentation-considerations

Adobe Experience Platform exécute des tâches de segmentation planifiées toutes les 24 heures. L’API d’activation ad hoc s’exécute en fonction des derniers résultats de segmentation.

Etape 1 : Conditions préalables prerequisites

Avant de pouvoir appeler les API Adobe Experience Platform, assurez-vous de respecter les conditions préalables suivantes :

Étape 2 : collecte des informations d’identification credentials

Pour lancer des appels aux API Platform, vous devez d’abord suivre le tutoriel sur l’authentification. Le tutoriel sur l’authentification indique les valeurs de chacun des en-têtes requis dans tous les appels API Experience Platform, comme illustré ci-dessous :

Les ressources d’Experience Platform peuvent être isolées dans des sandbox virtuels spécifiques. Dans les requêtes aux API Platform, vous pouvez spécifier le nom et l’identifiant du sandbox dans lequel l’opération aura lieu. Il s’agit de paramètres facultatifs.

Toutes les requêtes qui contiennent un payload (POST, PUT, PATCH) nécessitent un en-tête de type de média supplémentaire :

Étape 3 : création d’un flux d’activation dans l’interface utilisateur de Platform activation-flow

Avant de pouvoir activer des audiences via l’API d’activation ad hoc, vous devez d’abord configurer un flux d’activation dans l’interface utilisateur de Platform, pour la destination choisie.

Cela inclut l’accès au workflow d’activation, la sélection de vos audiences, la configuration d’un planning et leur activation. Vous pouvez utiliser l’interface utilisateur ou l’API pour créer un flux d’activation :

Étape 4 : Obtention du dernier ID de tâche d’exportation d’audience (non requis dans la version v2) segment-export-id

Une fois que vous avez configuré un flux d’activation pour votre destination de lot, les tâches de segmentation planifiées commencent à s’exécuter automatiquement toutes les 24 heures.

Avant de pouvoir exécuter la tâche d’activation ad hoc, vous devez obtenir l’identifiant de la dernière tâche d’exportation d’audience. Vous devez transmettre cet identifiant dans la requête de tâche d’activation ad hoc.

Suivez les instructions décrites ici pour récupérer une liste de toutes les tâches d’exportation d’audience.

Dans la réponse, recherchez le premier enregistrement contenant la propriété de schéma ci-dessous.

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

L’ID de la tâche d’exportation d’audience se trouve dans la propriété id, comme illustré ci-dessous.

Étape 5 : exécution de la tâche d’activation ad hoc activation-job

Adobe Experience Platform exécute des tâches de segmentation planifiées toutes les 24 heures. L’API d’activation ad hoc s’exécute en fonction des derniers résultats de segmentation.

Avant d’exécuter une tâche d’activation ad hoc, assurez-vous que la tâche d’exportation d’audience planifiée pour vos audiences est terminée. Pour plus d’informations sur la surveillance de l’état des flux d’activation, voir surveillance des flux de données de destination . Par exemple, si votre flux de données d’activation affiche l’état Traitement, attendez qu’il se termine avant d’exécuter la tâche d’activation ad hoc pour exporter un fichier complet.

Une fois la tâche d'export d'audience terminée, vous pouvez déclencher l'activation.

Requête request

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"
      ]
   }
}'

Propriété

Description

• destinationId1
• destinationId2

Les identifiants des instances de destination vers lesquelles vous souhaitez activer les audiences. Vous pouvez obtenir ces ID à partir de l’interface utilisateur de Platform, en accédant à l’onglet Destinations > Parcourir et en cliquant sur la ligne de destination de votre choix pour afficher l’ID de destination dans le rail de droite. Pour plus d’informations, consultez la documentation de l’espace de travail des destinations.

• segmentId1
• segmentId2
• segmentId3

Les identifiants des audiences que vous souhaitez activer vers la destination sélectionnée. Vous pouvez utiliser l’API ad hoc pour exporter des audiences générées par Platform ainsi que des audiences externes (téléchargement personnalisé). Lors de l’activation d’audiences externes, utilisez l’identifiant généré par le système au lieu de l’identifiant d’audience. Vous pouvez trouver l'identifiant généré par le système dans la vue de synthèse de l'audience dans l'interface utilisateur des audiences.
{width="100" modal="regular"}
{width="100" modal="regular"}

Requête avec des ID d’exportation request-export-ids

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"
   ]
}

Réponse response

Une réponse réussie renvoie un état 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"
      }
   ]
}

Gestion des erreurs d’API api-error-handling

Les points d’entrée de l’API Destination SDK suivent les principes généraux des messages d’erreur de l’API Experience Platform. Consultez les sections Codes dʼétat d’API et Erreurs dʼen-tête de requête dans le guide de dépannage de Platform.

Codes d’erreur et messages d’API spécifiques à l’API d’activation ad hoc specific-error-messages

Lors de l’utilisation de l’API d’activation ad hoc, vous pouvez rencontrer des messages d’erreur spécifiques à ce point de terminaison API. Consultez le tableau pour savoir comment y remédier lorsqu’il s’affiche.

Informations connexes related-information