(Beta) Activation des segments d’audience vers des destinations par lots via l’API d’activation ad hoc

IMPORTANT

Le ad-hoc activation API dans Platform est actuellement en version bêta. La documentation et les fonctionnalités peuvent changer.

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.

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.

activation ad hoc

REMARQUE

L’activation des audiences ad hoc n’est prise en charge que par destinations basées sur des fichiers de lots.

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 tâche d’activation ad hoc peut activer jusqu’à 20 segments. Si vous tentez d’activer plus de 20 segments par tâche, la tâche échouera. Ce comportement peut être modifié 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 Adobe Developer Console 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: {IMS_ORG}

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}
REMARQUE

Pour plus d’informations sur les environnements de test dans Experience Platform, consultez la documentation de présentation des environnements de test.

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.

Consultez le tutoriel suivant pour obtenir des instructions détaillées sur la configuration d’un flux d’activation pour vos destinations par lots : Activation des données d’audience vers des destinations d’exportation de profils par lots.

Étape 4 : Obtention du dernier ID de tâche d’exportation de segments

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.

identifiant de tâche d’exportation de segments

É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.

Une fois la tâche d’exportation de segments terminée, vous pouvez déclencher l’activation.

REMARQUE

Actuellement, chaque tâche d’activation ad hoc peut activer jusqu’à 20 segments. Si vous tentez d’activer plus de 20 segments par tâche, la tâche échouera. Ce comportement peut être modifié dans les prochaines versions.

Requête

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: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -d '
{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ],
      "destinationId2":[
         "segmentId2",
         "segmentId3"
      ]
   },
   "exportIds":[
      "exportId1"
   ]
}
Propriété Description
  • destinationId1
  • destinationId2
Les identifiants des instances de destination vers lesquelles vous souhaitez activer les segments.
  • segmentId1
  • segmentId2
  • segmentId3
Les identifiants des segments que vous souhaitez activer vers la destination sélectionnée.
  • exportId1
L’ID renvoyé dans la réponse de la variable exportation de segments tâche. Voir Étape 4 : Obtention du dernier ID de tâche d’exportation de segments pour obtenir des instructions sur la manière de trouver cet identifiant.

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"
      }
   ]
}
Propriété Description
segment Identifiant du segment activé.
order Identifiant de la destination vers laquelle le segment a été activé.
statusURL URL d’état du flux d’activation. Vous pouvez suivre la progression du flux à l’aide de la variable API de service de flux.

Gestion des erreurs d’API

Les points de terminaison de l’API Destination SDK suivent les principes généraux des messages d’erreur de l’API Experience Platform. Voir Codes d’état d’API et erreurs d’en-tête de requête dans le guide de dépannage de Platform.

Sur cette page