Vinculador

O plug-in do vinculador simplifica o processo de implementação da avaliação de vários domínios, conforme descrito no guia correspondente da analytics.js.

Visão geral

A avaliação de vários domínios compartilha um Client-ID 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 mesmo Client-ID que ele.
  2. O domínio de destino precisa verificar se há um Client-ID no URL quando o usuário acessa a página.

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 for válido, a biblioteca extrairá o Client-ID dele e o armazenará.

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 por meio da fila de comandos.

Depois da execução, a analytics.js 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 realizará uma correspondência de substring, ou seja, example.com 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 apontam 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 por meio do 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 por meio da 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á por meio do 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
});

Avaliaçã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 avaliaçã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 visitarão primeiro, você precisa implementar a avaliaçã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 avaliar. 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']);