Atualização do at.js 1.x para at.js 2.x

A versão mais recente da at.js no Adobe Target fornece conjuntos de recursos avançados para sua empresa personalizar tecnologias de próxima geração no lado do cliente. Essa nova versão tem como foco a atualização da at.js para ter interações harmoniosas com aplicativos de página única (SPAs).

Estes são alguns benefícios de usar a at.js 2.x que não estão disponíveis nas versões anteriores:

at.js 2.Diagramas do sistema x

Os diagramas a seguir ajudam a entender o fluxo de trabalho da at.js 2.x com Exibições e como isso melhora a integração do SPA. Para obter uma melhor introdução dos conceitos usados na at.js 2.x, consulte Implementação de aplicativos de página única.

(Clique na imagem para expandir até a largura total.)

Agora, onde quer triggerView() que seja implementada em seu SPA, as Exibições e as ações são recuperadas do cache e mostradas ao usuário, sem uma chamada de servidor. triggerView() também faz uma solicitação de notificações ao Target backend para aumentar e registrar contagens de impressão.

(Clique na imagem para expandir até a largura total.)

Implantar o at.js 2.x

Implantar o at.js 2.x por meio de marcas na extensão Adobe Experience Platform.

Funções obsoletas da at.js

Há várias funções que foram descontinuadas no at.js 2.x.

Você pode encontrar as funções obsoletas e a contraparte abaixo. Para obter uma lista completa das funções, consulte funções da at.js.

mboxCreate(mbox,params)

Descrição:

Executa uma solicitação e aplica a oferta ao DIV mais próximo com o nome de classe mboxDefault.

Exemplo:

<div class="mboxDefault">
  default content to replace by offer
</div>
<script>
  mboxCreate('mboxName','param1=value1','param2=value2');
</script>

at.js 2.x equivalente

Uma alternativa para mboxCreate(mbox, params) é getOffer() e applyOffer().

Exemplo:

<div class="mboxDefault">
  default content to replace by offer
</div>
<script>
  var el = document.currentScript.previousElementSibling;
  adobe.target.getOffer({
    mbox: "mboxName",
    params: {
      param1: "value1",
      param2: "value2"
    },
    success: function(offer) {
      adobe.target.applyOffer({
        mbox: "mboxName",
        selector: el,
        offer: offer
      });
    },
    error: function(error) {
      console.error(error);
      el.style.visibility = "visible";
    }
  });
</script>

mboxDefine() e mboxUpdate()

Descrição:

Cria um mapeamento interno entre um elemento e um nome de mbox, mas não executa a solicitação. Usada em conjunto com mboxUpdate(), que executa a solicitação e aplica a oferta ao elemento identificado pelo nodeId em mboxDefine(). Também pose ser usada para atualizar uma mbox iniciada por mboxCreate.

Exemplo:

<div id="someId" class="mboxDefault"></div>
<script>
 mboxDefine('someId','mboxName','param1=value1','param2=value2');
 mboxUpdate('mboxName','param3=value3','param4=value4');
</script>

at.js 2.x equivalente:

Uma alternativa para mboxDefine() e mboxUpdate é getOffer() e applyOffer(), com a opção do seletor usada em applyOffer(). Essa abordagem permite mapear a oferta para um elemento usando qualquer seletor de CSS, não apenas um com uma ID.

Exemplo:

<div id="someId" class="mboxDefault">
  default content to replace by offer
</div>
<script>
  adobe.target.getOffer({
    mbox: "mboxName",
    params: {
      param1: "value1",
      param2: "value2",
      param3: "value3",
      param4: "value4"
    },
    success: function(offer) {
      adobe.target.applyOffer({
        mbox: "mboxName",
        selector: "#someId",
        offer: offer
      });
    },
    error: function(error) {
      console.error(error);
      var el = document.getElementById("someId");
      el.style.visibility = "visible";
    }
  });
</script>

adobe.target.registerExtension()

Descrição:

Fornece uma forma padrão de registrar uma extensão específica.

Isso não é mais suportado e não deve ser usado.

Resumo das funções obsoletas, novas e suportadas at.js no 2.x

Limitações e chamadas de retorno

Esteja ciente das seguintes limitações e chamadas de retorno:

Rastreamento de conversão

Os clientes que usam mboxCreate() para rastreamento de conversão devem usar trackEvent() ou getOffer().

Entrega de oferta

Os clientes que não substituírem mboxCreate() por getOffer() ou applyOffer() correm o risco de não ter ofertas entregues.

O at.js 2.x pode ser usado em algumas páginas enquanto o at.js 1.x está em outras páginas?

Sim, o perfil do visitante é preservado nas páginas usando diferentes versões e bibliotecas. O formato de cookie é o mesmo.

