Personalização híbrida usando o Web SDK e a API do Edge Network

Visão geral overview

A personalização híbrida descreve o processo de recuperação de conteúdo de personalização no lado do servidor, usando a API do Edge Network, e de renderização no lado do cliente, usando a Web SDK.

Você pode usar personalização híbrida com soluções de personalização como Adobe Target, Adobe Journey Optimizer ou Offer Decisioning, sendo que a diferença é o conteúdo da carga da API do Edge Network.

Pré-requisitos prerequisites

Antes de implementar a personalização híbrida em suas propriedades da Web, verifique se você atende às seguintes condições:

Diagrama de Fluxo flow-diagram

O diagrama de fluxo abaixo descreve a ordem das etapas executadas para fornecer personalização híbrida.

Cookies cookies

Os cookies são usados para manter a identidade do usuário e as informações do cluster. Ao usar uma implementação híbrida, o servidor de aplicações web manipula o armazenamento e o envio desses cookies durante o ciclo de vida da solicitação.

Solicitar posicionamento request-placement

As solicitações de API do Edge Network são necessárias para obter apresentações e enviar uma notificação de exibição. Ao usar uma implementação híbrida, o servidor de aplicativos faz essas solicitações à API do Edge Network.

Estabelecer o host regional da Edge Network regional-host

Para estabelecer o host regional do Edge Network, primeiro leia a dica de localização do cookie kndctr_<orgId>_AdobeOrg_cluster, que pode ter os seguintes valores:

Exemplo: kndctr_53A16ACB5CC1D3760A495C99_AdobeOrg_cluster: va6

O host regional Edge Network usa o seguinte formato:<location_hint>.server.adobedc.net e pode ter os seguintes valores:

Ao usar esses hosts específicos, as solicitações serão direcionadas para o mesmo local do Edge Network que o usuário visitou antes e o sistema poderá fornecer a melhor experiência, pois os dados do usuário estão presentes nele.

Se nenhuma dica de localização (ou seja, nenhum cookie) estiver presente, use o host padrão: server.adobedc.net.

Implicações do Analytics analytics

Ao implementar a personalização híbrida, você deve prestar atenção especial para que as ocorrências de página não sejam contadas várias vezes no Analytics.

Quando você configura uma sequência de dados para o Analytics, os eventos são automaticamente encaminhados para que as ocorrências da página sejam capturadas.

A amostra dessa implementação usa dois fluxos de dados diferentes:

Dessa forma, a solicitação do lado do servidor não registra eventos do Analytics, mas as solicitações do lado do cliente registram. Isso faz com que as solicitações do Analytics sejam contadas com precisão.

Criar a solicitação do lado do servidor server-side-request

O exemplo de solicitação abaixo ilustra uma solicitação da API do Edge Network que o servidor de aplicativos poderia usar para recuperar o conteúdo de personalização.

Formato da API

POST /ee/v2/interact

Solicitação 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"
         }]
      }
   }
}'

Cabeçalhos de proxy proxy-headers

Os seguintes cabeçalhos são necessários para processar a solicitação corretamente.

Defina-os corretamente para apontar para as informações reais do cliente. Por exemplo, o cabeçalho X-Forwarded-For deve conter o IP do cliente para que a geolocalização adequada ocorra.

Cabeçalhos do usuário-agente user-agent-headers

Use os seguintes cabeçalhos user-agent para processar a solicitação corretamente.

Padrão

Baixa entropia (obrigatório):

Alta entropia (opcional):

A solicitação deve ser enviada conforme mostrado na especificação da API Edge Network. Consulte a documentação de personalização, se necessário.

Resposta do lado do servidor server-response

A resposta do Edge Network conterá state:store instruções, que devem ser transformadas em Set-Cookie cabeçalhos. Eles serão salvos no navegador e a implementação do Web SDK poderá usá-los.

Os cookies devem ser definidos no domínio de nível superior, para que sejam enviados junto com solicitações para a implementação do servidor e do cliente. (Ou pelo menos um subdomínio comum usado por ambas as implementações)

Exemplo:

Os cookies devem ser definidos em .example.com para que sejam compartilhados em ambos os casos.

A resposta do lado do servidor é organizada em fragmentos chamados Handles, que são gerados dependendo da configuração da sequência de dados. Por exemplo, os mecanismos de personalização em tempo real retornam personalization:decisions identificadores enquanto o mecanismo de ativação em tempo real produz activation:pull identificadores.

O exemplo de resposta abaixo mostra como pode ser a resposta da API do Edge Network.

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

Solicitação do lado do cliente client-request

Na página do cliente, o comando Web SDK applyResponse é chamado, transmitindo os cabeçalhos e o corpo da resposta do lado do 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"));

As ofertas JSON baseadas em formulário são aplicadas manualmente por meio do método applyPersonalization, para atualizar o DOM com base na oferta de personalização. Para atividades baseadas em formulário, os eventos de exibição devem ser enviados manualmente para indicar quando a oferta foi exibida. Isso é feito por meio do 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
                    }
                }
            }
        }
    });
}

Aplicativo de amostra sample-app

Para ajudá-lo a experimentar e saber mais sobre esse tipo de personalização, fornecemos um aplicativo de amostra que você pode baixar e usar para testes. Você pode baixar o aplicativo, juntamente com instruções detalhadas sobre como usá-lo, neste repositório do GitHub.