Personnalisation hybride à l’aide des API Web SDK et Edge Network

Vue d’ensemble overview

La personnalisation hybride décrit le processus de récupération du contenu de personnalisation côté serveur, à l’aide de l’API Edge Network, et de le rendre côté client, à l’aide du SDK Web.

Vous pouvez utiliser la personnalisation hybride avec des solutions de personnalisation telles qu’Adobe Target, Adobe Journey Optimizer ou Offer Decisioning, la différence étant le contenu de la payload de l’API Edge Network.

Conditions préalables prerequisites

Avant d’implémenter une personnalisation hybride sur vos propriétés web, assurez-vous de respecter les conditions suivantes :

Diagramme de flux flow-diagram

Le diagramme de flux ci-dessous décrit l’ordre des étapes effectuées pour fournir une personnalisation hybride.

Cookies cookies

Les cookies sont utilisés pour conserver l’identité de l’utilisateur et les informations de cluster. Lors de l’utilisation d’une implémentation hybride, le serveur d’applications web gère le stockage et l’envoi de ces cookies pendant le cycle de vie des requêtes.

Demander l’emplacement request-placement

Les requêtes d’API Edge Network sont nécessaires pour obtenir des propositions et envoyer une notification d’affichage. Lors de l’utilisation d’une implémentation hybride, le serveur d’applications envoie ces requêtes à l’API Edge Network.

Définir l’hôte régional Edge Network regional-host

Pour établir l’hôte régional Edge Network, lisez d’abord l’indice d’emplacement du cookie kndctr_<orgId>_AdobeOrg_cluster, qui peut avoir les valeurs suivantes :

Exemple : kndctr_53A16ACB5CC1D3760A495C99_AdobeOrg_cluster: va6

L’hôte régional Edge Network utilise le format suivant :<location_hint>.server.adobedc.net et peut avoir les valeurs suivantes :

En utilisant ces hôtes spécifiques, les requêtes seront dirigées vers le même emplacement Edge Network que celui visité précédemment par l’utilisateur. Le système sera en mesure de fournir la meilleure expérience, car les données utilisateur y sont présentes.

Si aucune indication d’emplacement (c’est-à-dire aucun cookie) n’est présente, utilisez l’hôte par défaut : server.adobedc.net.

Implications Analytics analytics

Lors de l’implémentation d’une personnalisation hybride, vous devez faire particulièrement attention à ce que les accès aux pages ne soient pas comptabilisés plusieurs fois dans Analytics.

Lorsque vous configurez un flux de données dans Analytics, les événements sont automatiquement transférés afin que les accès à la page soient capturés.

L’exemple de cette mise en œuvre utilise deux flux de données différents :

Ainsi, la requête côté serveur n’enregistre aucun événement Analytics, contrairement aux requêtes côté client. Cela entraîne un comptage précis des requêtes Analytics.

Créer la requête côté serveur server-side-request

L’exemple de requête ci-dessous illustre une requête d’API Edge Network que votre serveur d’applications peut utiliser pour récupérer le contenu de personnalisation.

Format d’API

POST /ee/v2/interact

Requête request

curl -X POST "https://edge.adobedc.net/ee/v2/interact?dataStreamId={DATASTREAM_ID}"
-H "Content-Type: text/plain"
-d '{
   "event":{
      "xdm":{
         "web":{
            "webPageDetails":{
               "URL":"http://localhost/"
            },
            "webReferrer":{
               "URL":""
            }
         },
         "identityMap":{
            "FPID":[
               {
                  "id":"xyz",
                  "authenticatedState":"ambiguous",
                  "primary":true
               }
            ]
         },
         "timestamp":"2022-06-23T22:21:00.878Z"
      },
      "data":{

      }
   },
   "query":{
      "identity":{
         "fetch":[
            "ECID"
         ]
      },
      "personalization":{
         "schemas":[
            "https://ns.adobe.com/personalization/default-content-item",
            "https://ns.adobe.com/personalization/html-content-item",
            "https://ns.adobe.com/personalization/json-content-item",
            "https://ns.adobe.com/personalization/redirect-item",
            "https://ns.adobe.com/personalization/dom-action"
         ],
         "decisionScopes":[
            "__view__",
            "sample-json-offer"
         ]
      }
   },
   "meta":{
      "state":{
         "domain":"localhost",
         "cookiesEnabled":true,
         "entries": [{
           "key": "kndctr_53A16ACB5CC1D3760A495C99_AdobeOrg_identity",
           "value":"CiY0NzE0NzkwMTUyMzYzMzI4NDAxMjc3NDcwNzA2NTcxMjI3OTI1NVIRCJ_S-uCRMRABGAEqBElSTDHwAZ_S-uCRMQ=="
         }, {
           "key": "kndctr_53A16ACB5CC1D3760A495C99_AdobeOrg_consent",
           "value": "general=in"
         }, {
            "key": "kndctr_53A16ACB5CC1D3760A495C99_AdobeOrg_cluster",
            "value": "va6"
         }]
      }
   }
}'