Nova API usada no at.js 2.x

at.js 2.x usa uma nova API, que chamamos a API de Entrega. Para depurar se o at.js está chamando o servidor de borda do Target corretamente, você pode filtrar a guia Rede das Ferramentas do Desenvolvedor do seu navegador para "entrega", "tt.omtrdc.net", ou seu código de cliente. Você também notará que Target envia uma carga JSON em vez de pares de valores-chave.

Target A mbox global não é mais usada

Em at.js 2.x, você não verá mais "target-global-mbox" visivelmente nas chamadas de rede. Em vez disso, substituímos a sintaxe "target-global-mbox" por "execute > pageLoad" na carga JSON enviada aos servidores Target, como observado a seguir:

{
  "id": {
    // ...
  },
  "context": {
    "channel": "web",
    // ...
  },
  "execute": {
    "pageLoad": {}
  }
}

Basicamente, o conceito global de mbox foi apresentado para Target informar se recupera ofertas e conteúdo no carregamento de página. Dessa forma, deixamos isso mais explícito na versão mais recente.

O nome da mbox global no at.js não importa mais?

Os clientes podem especificar um nome de mbox global via Target > Administration > Implementation > Edit at.js Settings. Essa configuração é usada pelos servidores de borda Target para traduzir execute > pageLoad para o nome da mbox global que aparece na interface do Target. Isso permite que os clientes continuem a usar APIs do lado do servidor, o compositor baseado em formulário, scripts de perfil e criar públicos-alvo usando o nome global da mbox. Recomendamos que você também verifique se o mesmo nome global da mbox está configurado na página Administration > Visual Experience Composer, caso ainda tenha páginas que usam o at.js 1.x, conforme mostrado nas ilustrações a seguir.

e

A configuração de mbox global de criação automática precisa ser ativada para o at.js 2.x?

Na maioria dos casos, sim. Essa configuração informa à at.js 2.x para disparar uma solicitação nos servidores de borda Target ao carregar a página. Como a mbox global é traduzida para executar o > pageLoad e se você quiser acionar uma solicitação no carregamento da página, essa configuração deve estar ativada.

As atividades existentes do VEC continuarão a funcionar, mesmo que o nome da mbox global do Target não seja especificado no at.js 2.x?

Sim, porque executar > carga é tratado no Target backend como target-global-mbox.

Se minhas atividades baseadas em formulário forem direcionadas para o target-global-mbox, essas atividades continuarão funcionando?

Sim, porque executar > carga é tratado nos servidores Target de borda como target-global-mbox.

at.js 2 compatível e não compatível.Configurações de x

Suporte de rastreamento entre domínios no at.js 2.x

O rastreamento entre domínios possibilita unir visitantes em diferentes domínios. Como um novo cookie deve ser criado para cada domínio, é difícil rastrear os visitantes quando eles navegam de um domínio para outro. Para realizar o rastreamento entre domínios, o Target usa um cookie de terceiros para rastrear visitantes entre domínios. Isso permite criar uma atividade do Target que abrange o siteA.com e o siteB.com, e os visitantes permanecem na mesma experiência quando navegam entre domínios únicos. Esta funcionalidade se associa ao comportamento de cookies de terceiros e próprios de Target.

Em Target, o cookie de terceiros é armazenado em <CLIENTCODE>.tt.omtrdc.net. O cookie próprio é armazenado no clientdomain.com. A primeira solicitação retorna cabeçalhos de resposta HTTP que tentam instalar cookies de terceiros chamados mboxSession e mboxPC, enquanto uma solicitação de redirecionamento é enviada de volta com um parâmetro extra (mboxXDomainCheck=true). Se o navegador aceitar cookies de terceiros, a solicitação de redirecionamento vai inclui-los, e a experiência será retornada. Esse fluxo de trabalho é possível porque usamos o método HTTP GET.

No entanto, na at.js 2.x, HTTP GET não é usado. Em vez disso, o HTTP POST é usado por meio do at.js 2.x para enviar cargas JSON para Target servidores Edge. Usar POST HTTP significa que a solicitação de redirecionamento para verificar se um navegador aceita cookies de terceiros será interrompida. Isso ocorre porque as solicitações HTTP GET são transações idempotentes, enquanto HTTP POST é não idempotente e não deve ser repetido arbitrariamente. Por isso, o rastreamento entre domínios no at.js 2.Não há suporte para x (anterior a 2.10) imediatamente. Somente o at.js 1.x tem suporte pronto para uso para rastreamento entre domínios.

Para usar o rastreamento entre domínios para a at.js v2.10 ou posterior, você pode executar um dos seguintes procedimentos:

Para usar o rastreamento entre domínios para versões da at.js v2.x antes da versão 2.10, você pode implementar a opção #1 acima (instalar a biblioteca ECID).

