Instalar a Camada de dados de clientes Adobe

A instalação da Camada de dados de clientes Adobe (ACDL) envolve duas partes:

  1. Crie a matriz de camada de dados em cada script que a envia, para que seu código funcione independentemente de a ACDL ainda ter sido carregada ou não.
  2. Carregar a biblioteca ACDL uma vez por página, usando um dos métodos de instalação.

Criar a matriz da camada de dados initialize

Adicione a seguinte linha antes de qualquer código que envie para a camada de dados:

window.adobeDataLayer = window.adobeDataLayer || [];

Essa linha cria a matriz se ela não existir e a mantém se existir. Inclua-a em cada script que enviar para a camada de dados, não apenas na primeira. Os scripts podem ser carregados em qualquer ordem e a linha garante que cada script envie para o mesmo array sem substituí-lo.

Após esta linha, enviar dados, eventos e funções com push():

window.adobeDataLayer = window.adobeDataLayer || [];
window.adobeDataLayer.push({ page: { title: "Home" } });

Até o ACDL ser carregado, push() é o método de matriz padrão do JavaScript e a matriz funciona como uma fila. Quando o ACDL é carregado, ele processa os itens em fila em ordem. Consulte Fila e histórico.

IMPORTANT
ACDL sempre usa o nome global adobeDataLayer. A biblioteca não tem suporte para outros nomes. A extensão de tag pode fazer com que um segundo nome se refira à mesma camada de dados.

Escolha um método de instalação methods

Carregue o ACDL em cada página com um dos seguintes métodos:

Método
Use-o quando
Extensão da tag
Você usa tags na Adobe Experience Platform. A extensão pode carregar a ACDL para você.
Marca de script
Você mesmo deseja hospedar o arquivo de biblioteca e adicioná-lo aos modelos de página.
npm
Você cria o JavaScript do site com um pacote.
Adobe Experience Manager
Seu site usa os Componentes principais do AEM 2.9.0 ou posterior.

Extensão de tag tags

A extensão de marca da Camada de Dados do Cliente Adobe carrega o ACDL quando a biblioteca de marcas é carregada, a menos que a página já a carregue. Não é necessário adicionar a biblioteca aos modelos de página. O código do site ainda precisa criar a matriz de camada de dados e enviar dados por push. Consulte Configurar a extensão da Camada de Dados de Clientes Adobe.

Tag de script script

Baixe a biblioteca do npm (consulte npm) e o host adobe-client-data-layer.min.js no site. Em seguida, carregue-o no <head> de cada página com os atributos async e defer:

<script src="/js/adobe-client-data-layer.min.js" async defer></script>

Os navegadores compatíveis com o async executam o script assim que ele é baixado, sem bloquear a página. Como a ACDL processa tudo o que foi enfileirado antes de ser carregado, seus dados estarão seguros mesmo se outros scripts enviarem primeiro para a camada de dados.

O exemplo a seguir mostra uma página em que um script integrado e um script externo são enviados para a camada de dados antes do carregamento da ACDL:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>My page</title>
    <script src="/js/myscripts.js" defer></script>
    <script>
      window.adobeDataLayer = window.adobeDataLayer || [];
      window.adobeDataLayer.push({ page: { title: "My page" } });
    </script>
    <script src="/js/adobe-client-data-layer.min.js" async defer></script>
  </head>
  <body>
    <h1>My page</h1>
  </body>
</html>

O script externo, /js/myscripts.js, também cria a matriz antes de enviar:

window.adobeDataLayer = window.adobeDataLayer || [];
window.adobeDataLayer.push({ user: { loggedIn: false } });

NCDNs npm públicos, como unpkg e jsDelivr, também atendem ao arquivo de biblioteca. Se você carregá-lo de um CDN de terceiros, fixe uma versão exata no URL para que o arquivo não seja alterado sem o seu conhecimento.

npm npm

Instale o pacote:

npm install @adobe/adobe-client-data-layer

O pacote contém um script de navegador em dist/adobe-client-data-layer.min.js. Copie esse arquivo para o site e carregue-o com uma marca de script ou importe o arquivo para o seu JavaScript agrupado:

import "@adobe/adobe-client-data-layer/dist/adobe-client-data-layer.min.js";

O script não exporta nada. Quando ele é executado, configura window.adobeDataLayer.

NOTE
Na ACDL 3.x, importe o caminho de arquivo mostrado acima. O pacote 3.x não define um ponto de entrada, portanto, import "@adobe/adobe-client-data-layer" falha.

Adobe Experience Manager aem

Os Componentes principais do AEM 2.9.0 e posteriores incluem o ACDL como uma biblioteca do cliente e os Componentes principais enviam dados e eventos para cada componente. Consulte Uso da Camada de Dados de Clientes Adobe com os Componentes Principais.

Se o site do AEM também usar a extensão de tag ACDL, desative a opção Carregar a biblioteca da Camada de dados do cliente Adobe, se ausente, para que somente o AEM carregue a biblioteca. Consulte Configurar a extensão da Camada de Dados de Clientes Adobe.

Carregar a biblioteca apenas uma vez load-once

Carregar ACDL uma vez por página. Se uma segunda cópia for carregada, ela registrará o seguinte aviso no console do navegador e não alterará a camada de dados:

Adobe Client Data Layer v3.0.1 has already been imported/initialized on this page. You may be erroneously loading it a second time.

A primeira cópia continua em execução, de modo que os dados e os ouvintes ainda funcionam. Remova a duplicata para evitar o download extra. Duplicatas são comuns quando um modelo de página e a extensão de tag carregam a biblioteca.

Verificar a instalação verify

Abra o console do desenvolvedor do navegador em uma página que carregue o ACDL e execute os seguintes comandos:

adobeDataLayer.version     // For example, "3.0.1"
adobeDataLayer.getState()  // The computed state of everything pushed so far

Se adobeDataLayer.version for undefined, ACDL não foi carregado na página. Consulte Solução de problemas.

Atualização do 2.x para o 3.x upgrade

Os Componentes principais do Adobe Experience Manager carregam a ACDL 2.x por padrão, muitos sites ainda executam a 2.x. Revise as alterações a seguir antes de atualizar para a versão 3.x. Para todas as versões, consulte as notas de versão no GitHub.

O ACDL 3.0 substituiu sua biblioteca de utilitários interna por recursos de navegador incorporados. O arquivo é muito menor, mas os requisitos e alguns comportamentos de mesclagem foram alterados:

Área
2.x
3.x
Requisitos do navegador
Navegadores mais antigos suportados
Requer o structuredClone() e o JavaScript moderno. Consulte Requisitos do navegador.
Tamanho do arquivo (minificado)
Cerca de 33 KB
Cerca de 6 KB
Envio de uma matriz para uma chave que já contém uma matriz
Mescla as matrizes por posição. ["c"] de push sobre ["a", "b"] resulta em ["c", "b"].
Substitui a matriz. ["c"] de push sobre ["a", "b"] resulta em ["c"]. Consulte Matrizes.
Enviar um objeto para uma chave que contenha string, número ou booleano
Substitui o valor pelo objeto.
Não substitui o valor. Consulte Alterar o tipo de um valor.
Notação de colchetes em getState() caminhos, como items[0].sku
Suportado
Não suportado. Use a notação de pontos, como items.0.sku. Consulte getState().
ponto de entrada do pacote npm
import "@adobe/adobe-client-data-layer" carrega a biblioteca.
Importe o caminho do arquivo. Consulte npm.

Teste sua implementação após a atualização, especialmente o código que envia matrizes ou altera o tipo de um valor.

recommendation-more-help
experience-platform-help-collection