Diffuser des offres à l’aide de l’API Decisioning decisioning-api

Avec la gestion des décisions, vous pouvez créer et proposer des expériences d'offre personnalisées aux utilisateurs finaux par le biais de canaux et des applications en s'appuyant sur une logique métier et des règles de décision.
Une offre est un message marketing auquel des règles peuvent être associées et qui spécifie qui est éligible pour voir l'offre.

Vous pouvez créer et diffuser des offres en effectuant une requête POST à l'API Decisioning.

Ce tutoriel nécessite une bonne compréhension des API, tout particulièrement en ce qui concerne la gestion des décisions.
Pour plus d'informations, consultez le Guide de l'API de gestion des décisions destiné aux développeurs.
Ce tutoriel nécessite aussi que vous disposiez d'un identifiant d'emplacement et d'un identifiant de décision uniques. Si vous ne disposez pas de ces valeurs, consultez les tutoriels sur la création d'un emplacement et la création d'une décision.

➡️ Découvrez cette fonctionnalité en vidéo

En-têtes requis required-headers

Le tableau suivant montre les valeurs valides qui comprennent les champs Content-Type et Accept dans l'en-tête de la requête :

Nom de l'en-tête
Valeur
Accept
application/vnd.adobe.xdm+json; schema="https://ns.adobe.com/experience/offer-management/decision-response;version=1.0"
Content-Type
application/vnd.adobe.xdm+json; schema="https://ns.adobe.com/experience/offer-management/decision-request;version=1.0"
Autorisation
Bearer {ACCESS_TOKEN}
x-gw-ims-org-id
{IMS_ORG}
x-sandbox-name
{SANDBOX_NAME}
x-api-key
{API_KEY}
  • Toutes les requêtes contenant une payload (POST, PUT, PATCH) nécessitent l’en-tête de type de contenu.

Requête API request

Format d’API

POST /{ENDPOINT_PATH}/decisions
Paramètre
Description
Exemple
{ENDPOINT_PATH}
Chemin d’accès de point d’entrée pour les API de référentiel.
https://platform.adobe.io/data/core/ods

Requête

curl -X POST \
  'https://platform.adobe.io/data/core/ods/decisions' \
  -H 'Accept: application/vnd.adobe.xdm+json; schema="https://ns.adobe.com/experience/offer-management/decision-response;version=1.0"' \
  -H 'Content-Type: application/vnd.adobe.xdm+json; schema="https://ns.adobe.com/experience/offer-management/decision-request;version=1.0"'
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'
  -d '{
        "xdm:propositionRequests": [
            {
              "xdm:placementId": "xcore:offer-placement:ffed0456",
              "xdm:activityId": "xcore:offer-activity:ffed0123",
              "xdm:itemCount": 2
            },
            {
              "xdm:placementId": "xcore:offer-placement:ffed0012",
              "xdm:activityId": "xcore:offer-activity:fffc0789"
            }
        ],
        "xdm:profiles": [
            {
              "xdm:identityMap": {
                "SWCUSTID": [
                {
                    "xdm:id": "123@abc.com"
                }
                ]
            },
            "xdm:decisionRequestId": "0AA00002-0000-1224-c0de-cjf98Csj43"
            }
        ],
        "xdm:allowDuplicatePropositions": {
            "xdm:acrossActivities": true,
            "xdm:acrossPlacements": true
        },
        "xdm:mergePolicy": {
            "xdm:id": "5f3ed32f-eaf1-456c-b0f0-7b338c4cb18a"
        },
        "xdm:responseFormat": {
            "xdm:includeContent": true,
            "xdm:includeMetadata": {
            "xdm:activity": [
                "name"
            ],
            "xdm:option": [
                "name"
            ],
            "xdm:placement": [
                "name"
            ]
            }
        }
      }'