En-têtes de proxy proxy-headers

Les en-têtes suivants sont requis pour traiter correctement la requête.

Veillez à les définir correctement pour pointer vers les informations réelles du client. Par exemple, l’en-tête X-Forwarded-For doit contenir l’adresse IP du client pour qu’une géolocalisation correcte soit effectuée.

En-têtes User-Agent user-agent-headers

Utilisez les en-têtes user-agent suivants pour traiter correctement la requête.

Par défaut

Faible entropie (obligatoire) :

entropie élevée (facultatif) :

La requête doit être envoyée comme indiqué dans la spécification API Edge Network. Consultez la documentation sur la personnalisation si votre cas d’utilisation le requiert.

Réponse côté serveur server-response

La réponse d’Edge Network contiendra des instructions state:store, qui doivent être transformées en en-têtes Set-Cookie. Ils sont enregistrés dans le navigateur et peuvent être utilisés par l’implémentation de Web SDK.

Les cookies doivent être définis sur le domaine de niveau supérieur, de sorte qu’ils soient envoyés avec les requêtes à l’implémentation du serveur et à celle du client. (Ou au moins un sous-domaine commun utilisé par les deux mises en œuvre)

Exemple :

Les cookies doivent être définis sur .example.com afin qu’ils soient partagés dans les deux cas.

La réponse côté serveur est organisée en fragments appelés Handles, qui sont générés en fonction de la configuration du train de données. Par exemple, les moteurs de personnalisation en temps réel renvoient des descripteurs personalization:decisions, tandis que le moteur d’activation en temps réel génère des descripteurs activation:pull.

L’exemple de réponse ci-dessous montre à quoi pourrait ressembler la réponse de l’API Edge Network.

{
   "requestId":"5c539bd0-33bf-43b6-a054-2924ac58038b",
   "handle":[
      {
         "payload":[
            {
               "id":"XXX",
               "namespace":{
                  "code":"ECID"
               }
            }
         ],
         "type":"identity:result"
      },
      {
         "payload":[
            {
               "..."
            },
            {
               "..."
            }
         ],
         "type":"personalization:decisions",
         "eventIndex":0
      }
   ]
}

Requête côté client client-request

Sur la page client, la commande Web SDK applyResponse est appelée, transmettant les en-têtes et le corps de la réponse côté serveur.

   alloy("applyResponse", {
      "renderDecisions": true,
      "responseHeaders": {
         "cache-control": "no-cache, no-store, max-age=0, no-transform, private",
         "connection": "close",
         "content-encoding": "deflate",
         "content-type": "application/json;charset=utf-8",
         "date": "Mon, 11 Jul 2022 19:42:01 GMT",
         "server": "jag",
         "strict-transport-security": "max-age=31536000; includeSubDomains",
         "transfer-encoding": "chunked",
         "vary": "Origin",
         "x-adobe-edge": "OR2;9",
         "x-content-type-options": "nosniff",
         "x-konductor": "22.6.78-BLACKOUTSERVERDOMAINS:7fa23f82",
         "x-rate-limit-remaining": "599",
         "x-request-id": "5c539bd0-33bf-43b6-a054-2924ac58038b",
         "x-xss-protection": "1; mode=block"
      },
      "responseBody": {
         "requestId": "5c539bd0-33bf-43b6-a054-2924ac58038b",
         "handle": [
         {
            "payload": [
               {
               "id": "XXX",
               "namespace": {
                  "code": "ECID"
               }
               }
            ],
            "type": "identity:result"
         },
         {
            "payload": [
               {...},
               {...}
            ],
            "type": "personalization:decisions",
            "eventIndex": 0
         }
         ]
      }
   }
   ).then(applyPersonalization("sample-json-offer"));

Les offres JSON basées sur des formulaires sont appliquées manuellement par l’intermédiaire de la méthode applyPersonalization pour mettre à jour le DOM en fonction de l’offre de personnalisation. Pour les activités basées sur des formulaires, les événements d’affichage doivent être envoyés manuellement pour indiquer le moment où l’offre a été affichée. Cela s’effectue via la commande sendEvent.

function sendDisplayEvent(decision) {
    const { id, scope, scopeDetails = {} } = decision;

    alloy("sendEvent", {
        "xdm": {
            "eventType": "decisioning.propositionDisplay",
            "_experience": {
                "decisioning": {
                    "propositions": [{
                        "id": id,
                        "scope": scope,
                        "scopeDetails": scopeDetails
                    }],
                    "propositionEventType": {
                        "display": 1
                    }
                }
            }
        }
    });
}

Exemple d’application sample-app

Pour vous aider à expérimenter et à en savoir plus sur ce type de personnalisation, nous vous proposons un exemple d’application que vous pouvez télécharger et utiliser pour les tests. Vous pouvez télécharger l’application, ainsi que des instructions détaillées sur son utilisation, à partir de ce référentiel GitHub.