Activer les 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 spécialistes marketing d’activer par programmation les audiences 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 de votre choix. L’activation des audiences ad hoc n’est prise en charge que par les destinations basées sur des fichiers par lots.

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

Cas d’utilisation use-cases

Ventes ou promotions Flash

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

Événements actuels ou dernières nouvelles

Un hôtel s'attend à un mauvais temps les jours suivants, et l'équipe souhaite informer rapidement les clients afin qu'ils puissent se préparer en conséquence. L’équipe marketing peut utiliser l’API d’activation ad hoc d’Experience Platform pour exporter des audiences à la demande et informer les invités.

Test de l’intégration

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

Mécanismes de sécurisation guardrails

Gardez à l’esprit les mécanismes de sécurisation suivants 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 une fois toutes les 24 heures. L’API d’activation ad hoc s’exécute en fonction des derniers résultats de segmentation.

Etape 1 : prérequis prerequisites

Avant d’effectuer des appels vers les API Adobe Experience Platform, veillez à respecter les conditions préalables suivantes :

Étape 2 : collecter les informations d’identification credentials

Pour lancer des appels aux API Experience 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 Experience 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éer un flux d’activation dans l’interface utilisateur d’Experience Platform activation-flow

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

Cela inclut l’entrée dans le 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 : obtenir le dernier identifiant de tâche d'exportation d'audience (non requis dans v2) segment-export-id

Une fois que vous avez configuré un flux d’activation pour la destination par lots, 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 demande de traitement 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 qui inclut la propriété de schéma ci-dessous.

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

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

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

Adobe Experience Platform exécute des tâches de segmentation planifiées une fois 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. Consultez surveillance des flux de données de destination pour plus d’informations sur la surveillance du statut des flux d’activation. Par exemple, si votre flux de données d’activation affiche un statut Traitement, attendez qu’il soit terminé avant d’exécuter la tâche d’activation ad hoc pour exporter un fichier complet.

Une fois la tâche d’exportation 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

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

• segmentId1
• segmentId2
• segmentId3

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 Experience Platform, ainsi que des audiences externes (chargement personnalisé). Lors de l’activation d’audiences externes, utilisez l’identifiant généré par le système plutôt que l’identifiant d’audience. L’identifiant généré par le système est disponible dans la vue de résumé de l’audience dans l’interface utilisateur des audiences.
{width="100" modal="regular"}
{width="100" modal="regular"}

Requête avec ID d’export 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 statut 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 API et Erreurs d’en-tête de requête dans le guide de dépannage d’Experience Platform.

Codes d’erreur d’API et messages 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 d’entrée de l’API. Consultez le tableau pour comprendre comment y remédier lorsqu’ils apparaissent.

Informations connexes related-information