Propriété
Description
Exemple
xdm:propositionRequests
Cet objet contient les identifiants d'emplacement et de décision.
xdm:propositionRequests.xdm:placementId
Identifiant d'emplacement unique.
"xdm:placementId": "xcore:offer-placement:ffed0456"
xdm:propositionRequests.xdm:activityId
Identifiant de décision unique.
"xdm:activityId": "xcore:offer-activity:ffed0123"
xdm:itemCount
Nombre d'offres à renvoyer. Le nombre maximal est 30.
"xdm:itemCount": 2
xdm:profiles
Cet objet contient des informations sur le profil pour lequel la décision est demandée. Pour une requête d'API, il contient un profil.
xdm:profiles.xdm:identityMap
Cet objet contient un ensemble d'identités d'utilisateur final basées sur le code d'intégration d'espace de noms de l'identité. Le mappage d'identité peut comporter plusieurs identités de chaque espace de noms. Pour plus d’informations sur les espaces de noms, consultez cette page.
Email: [{"xdm:id": "123@abc.com"}]
xdm:profiles.xdm:decisionRequestId
Identifiant généré par le client pouvant être utilisé pour identifier de manière unique une demande de décision de profil. Cette identifiant est repris dans la réponse et n'influence pas le résultat de la décision.
"xdm:decisionRequestId": "0AA00002-0000-1224-c0de-cjf98Csj43"
xdm:allowDuplicatePropositions
Cet objet représente la structure de contrôle des règles de déduplication. Il s'agit d'une série d'indicateurs qui définissent si la même option peut être proposée dans une certaine dimension. Un indicateur défini sur true signifie que les duplicatas sont autorisés et ne doivent pas être supprimés pour la catégorie indiquée par l'indicateur. Un indicateur défini sur false signifie que le moteur de décision ne doit pas faire la même proposition pour la dimension et doit plutôt choisir la meilleure option suivante pour l'une des sous-décisions.
xdm:allowDuplicatePropositions.xdm:acrossActivities
Si la valeur est définie sur true, plusieurs décisions peuvent se voir attribuer la même option.
"xdm:acrossActivities": true
xdm:allowDuplicatePropositions.xdm:acrossPlacements
Si la valeur est définie sur true, plusieurs emplacements peuvent se voir attribuer la même option.
"xdm:acrossPlacements": true
xdm:mergePolicy.xdm:id
Identifie la politique de fusion selon laquelle gérer les données renvoyées par le service d'accès aux profils. S’i aucune n’est spécifiée dans la requête, la gestion des décisions ne transmet aucun service d’accès au profil. Dans le cas contraire, il transmet l’identifiant fourni par la personne appelante.
"xdm:id": "5f3ed32f-eaf1-456c-b0f0-7b338c4cb18a"
xdm:responseFormat
Ensemble d'indicateurs qui formate le contenu de la réponse.
xdm:responseFormat.xdm:includeContent
Valeur booléenne qui, si elle est définie sur true, inclut le contenu de la réponse.
"xdm:includeContent": true
xdm:responseFormat.xdm:includeMetadata
Objet utilisé pour spécifier les métadonnées supplémentaires renvoyées. Si cette propriété n'est pas incluse, xdm:id et repo:etag sont renvoyés par défaut.
name
xdm:responseFormat.xdm:activity
Cet indicateur identifie les informations de métadonnées spécifiques renvoyées pour xdm:activity.
name
xdm:responseFormat.xdm:option
Cet indicateur identifie les informations de métadonnées spécifiques renvoyées pour xdm:option.
name, characteristics
xdm:responseFormat.xdm:placement
Cet indicateur identifie les informations de métadonnées spécifiques renvoyées pour xdm:placement.
name, channel, componentType

Réponse

Une réponse réussie renvoie des informations sur votre proposition, y compris son unique xdm:propositionId.

