Vinculador

O plug-in do vinculador simplifica a implementação da medição de vários domínios, como descrito no guia de medição de vários domínios da analytics.js.

Visão geral

A medição de vários domínios compartilha um ID do cliente exclusivo entre um domínio de origem e outro de destino. Esse processo é realizado em duas etapas:

  1. O domínio de origem precisa garantir que todos os URLs que direcionam para o domínio de destino contenham o ID de cliente do domínio de origem.
  2. O domínio de destino precisa saber como verificar a presença de um ID de cliente no URL quando o usuário navega até ele.

O plug-in do vinculador faz isso adicionando um parâmetro de vinculador aos URLs que direcionam para o domínio de destino. O parâmetro do vinculador contém o ID de cliente, a data e hora atual e os metadados do navegador codificados. O carimbo de data/hora e os metadados são usados para evitar problemas com o compartilhamento do URL.

O parâmetro do vinculador é uma sequência semelhante a esta:

_ga=1.199239214.1624002396.1440697407

O campo allowLinker é fornecido no domínio de destino. Quando ele é definido como true, a analytics.js é instruída a verificar os parâmetros do vinculador no URL. Se o parâmetro for encontrado e válido, a biblioteca vai extrair e armazenar o ID do cliente.

Com o plug-in do vinculador, é possível adicionar de forma automática e manual o parâmetro correspondente a URLs em links e formulários na página. Na maioria dos casos, a forma automática é recomendada.

Adição automática de parâmetros do vinculador

Para configurar a vinculação automática de vários domínios no domínio de origem em URLs que direcionam ao domínio de destino, é necessário solicitar o plug-in do vinculador e chamar o método autoLink dele.

É possível chamar o método autoLink usando a fila de comandos.

Depois da execução, a analytics.js vai monitorar os cliques em links que direcionam para os domínios de destino e adicionar o parâmetro do vinculador a esses links imediatamente antes do início da navegação. É necessário aguardar até que o usuário clique em um link para adicionar o parâmetro do vinculador porque esses parâmetros expiram após dois minutos.

O parâmetro opcional decorateForms precisará ser especificado e definido como true se você tiver formulários no seu site que apontem para o domínio de destino.

Uso

ga('[trackerName.]linker:autoLink', domains, [useAnchor], [decorateForms]);

Parâmetros

Nome Tipo Obrigatório Descrição
domains Array[RexExp|string] Sim Uma matriz de strings ou expressões regulares que correspondem ao hostname de um URL e indicam a vinculação automática de domínios. Se uma string for enviada, a analytics.js vai realizar uma correspondência de substring, ou seja, example.com vai corresponder aos links que apontam para blog.example.com.
useAnchor boolean Não Quando definido como "true", o parâmetro do vinculador é adicionado à parte de âncora do URL, não à parte de consulta.
decorateForms boolean Não Quando definido como "true", o plug-in do vinculador adiciona um parâmetro aos envios de formulário que redirecionam para os destinos correspondentes ao parâmetro domain.

Exemplo

// Loads the Linker plugin
ga('require', 'linker');

// Instructs the Linker plugin to automatically add linker parameters
// to all links and forms pointing to the domain "destination.com".
ga('linker:autoLink', ['destination.com'], false, true);

Adição manual de parâmetros do vinculador

Você pode adicionar manualmente o parâmetro do vinculador a um elemento <a> ou <form> específico pelo método decorate, que só é necessário quando o autoLink descrito acima não estiver sendo usado.

decorate

É possível chamar o método decorate usando a fila de comandos.

É importante garantir que o método "decorate" seja chamado o mais perto possível do momento da navegação porque os parâmetros do vinculador expiram após dois minutos. Na maioria das vezes, esse método deve ser chamado em um manipulador de eventos.

Uso

ga('[trackerName.]linker:decorate', element, [useAnchor]);

Parâmetros

Nome Tipo Obrigatório Descrição
element HTMLElement Sim O elemento <a> ou <form> a que o parâmetro do vinculador será anexado.
useAnchor boolean Não Quando definido como "true", o parâmetro do vinculador é adicionado à parte de âncora do URL, não à parte de consulta.

Exemplo

// Loads the Linker plugin
ga('require', 'linker');

// Gets a reference to a link pointing to an external domain.
var destinationLink = document.getElementById('destination-link');

// Adds click handler that decorates `destinationLink`.
destinationLink.addEventListener('click', function() {
  ga('linker:decorate', destinationLink);
});

linkerParam

Além do método decorate, você também pode acessar manualmente o parâmetro do vinculador que um rastreador usará com o campo linkerParam.

ga(function(tracker) {
  var linkerParam = tracker.get('linkerParam');
});

Como configurar um site para aceitar parâmetros do vinculador

Depois que o usuário acessa uma página no domínio de destino com um parâmetro do vinculador no URL, a analytics.js precisa saber como procurar esse parâmetro.

Você pode configurar a página de destino para que ela procure os parâmetros do vinculador. Basta definir o campo allowLinker como true ao criar o rastreador:

ga('create', 'UA-XXXXXX-X', 'auto', {
  allowLinker: true
});

Medição bidirecional de vários domínios

Um fluxo de usuários em que os usuários sempre começam no domínio de origem e só depois acessam o domínio de destino é considerado uma medição unidirecional de vários domínios. As instruções acima consideram esse tipo de fluxo de usuários.

Nos casos em que não se sabe qual domínio os usuários vão visitar primeiro, você precisa implementar a medição bidirecional de vários domínios, em que cada domínio é configurado para funcionar como a origem ou o destino.

Para implementar esse processo, ative a vinculação automática em ambos os domínios e configure-os para aceitar os parâmetros do vinculador.

Em source.com:

ga('create', 'UA-XXXXX-Y', 'auto', {allowLinker: true});
ga('require', 'linker');
ga('linker:autoLink', ['destination.com']);

Em destination.com:

ga('create', 'UA-XXXXX-Y', 'auto', {allowLinker: true});
ga('require', 'linker');
ga('linker:autoLink', ['source.com']);

Uso de um único snippet em todos os domínios

Para simplificar esse fluxo ainda mais, você pode listar no método autoLink todos os domínios que você gostaria de medir. Isso permite usar o mesmo snippet de código em cada um deles:

ga('create', 'UA-XXXXX-Y', 'auto', {allowLinker: true});
ga('require', 'linker');
ga('linker:autoLink', ['source.com', 'destination.com']);