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

Présentation

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

Le diagramme ci-dessous illustre le workflow de bout en bout pour l’activation des segments 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

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 segments à 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 segments à 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 segments à la demande, afin qu’ils puissent tester leur intégration personnalisée avec Adobe Experience Platform et s’assurer que tout fonctionne correctement.

Barrières de sécurité

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

• Actuellement, chaque traitement d’activation ad hoc peut activer jusqu’à 80 segments. Si vous tentez d’activer plus de 80 segments par traitement, celui-ci échouera. Ce comportement peut faire l’objet de modifications dans les prochaines versions.
• Les tâches d’activation ad hoc ne peuvent pas s’exécuter en parallèle avec les tâches planifiées traitements d’exportation de segments. Avant d’exécuter une tâche d’activation ad hoc, assurez-vous que la tâche d’exportation de segments planifiée est terminée. Voir surveillance des flux de données de destination pour plus d’informations sur la manière de surveiller l’état des flux d’activation. Par exemple, si votre flux de données d’activation affiche une Traitement , attendez qu’il se termine avant d’exécuter la tâche d’activation ad hoc.
• N’exécutez pas plusieurs tâches d’activation ad hoc simultanées par segment.

Considérations relatives à la segmentation

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.

Étape 1 : Conditions préalables

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

• Vous disposez d’un compte de l’organisation IMS ayant accès à Adobe Experience Platform.
• Votre compte d’Experience Platform a la variable developer et user rôles activés pour le profil de produit de l’API Adobe Experience Platform. Contactez votre Admin Console pour activer ces rôles pour votre compte.
• Vous avez une Adobe ID. Si vous ne possédez pas d’Adobe ID, accédez à la Console Adobe Developer et créez un compte.

Étape 2 : Collecte des informations d’identification

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 :

• Authorization: Bearer {ACCESS_TOKEN}
• x-api-key : {API_KEY}
• x-gw-ims-org-id: {ORG_ID}

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

• x-sandbox-name: {SANDBOX_NAME}

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

• Content-Type: application/json

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

Avant de pouvoir activer des segments 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 segments, la configuration d’un planning et leur activation. Vous pouvez utiliser l’interface utilisateur ou l’API pour créer un flux d’activation :

• Utilisation de l’interface utilisateur de Platform pour créer un flux d’activation pour les destinations d’exportation de profils par lots
• Utilisation de l’API Flow Service pour se connecter aux destinations d’exportation de profils par lots et activer les données

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

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 d’exécuter la tâche d’activation ad hoc, vous devez obtenir l’identifiant de la dernière tâche d’exportation de segments. Vous devez transmettre cet identifiant dans la requête de tâche d’activation ad hoc.

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

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 de segments se trouve dans la variable id , comme illustré ci-dessous.

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

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 de segments planifiée pour vos segments est terminée. Voir surveillance des flux de données de destination pour plus d’informations sur la manière de surveiller l’état des flux d’activation. Par exemple, si votre flux de données d’activation affiche une 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’exportation de segments terminée, vous pouvez déclencher l’activation.

Requête

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

Requête avec des identifiants d’exportation (à abandonner)

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

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

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

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

• Se connecter aux destinations par lots et activer des données à l’aide de l’API Flow Service
• (Version bêta) Exporter des fichiers à la demande vers des destinations par lots à l’aide de l’interface utilisateur Experience Platform

Ressources Business.Adobe.com