Linker

O plug-in do linker simplifica o processo de implementação do acompanhamento de vários domínios, conforme descrito no guia de acompanhamento de vários domínios para analytics.js.

Visão geral

O acompanhamento de vários domínios funciona compartilhando um único ID de cliente entre um domínio de origem e um domínio 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 linker faz isso adicionando um parâmetro de linker aos URLs que direcionam para o domínio de destino. O parâmetro de linker contém o ID de cliente, a data e hora atual e os metadados do navegador codificados. A data e hora e os metadados são usados para evitar problemas com o compartilhamento do URL.

O parâmetro do linker tem uma aparência parecida com esta:

_ga=1.199239214.1624002396.1440697407

No domínio de destino, o campo allowLinker é fornecido. Quando ele é definido como true, instrui o analytics.js para verificar parâmetros do linker no URL. Se o parâmetro do linker for encontrado e for válido, o Client-ID será extraído do parâmetro e armazenado.

Com o plug-in do linker, é possível adicionar automática e manualmente o parâmetro do linker 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 linker

Para configurar a vinculação automática de vários domínios no domínios de origem de URLs que direcionam para o domínio de destino, você precisa exigir o plug-in do linker e chamar o método autoLink dele.

É possível chamar o método autoLink por meio da fila de comandos.

Depois de executado, o analytics.js monitorará cliques em links que direcionam para o domínio (ou domínios) de destino e adicionará o parâmetro do linker a esses links imediatamente depois do início da navegação. É necessário aguardar até que o usuário clique em um link para adicionar o parâmetro do linker porque parâmetros do linker expiram depois de dois minutos.

O parâmetro opcional decorateForms deve ser especificado e definido como true se há formulários no site que direcionam 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 para correspondência com o hostname de um URL, indicando quais domínios se aplicam à vinculação automática. Se uma string é passada, o analytics.js realiza uma correspondência de substring. Assim, example.com corresponderá a links que direcionam para blog.example.com.
useAnchor boolean não Quando definido como "true", o parâmetro do linker é adicionado à parte de âncora do URL, não à parte de consulta.
decorateForms boolean não Quando definido como "true", o plug-in do linker adiciona um parâmetro do linker para formar envios que direcionam para destinos que correspondem 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 linker

Você pode adicionar manualmente o parâmetro do linker a determinado elemento <a> ou <form> por meio do método decorate. Esse método só é necessário quando você não usa o método autoLink descrito acima.

decorate

É possível chamar o método decorate por meio da fila de comandos.

É importante se certificar de que o método "decorate" seja chamado o mais perto possível do momento da navegação, pois os parâmetros do linker expiram depois de 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 ser anexado no parâmetro do linker.
useAnchor boolean não Quando definido como "true", o parâmetro do linker é 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ê pode acessar manualmente o parâmetro do linker que um rastreador usará por meio do campo linkerParam.

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

Configuração de um site para aceitar parâmetros do linker

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

Você pode instruir a página de destino para procurar parâmetros do linker configurando o campo allowLinker como true ao criar o rastreador:

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

Acompanhamento 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 no acompanhamento 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 visitarão primeiro, você precisa implementar o acompanhamento bidirecional de vários domínios, em que cada domínio é configurado para funcionar como a origem ou o destino.

Para implementar o acompanhamento bidirecional de vários domínios, ative a vinculação automática nos dois domínios e configure-os para aceitar parâmetros do linker.

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 ainda mais, você pode listar todos os domínios possíveis que deseja acompanhar no método autoLink. Assim, é possível usar o mesmo snippet de código em todos os domínios:

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