{
  "xdm:propositionId": "5d0ffb5e-dfc6-4280-99b6-0bf3131cb8b8",
  "xdm:propositions": [
    {
      "xdm:activity": {
        "xdm:id": "xcore:activity:ffed0123",
        "repo:etag": 4
      },
      "xdm:placement": {
        "xdm:id": "xcore:placement:ffed0456",
        "repo:etag": 1
      },
      "xdm:options": [
        {
          "xdm:id": "xcore:personalized-option:ccc0111",
          "repo:etag": 3,
          "@type": "https://ns.adobe.com/experience/decisioning/content-component-html-template",
          "xdm:content": "<html>some html</html>"
        },
        {
          "xdm:id": "xcore:personalized-option:ccc0222",
          "repo:etag": 5,
          "@type": "https://ns.adobe.com/experience/decisioning/content-component-html-template",
          "xdm:content": "<html>hello, world</html>",
          "xdm:score": 45.65
        }
      ]
    },
    {
      "xdm:activity": {
        "xdm:id": "xcore:activity:ffed0123",
        "repo:etag": 4
      },
      "xdm:placement": {
        "xdm:id": "xcore:placement:ffed0789",
        "repo:etag": 2
      },
      "xdm:fallback": {
        "xdm:id": "xcore:fallback:ccc0222",
        "repo:etag": 5,
        "@type": "https://ns.adobe.com/experience/decisioning/content-component-imagelink",
        "dc:format": "image/png",
        "xdm:deliveryURL": "https://cdn.adobe.com/content/1445323-1134331.png",
        "xdm:content": "https://www.adobe.com/index2.html"
      }
    }
  ],
  "ode:createDate": 1566497582038
}
Propriété
Description
Exemple
xdm:propositionId
Identifiant unique de l'entité de proposition associée à un événement XDM DecisionEvent.
"xdm:propositionId": "5d0ffb5e-dfc6-4280-99b6-0bf3131cb8b8"
xdm:propositions
Cet objet contient une proposition de décision unique. Plusieurs options peuvent être renvoyées pour la décision. Si aucune option n'est trouvée, l'offre de secours de la décision est renvoyée. Les propositions de décision uniques comprennent toujours une propriété options ou fallback. Lorsqu'elle est présente, la propriété options ne peut pas être vide.
xdm:propositions.xdm:activity
Cet objet contient l'identifiant unique d'une décision.
"xdm:id": "xcore:activity:ffed0123"
xdm:propositions.xdm:placement
Cet objet contient l'identifiant unique d'un emplacement d'offre.
"xdm:id": "xcore:placement:ffed0456"
xdm:propositions.xdm:options
Cet objet contient une seule option, y compris son identifiant unique. En cas de présence, cet objet ne peut pas être vide.
xdm:id": "xcore:personalized-option:ccc0111
xdm:propositions.xdm:options.@type
Définit le type du composant. @type agit en tant que contrat de traitement pour le client. Une fois l'expérience assemblée, le compositeur recherche le ou les composants ayant un type spécifique.
https://ns.adobe.com/experience/offer-management/content-component-imagelink
xdm:propositions.xdm:content
Format du contenu de la réponse.
Le contenu de la réponse peut être : text, html block ou image link
xdm:score
Score d'une option calculée à la suite d'une fonction de classement associée à l'option ou à la décision. Ce champ est renvoyé par l'API si une fonction de classement est impliquée dans la détermination du score d'une offre au cours du classement.
"xdm:score": 45.65
xdm:propositions.xdm:fallback
Cet objet contient une seule offre de secours, y compris son identifiant unique.
"xdm:id": "xcore:fallback:ccc0222"
xdm:propositions.xdm:fallback.dc:format
Manifestation physique ou numérique de la ressource. En règle générale, le format doit inclure le type de média de la ressource. Le format peut être utilisé pour déterminer le logiciel, le matériel ou tout autre équipement nécessaire pour afficher ou exploiter la ressource. Il est recommandé de sélectionner une valeur dans un vocabulaire contrôlé, par exemple, la liste des types de médias Internet définissant les formats de médias informatiques.
"dc:format": "image/png" ou "image/jpeg"
xdm:propositions.xdm:fallback.xdm:deliveryURL
URL facultative permettant de lire le fichier à partir d’un réseau de diffusion de contenu ou d’un point d’entrée de service. Cette URL permet d'accéder publiquement à la ressource à partir d'un agent utilisateur.
https://d37yhxrr0p3l3l.cloudfront.net/0fd0f090-a148-11ea-89e3-f1f2ad52f7e8/urn:aaid:sc:US:a68c86a6-9295-4940-a083-11916b665500/0/40d78a12-f8b6-3f07-8e67-7cb8ae2cc7ec
ode:createDate
Heure à laquelle le message de réponse à la décision a été créé. Il s'agit de l'époque.
"ode:createDate": 1566497582038

Codes de réponse

Le tableau ci-dessous répertorie tous les codes qui peuvent être renvoyés dans la réponse :

Code
Description
200
Réussite. Une décision a été prise pour des activités données.
400
Paramètre de requête non valide. La requête ne peut pas être comprise par le serveur en raison d’une syntaxe incorrecte.
403
Accès interdit, autorisations insuffisantes.
422
Entité impossible à traiter. La syntaxe de la requête est correcte mais elle ne peut pas être traitée en raison d’erreurs sémantiques.
429
Trop de requêtes. L’utilisateur ou l‘utilisatrice a envoyé trop de demandes au cours d’une période donnée.
500
Erreur interne du serveur. Le serveur a rencontré une condition inattendue qui l’a empêché de satisfaire la requête.
503
Service indisponible en raison d’une surcharge du serveur. Le serveur ne peut actuellement pas traiter la demande en raison d’une surcharge temporaire.

Étapes suivantes next-steps

En suivant ce guide d'API, vous avez créé et diffusé des offres à l'aide de l'API Decisions. Pour plus d'informations, consultez la présentation de la gestion des décisions.

recommendation-more-help
b22c9c5d-9208-48f4-b874-1cefb8df4d76