Criar automaticamente mbox global é compatível

Essa configuração informa à at.js 2.x para disparar uma solicitação nos servidores de borda Target no carregamento da página. Como a mbox global é traduzida para executar > carga, e isso é interpretado pelos servidores Target de borda, os clientes devem ativar esse recurso se quiserem acionar uma solicitação no carregamento da página.

O nome da mbox global é compatível

Os clientes podem especificar um nome de mbox global via Target > Administration > Implementation > Edit. Essa configuração é usada pelos Target servidores de borda para traduzir executar > carga para o nome da mbox global inserido. Isso permite que os clientes continuem a usar APIs do lado do servidor, o compositor baseado em formulário, scripts de perfil e criar públicos-alvo que direcionem a mbox global.

Os eventos personalizados da at.js abaixo são aplicáveis a triggerView() ou são somente para applyOffer() ou applyOffers()?

Sim, os eventos personalizados da at.js triggerView() também se aplicam.

Ele informa quando eu chamo triggerView() com {"page" : "true"}, enviará uma notificação para o back-end do Target e aumentará a impressão. Também faz com que os scripts de perfil sejam executados?

Quando uma chamada de pré-busca é feita no Target backend, os scripts de perfil são executados. Consequentemente, os dados de perfil afetados serão criptografados e enviados para o lado do cliente. Após invocar triggerView() com {"page": "true"}, uma notificação é enviada juntamente com os dados de perfil criptografados. Isso ocorre quando o Target backend descriptografa os dados do perfil e armazena nos bancos de dados.

Precisamos adicionar um código que oculta previamente antes da chamada triggerView() a fim de gerenciar a cintilação?

Não, não é necessário adicionar código de pré-ocultação antes de chamar triggerView(). at.js 2.x gerencia a lógica de pré-ocultação e cintilação antes da exibição e aplicação da exibição.

Qual at.js 1.A at.js 2 não oferece suporte a x parâmetros para criar públicos-alvo.x?

Os seguintes parâmetros da at.js 1.x NÃO são suportados no momento para criação de público-alvo ao usar a at.js 2.x:

at.js 2.x não oferece suporte à criação de públicos-alvo usando parâmetros de vst.* parâmetros

Clientes na at.js 1.x puderam usar vst.* parâmetros de mbox para criar públicos. Esse foi um efeito colateral não intencional de como a at.js 1.x enviou parâmetros de mbox para o back-end Target. Depois de migrar para o at.js 2.x, não é mais possível criar públicos-alvo usando esses parâmetros, pois a at.js 2.x envia parâmetros de mbox de forma diferente.

compatibilidade com o at.js

As tabelas a seguir explicam o at.js. 2.x compatibilidade com diferentes tipos de atividades, integrações, recursos e funções da at.js.

Tipos de atividade

Integrações

Recursos

Parâmetros da string de consulta

Tokens de resposta

at.js 2.x, como a at.js 1.x, usa o evento personalizado at-request-succeeded para acionar tokens de resposta. Para obter exemplos de código usando o evento personalizado do at-request-succeeded, consulte Tokens de resposta.

at.js 1.x parâmetros para at.js 2.Mapeamento de carga x

Esta seção descreve os mapeamentos entre a at.js 1.x e at.js 2.x.

Antes de analisar o mapeamento de parâmetros, os endpoints usados por essas versões de biblioteca foram alterados:

Outra diferença significativa é que:

As seções a seguir listam todos os parâmetros da at.js 1.Parâmetro x, sua descrição e o 2 correspondente.x carga JSON (se aplicável):

at_property

(at.js 1.x parâmetro)

Usado para Permissões de usuário do Enterprise.

{
  ....
  "property": {
    "token": "1213213123122313121"
  }
  ....
}

mboxHost

(at.js 1.x parâmetro)

O domínio da página em que a biblioteca Target é executada.

at.js 2.x carga JSON:

{
  "context": {
    "browser": {
       "host": "test.com"
    }
  }
}

webGLRenderer

(at.js 1.x parâmetro)

Os recursos de renderização da Web GL do navegador. Isso é usado pelo nosso mecanismo de detecção de dispositivo para determinar se o dispositivo do visitante é um desktop, iPhone, dispositivo Android, etc.

at.js 2.x carga JSON:

{
  "context": {
    "browser": {
       "webGLRenderer": "AMD Radeon Pro 560X OpenGL Engine"
    }
  }
}

mboxURL

(at.js 1.x parâmetro)

O URL da página.

at.js 2.x carga JSON:

{
  "context": {
    "address": {
       "url": "http://test.com"
    }
  }
}

mboxReferrer

(at.js 1.x parâmetro)

O referenciador de página.

at.js 2.x carga JSON:

{
  "context": {
    "address": {
       "referringUrl": "http://google.com"
    }
  }
}

mbox (o nome) igual à mbox global

(at.js 1.x parâmetro)

A API de entrega não tem mais um conceito de mbox global. Na carga JSON, você deve usar execute > pageLoad.

at.js 2.x carga JSON:

{
  "execute": {
    "pageLoad": {
       "parameters": ....
       "profileParameters": ...
       .....
    }
  }
}

mbox (o nome) não é igual à mbox global

(at.js 1.x parâmetro)

Para usar um nome de mbox, passe-o para execute > mboxes. Uma mbox exige um índice e um nome.

at.js 2.x carga JSON:

{
  "execute": {
    "mboxes": [{
       "index": 0,
       "name": "some-mbox",
       "parameters": ....
       "profileParameters": ...
       .....
    }]
  }
}

mboxId

(at.js 1.x parâmetro)

Não está mais em uso.

mboxCount

(at.js 1.x parâmetro)

Não está mais em uso.

mboxRid

(at.js 1.x parâmetro)

A ID de solicitação usada por sistemas de downstream para ajudar na depuração.

at.js 2.x carga JSON:

{
  "requestId": "2412234442342"
  ....
}

mboxTime

(at.js 1.x parâmetro)

Não está mais em uso.

mboxSession

(at.js 1.x parâmetro)

A ID da sessão é enviada como parâmetro de sequência de consulta (sessionId) para o endpoint da API de entrega.

mboxPC

(at.js 1.x parâmetro)

A ID de TNT é passada para id > tntId.

at.js 2.x carga JSON:

{
  "id": {
    "tntId": "ca5ddd7e33504c58b70d45d0368bcc70.21_3"
  }
  ....
}

mboxMCGVID

(at.js 1.x parâmetro)

A ID de visitante da Experience Cloud é passada para id > marketingCloudVisitorId.

at.js 2.x carga JSON:

{
  "id": {
    "marketingCloudVisitorId": "797110122341429343505"
  }
  ....
}

vst.aaaa.id e vst.aaaa.authState

(at.js 1.x parâmetros)

As IDs do cliente devem ser passadas para id > customerIds.

at.js 2.x carga JSON:

{
  "id": {
    "customerIds": [{
       "id": "1232131",
       "integrationCode": "aaaa",
       "authenticatedState": "....."
     }]
  }
  ....
}

mbox3rdPartyId

(at.js 1.x parâmetro)

A ID de terceiros do cliente usada para vincular Target IDs diferentes.

at.js 2.x carga JSON:

{
  "id": {
    "thirdPartyId": "1232312323123"
  }
  ....
}

mboxMCSDID

(at.js 1.x parâmetro)

SDID, também conhecida como ID de dados complementares. Deve ser passado para experienceCloud > analytics > supplementalDataId.

at.js 2.x carga JSON:

{
  "experienceCloud": {
    "analytics": {
      "supplementalDataId": "1212321132123131"
    }
  }
  ....
}

vst.trk

(at.js 1.x parâmetro)

Servidor de rastreamento de Analytics. Deve ser passado para experienceCloud > analytics > trackingServer.

at.js 2.x carga JSON:

{
  "experienceCloud": {
    "analytics": {
      "trackingServer": "analytics.test.com"
    }
  }
  ....
}

vst.trks

(at.js 1.x parâmetro)

Servidor de rastreamento do Analytics seguro. Deve ser passado para experienceCloud > analytics > trackingServerSecure.

at.js 2.x carga JSON:

{
  "experienceCloud": {
    "analytics": {
      "trackingServerSecure": "secure-analytics.test.com"
    }
  }
  ....
}

mboxMCGLH

(at.js 1.x parâmetro)

Dica de localização do Audience Manager. Deve ser passado para experienceCloud > audienceManager > locationHint.

at.js 2.x carga JSON:

{
  "experienceCloud": {
    "audienceManager": {
      "locationHint": 9
    }
  }
  ....
}

mboxAAMB

(at.js 1.x parâmetro)

Blob do Audience Manager. Deve ser passado para experienceCloud > audienceManager > blob.

at.js 2.x carga JSON:

{
  "experienceCloud": {
    "audienceManager": {
      "blob": "2142342343242342"
    }
  }
  ....
}

mboxVersion

(at.js 1.x parâmetro)

A versão é enviada como um parâmetro de sequência de consulta por meio do parâmetro da versão.

Vídeo de treinamento: at.js 2.x diagrama de arquitetura

at.js 2.O x aprimora o suporte do Adobe Target para SPA e integra-se com outras soluções de Experience Cloud. Este vídeo explica como tudo se une.

Consulte Noções básicas sobre o at.js 2.x funciona para obter mais informações.