Personalización híbrida mediante Web SDK y API de Edge Network

Información general overview

La personalización híbrida describe el proceso de recuperar contenido de personalización del lado del servidor, utilizando la API de Edge Network y procesándolo del lado del cliente, utilizando Web SDK.

Puede utilizar la personalización híbrida con soluciones de personalización como Adobe Target, Adobe Journey Optimizer o Offer Decisioning, la diferencia es el contenido de la carga útil Edge Network API.

Requisitos previos prerequisites

Antes de implementar la personalización híbrida en las propiedades web, asegúrese de cumplir las siguientes condiciones:

Diagrama de flujo flow-diagram

El diagrama de flujo siguiente describe el orden de los pasos realizados para ofrecer una personalización híbrida.

Cookies cookies

Las cookies se utilizan para mantener la identidad del usuario y la información de clúster. Al utilizar una implementación híbrida, el servidor de aplicaciones web gestiona el almacenamiento y el envío de estas cookies durante el ciclo vital de la solicitud.

Solicitar ubicación request-placement

Las solicitudes de API de Edge Network son necesarias para obtener propuestas y enviar una notificación de visualización. Al utilizar una implementación híbrida, el servidor de aplicaciones realiza estas solicitudes a la API de Edge Network.

Establecimiento del host regional de Edge Network regional-host

Para establecer el host regional de Edge Network, lea primero la sugerencia de ubicación de la cookie kndctr_<orgId>_AdobeOrg_cluster, que puede tener los siguientes valores:

Ejemplo: kndctr_53A16ACB5CC1D3760A495C99_AdobeOrg_cluster: va6

El host regional de Edge Network utiliza el siguiente formato: <location_hint>.server.adobedc.net y puede tener los siguientes valores:

Al utilizar estos hosts específicos, las solicitudes se dirigen a la misma ubicación de Edge Network que el usuario visitó anteriormente y el sistema puede ofrecer la mejor experiencia, ya que los datos de usuario están presentes en la ubicación.

Si no hay ninguna sugerencia de ubicación (es decir, ninguna cookie), use el host predeterminado: server.adobedc.net.

Implicaciones de Analytics analytics

Al implementar la personalización híbrida, debe prestar especial atención para que las visitas a la página no se cuenten varias veces en Analytics.

Al configurar una secuencia de datos para Analytics, los eventos se reenvían automáticamente para que se capturen las visitas a la página.

El ejemplo de esta implementación utiliza dos flujos de datos diferentes:

De este modo, la solicitud del lado del servidor no registra ningún evento de Analytics, pero las solicitudes del lado del cliente sí. Esto hace que las solicitudes de Analytics se cuenten con precisión.

Generar la solicitud del lado del servidor server-side-request

La solicitud de ejemplo siguiente ilustra una solicitud de API de Edge Network que el servidor de aplicaciones podría utilizar para recuperar el contenido de personalización.

Formato de API

POST /ee/v2/interact

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

Encabezados de proxy proxy-headers

Se requieren los siguientes encabezados para procesar correctamente la solicitud.

Asegúrese de configurarlas correctamente para que indiquen la información real del cliente. Por ejemplo, el encabezado X-Forwarded-For debe contener la dirección IP del cliente para que se realice la geolocalización adecuada.

Encabezados de agente de usuario user-agent-headers

Utilice los siguientes encabezados de usuario-agente para procesar correctamente la solicitud.

Predeterminado

Baja entropía (obligatoria):

Alta entropía (opcional):

La solicitud debe enviarse tal como se muestra en la especificación de API de Edge Network. Consulte la documentación de personalización si su caso de uso lo requiere.

Respuesta del lado del servidor server-response

La respuesta de Edge Network contendrá state:store instrucciones, que deben transformarse en Set-Cookie encabezados. Se guardan en el explorador y la implementación de Web SDK puede utilizarlos.

Las cookies deben configurarse en el dominio de nivel superior para que se envíen junto con solicitudes a la implementación del servidor y a la del cliente. (O al menos un subdominio común utilizado por ambas implementaciones)

Por ejemplo:

Las cookies deben establecerse en .example.com para que se compartan en ambos casos.

La respuesta del lado del servidor está organizada en fragmentos llamados Handles, que se generan según la configuración de la secuencia de datos. Por ejemplo, los motores de personalización en tiempo real devuelven identificadores de personalization:decisions, mientras que el motor de activación en tiempo real produce identificadores de activation:pull.

La respuesta de ejemplo siguiente muestra cómo podría ser la respuesta de la API de Edge Network.

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

Solicitud del lado del cliente client-request

En la página del cliente, se llama al comando Web SDK applyResponse, pasando los encabezados y el cuerpo de la respuesta del lado del servidor.

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

Las ofertas JSON basadas en formularios se aplican manualmente mediante el método applyPersonalization para actualizar DOM según la oferta de personalización. Para las actividades basadas en formularios, los eventos de visualización deben enviarse manualmente para indicar cuándo se ha mostrado la oferta. Esto se realiza mediante el 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
                    }
                }
            }
        }
    });
}

Aplicación de ejemplo sample-app

Para ayudarle a experimentar y obtener más información sobre este tipo de personalización, le proporcionamos una aplicación de muestra que puede descargar y utilizar para realizar pruebas. Puede descargar la aplicación, junto con instrucciones detalladas sobre cómo utilizarla, desde este repositorio de GitHub.