Personalizzazione ibrida tramite Web SDK e API di Edge Network

Panoramica overview

La personalizzazione ibrida descrive il processo di recupero del contenuto di personalizzazione lato server, utilizzando l'API Edge Network, e di rendering lato client, utilizzando il Web SDK.

Puoi utilizzare la personalizzazione ibrida con soluzioni di personalizzazione come Adobe Target, Adobe Journey Optimizer o Offer Decisioning; la differenza consiste nel contenuto del payload dell'API Edge Network.

Prerequisiti prerequisites

Prima di implementare la personalizzazione ibrida nelle proprietà web, assicurati di soddisfare le seguenti condizioni:

Diagramma di flusso flow-diagram

Il diagramma di flusso seguente descrive l’ordine dei passaggi effettuati per distribuire la personalizzazione ibrida.

Cookie cookies

I cookie vengono utilizzati per rendere persistenti l’identità dell’utente e le informazioni sul cluster. Quando si utilizza un’implementazione ibrida, il server applicazioni Web gestisce l’archiviazione e l’invio di questi cookie durante il ciclo di vita della richiesta.

Posizionamento della richiesta request-placement

Le richieste API di Edge Network sono necessarie per ottenere proposte e inviare una notifica di visualizzazione. Quando si utilizza un’implementazione ibrida, il server applicazioni invia queste richieste all’API di Edge Network.

Stabilire l’host regionale di Edge Network regional-host

Per stabilire l'host regionale di Edge Network, leggere innanzitutto l'hint di posizione dal cookie kndctr_<orgId>_AdobeOrg_cluster, che può avere i seguenti valori:

Esempio: kndctr_53A16ACB5CC1D3760A495C99_AdobeOrg_cluster: va6

L'host regionale di Edge Network utilizza il seguente formato:<location_hint>.server.adobedc.net e può avere i seguenti valori:

Utilizzando questi host specifici, le richieste verranno indirizzate alla stessa posizione di Edge Network visitata in precedenza dall’utente e il sistema sarà in grado di fornire l’esperienza migliore, in quanto i dati utente sono presenti in tale posizione.

Se non è presente alcun hint di posizione (ovvero nessun cookie), utilizzare l'host predefinito: server.adobedc.net.

implicazioni di Analytics analytics

Quando implementi la personalizzazione ibrida, devi prestare particolare attenzione in modo che gli hit pagina non vengano conteggiati più volte in Analytics.

Quando configuri uno stream di dati per Analytics, gli eventi vengono inoltrati automaticamente in modo che gli hit di pagina vengano acquisiti.

Il campione di questa implementazione utilizza due diversi flussi di dati:

In questo modo, la richiesta lato server non registra alcun evento Analytics, ma le richieste lato client. Questo fa sì che le richieste di Analytics vengano conteggiate con precisione.

Creare la richiesta lato server server-side-request

La richiesta di esempio seguente illustra una richiesta API di Edge Network che il server applicazioni può utilizzare per recuperare il contenuto di personalizzazione.

Formato API

POST /ee/v2/interact

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

Intestazioni proxy proxy-headers

Per elaborare correttamente la richiesta sono necessarie le seguenti intestazioni.

Assicurati di impostarli correttamente in modo che puntino alle informazioni client effettive. Ad esempio, l'intestazione X-Forwarded-For deve contenere l'IP client per consentire la corretta geolocalizzazione.

Intestazioni agente utente user-agent-headers

Utilizza le seguenti intestazioni user-agent per elaborare correttamente la richiesta.

Predefinito

Bassa entropia (obbligatoria):

Alta entropia (facoltativa):

La richiesta deve essere inviata come indicato nella specifica API di Edge Network. Se il tuo caso d'uso lo richiede, consulta la documentazione sulla personalizzazione.

Risposta lato server server-response

La risposta di Edge Network conterrà state:store istruzioni, che devono essere trasformate in Set-Cookie intestazioni. Vengono salvati nel browser e possono essere utilizzati dall’implementazione Web SDK.

I cookie devono essere impostati sul dominio di primo livello, in modo che vengano inviati insieme a richieste all’implementazione del server e a quella del client. (O almeno un sottodominio comune utilizzato da entrambe le implementazioni)

Esempio:

I cookie devono essere impostati su .example.com in modo che vengano condivisi in entrambi i casi.

La risposta lato server è organizzata in frammenti denominati Handles, generati in base alla configurazione dello stream di dati. Ad esempio, i motori di personalizzazione in tempo reale restituiscono personalization:decisions handle, mentre il motore di attivazione in tempo reale genera activation:pull handle.

La risposta di esempio seguente mostra l’aspetto che potrebbe avere la risposta dell’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
      }
   ]
}

Richiesta lato client client-request

Nella pagina client viene chiamato il comando Web SDK applyResponse, passando le intestazioni e il corpo della risposta lato server.

   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"));

Le offerte JSON basate su moduli vengono applicate manualmente tramite il metodo applyPersonalization, per aggiornare DOM in base all'offerta di personalizzazione. Per le attività basate su moduli, gli eventi di visualizzazione devono essere inviati manualmente, per indicare quando è stata visualizzata l’offerta. Questa operazione viene eseguita tramite il comando 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
                    }
                }
            }
        }
    });
}

Applicazione di esempio sample-app

Per aiutarti a sperimentare e saperne di più su questo tipo di personalizzazione, forniamo un’applicazione di esempio che puoi scaricare e utilizzare per i test. Puoi scaricare l'applicazione, insieme a istruzioni dettagliate su come utilizzarla, da questo archivio GitHub.