Acompanhamento de aplicativo de página única

Este guia descreve como usar o analytics.js para acompanhar páginas em sites cujo conteúdo é carregado dinamicamente sem o carregamento tradicional de página inteira.

Visão geral

O aplicativo de página única (SPA, na sigla em inglês) é um aplicativo da Web ou website que carrega todos os recursos necessários para navegar por todo o site no primeiro carregamento de página. À medida que o usuário clica em links e interage com a página, o conteúdo subsequente é carregado dinamicamente. O aplicativo atualiza o URL na barra de endereços para emular a navegação tradicional nas páginas. No entanto, outra solicitação de página inteira nunca é feita.

O snippet de acompanhamento JavaScript padrão funciona bem com websites tradicionais porque ele é executado cada vez que os usuários carregam uma nova página. No entanto, para um aplicativo de página única, no qual o site carrega o conteúdo da nova página dinamicamente em vez de carregamentos de página completos, o código do snippet analytics.js é executado apenas uma vez. Isto significa que as exibições de página subsequentes (virtuais) precisam ser acompanhadas manualmente, à medida que o novo conteúdo é carregado.

Acompanhamento de exibições virtuais de página

Quando o aplicativo carrega conteúdo dinamicamente e atualiza o URL na barra de endereços, os dados armazenados no seu rastreador também serão atualizados.

Para atualizar o rastreador, use o comando set e forneça o novo valor page:

ga('set', 'page', '/new-page.html');

Depois que você determinar o novo valor da página, todos os hits subsequentes enviados usarão esse novo valor. Para registrar uma exibição de página, envie um hit de exibição de página imediatamente após atualizar o rastreador.

ga('set', 'page', '/new-page.html');
ga('send', 'pageview');

Tecnicamente, o comando send para os hits de exibição de página aceita um campo page opcional como terceiro parâmetro. No entanto, o uso do campo page desse modo não é recomendado para o acompanhamento de aplicativos de página única. Isso ocorre porque os campos passados pelo comando send não são definidos no rastreador, mas se aplicam somente ao hit atual. A não atualização do rastreador causará problemas se o aplicativo enviar hits que não sejam de exibição de página (por exemplo, eventos ou interações em redes sociais). Isso ocorre porque os hits são associados com o valor page que o rastreador tinha ao ser criado.

Tratamento de vários URLs para o mesmo recurso

Alguns SPAs atualizam somente o hash do URL quando eles carregam conteúdo dinamicamente. Isso pode criar situações em que muitos caminhos de página diferentes apontam para o mesmo recurso. Nesses casos, normalmente é melhor escolher um URL canônico e enviar somente o valor page dele para o Google Analytics.

Por exemplo, considere um website cuja página "Sobre" pode ser acessada por meio de um dos URLs a seguir:

  • /about.html
  • /#about.html
  • /home.html#about.html

Para evitar a duplicação nos seus relatórios, é melhor acompanhar todas essas exibições de página como /about.html.

Considerações importantes

Não atualizar o referenciador do documento

Quando você cria um objeto de acompanhamento usando o comando create, o valor de document.referrer é armazenado no campo referrer do rastreador. No contexto de um aplicativo de página única que não usa carregamentos de página completa, o campo referrer sempre será o mesmo.

Apesar disso, não é necessário atualizar o campo "referrer" manualmente antes de enviar hits de exibições de página. O Google Analytics é capaz de determinar automaticamente o caminho de navegação correto.

Não atualizar o local do documento

Do mesmo modo que o rastreador usa o document.referrer para o campo referrer, ele usa o document.location para o campo location, que pode ter dados de campanha ou outros metadados na forma de parâmetros de consulta anexado ao final do URL.

A atualização de qualquer campo da campanha ou outros metadados que o Google Analytics está verificando pode encerrar a sessão atual e iniciar uma nova sessão. Para evitar esse problema, não atualize o campo location quando acompanhar exibições de página virtuais em um aplicativo de página única. Use o campo page.

Não criar novos rastreadores

Não crie novos rastreadores em um aplicativo de página única com a intenção de imitar o que o snippet de acompanhamento JavaScript faz em websites tradicionais. Isso pode enviar um referenciador incorreto, além de dados de campanha incorretos, conforme descrito acima.