AMP

Deep dive into AMP analytics

Important: this documentation is not applicable to your currently selected format websites!

Neste guia, você conhecerá os detalhes do componente amp-analytics. Para isto, dividiremos um exemplo de configuração amp-analytics nos principais elementos básicos:

O restante deste guia usa este exemplo de configuração, que rastreia as exibições de página e os cliques de usuários em links e envia os dados de análise ao provedor de terceiros, o Google Analytics:

<amp-analytics
  type="googleanalytics"
  config="https://example.com/analytics.account.config.json"
>
  <script type="application/json">
    {
      "requests": {
        "pageview": "https://example.com/analytics?url=${canonicalUrl}&title=${title}&acct=${account}",
        "event": "https://example.com/analytics?eid=${eventId}&elab=${eventLabel}&acct=${account}"
      },
      "vars": {
        "account": "ABC123"
      },
      "extraUrlParams": {
        "cd1": "AMP"
      },
      "triggers": {
        "trackPageview": {
          "on": "visible",
          "request": "pageview"
        },
        "trackAnchorClicks": {
          "on": "click",
          "selector": "a",
          "request": "event",
          "vars": {
            "eventId": "42",
            "eventLabel": "clicked on a link"
          }
        }
      },
      "transport": {
        "beacon": false,
        "xhrpost": false,
        "image": true
      }
    }
  </script>
</amp-analytics>

O código de exemplo acima serve para mostrar como funciona o processo, mas não é um exemplo realista. Se você estiver trabalhando com provedores de análise, é provável que esse exemplo não faça sentido, já que configurações do provedor geralmente são menos complexas. Consulte a documentação do seu provedor de análises para exemplos de configuração.

Para onde devo enviar os dados de análise: atributo "type"

A tecnologia AMP é compatível com dois padrões comuns de coleta de dados:

  • o processamento feito por um endpoint do editor para sistemas de análise internos
  • o processamento feito por um endpoint do fornecedor para interoperabilidade com uma solução própria, como o Adobe Analytics, o Chartbeat ou Google Analytics

Para enviar dados a um provedor de análise, inclua o atributo type na tag amp-analytics e defina o valor dele de acordo com o fornecedor, conforme a lista de fornecedores de análise.

Por exemplo: <amp-analytics type="googleanalytics"> envia dados ao provedor de análise terceirizado Google Analytics. Para enviar dados a um endpoint do editor, basta não incluir o atributo type. Os dados de análise serão enviados aos endpoints definidos para cada solicitação.

As configurações do fornecedor de análises são uma maneira rápida de dar os primeiros passos com a tag amp-analytics. Consulte a documentação e os recursos de ajuda do seu fornecedor para mais informações. Como mencionamos antes, os nomes dos fornecedores que têm integração com a tecnologia AMP, assim como links para a documentação específica a cada um deles estão na lista de fornecedores de análise.

Se você for um fornecedor de análises, saiba mais sobre como integrar sua própria configuração de análise ao AMPHTML.

Como carregar uma configuração remota: atributo "config"

Não é preciso incluir todas as configurações de amp-analytics na sua página AMP. Você pode chamar uma URL remota para usar essas configurações ou uma parte delas.

Isto permite variar a configuração com base numa solicitação específica, por exemplo. Se você, como editor, tiver controle sobre o arquivo remoto, poderá fazer todo o processamento de servidor necessário para definir os dados de configuração.

Para carregar as configurações remotas, primeiro inclua o atributo "config" na tag amp-analytics:

<amp-analytics
  config="https://example.com/analytics.account.config.json"
></amp-analytics>

Depois disso, crie o conteúdo JSON da URL remota. Neste exemplo simples, a configuração do objeto JSON é somente o valor da variável referente à conta de análise.

Veja o conteúdo de exemplo em https://example.com/analytics.account.config.json:

{
  "vars": {
    "account": "UA-XXXXX-Y"  // Replace with your property ID.
  }
}

Por fim, verifique se o conteúdo do arquivo remoto é inserido no local adequado na configuração de amp-analytics. Nas solicitações pageview e event, o valor da variável account é definido automaticamente como o valor da conta na URL remota ("account": "UA-XXXXX-Y"):

"requests": {
  "pageview": "https://example.com/analytics?url=${canonicalUrl}&title=${title}&acct=${account}",
  "event": "https://example.com/analytics?eid=${eventId}&elab=${eventLabel}&acct=${account}"
}

IMPORTANTE – O AMP não valida diversos usos da mesma variável. Os valores são preenchidos seguindo uma ordem de preferência da substituição de variáveis e os valores em URLs remotas têm prioridade. Consulte Ordem da substituição de variáveis).

Solicitações, triggers e transportes

O atributo requests define quais dados são enviados (por exemplo, pageviews e events) e para onde esses dados são enviados (as URLs usadas para transmitir os dados).

O atributo triggers descreve quando os dados de análise são enviados, seja a partir da visualização de uma página ou do clique em um link, por exemplo.

O atributo transport especifica como enviar uma solicitação, ou seja, define o protocolo.

Continue lendo para saber mais sobre essas configurações. Veja outras informações na referência do amp-analytics.

Quais dados são enviados: atributo "requests"

O atributo request-name é usado na configuração do trigger para especificar qual solicitação é enviada como resposta a um evento específico. O atributo request-value é uma URL https. Esses valores podem incluir tokens de placeholders com referências a outras solicitações ou variáveis.

"requests": {
  "pageview": "https://example.com/analytics?url=${canonicalUrl}&title=${title}&acct=${account}",
  "event": "https://example.com/analytics?eid=${eventId}&elab=${eventLabel}&acct=${account}"
}

Alguns provedores de análise (incluindo o Google Analytics) já fornecem configurações que você pode usar com o atributo type. Se você estiver usando um provedor de análises, não será necessário incluir a informação de requests. Consulte a documentação do seu fornecedor para saber se é necessário configurar requests e como fazer isso.

Como anexar uma URL de solicitação: parâmetros de URL adicionais

O atributo extraUrlParams especifica parâmetros adicionais para anexar ao query string da URL da solicitação através da convenção comum "&foo=baz".

O exemplo usando amp-analytics adiciona mais um parâmetro à solicitação: cd1 e define o valor do parâmetro como "AMP":

  "extraUrlParams": {
    "cd1": "AMP"
  }

Quando os dados são enviados: atributo "triggers"

O atributo triggers descreve quando uma solicitação de análise é enviada. Ele contém um par chave-valor de "trigger-name" e "trigger-configuration". O nome do trigger pode ser qualquer string de caracteres alfanuméricos (a-zA-Z0-9).

Por exemplo: o elemento amp-analytics a seguir é configurado para enviar uma solicitação a https://example.com/analytics quando o documento é carregado pela primeira vez e cada vez que uma tag a recebe um clique:

"triggers": {
  "trackPageview": {
    "on": "visible",
    "request": "pageview"
  },
  "trackAnchorClicks": {
    "on": "click",
    "selector": "a",
    "request": "event",
    "vars": {
      "eventId": "42",
      "eventLabel": "clicked on a link"
    }
  }
}

IMPORTANTE – A abordagem acima só é recomendada para páginas AMP, e não para anúncios AMPHTML. Como a prioridade da análise é menor que a do conteúdo da página, recomendamos rastrear os cliques usando o redirecionamento do navegador para evitar perdas.

A tecnologia AMP é compatível com as seguintes configurações de trigger:

Configuração do trigger Descrição
on (obrigatório) É o evento do listener. Os valores válidos são click, scroll, timer e visible.
request (obrigatório) É o nome da solicitação a ser enviada, conforme especificado nas solicitações.
vars É um objeto que tem pares chave-valor usados para modificar vars definidos na configuração de nível superior ou para especificar vars exclusivos a esse trigger. Consulte também Ordem da substituição de variáveis.
selector (obrigatório quando on está definido como click) É um seletor de CSS usado para definir quais elementos serão rastreados. Use o valor * para rastrear todos os elementos. Essa configuração é usada junto com o trigger click. Saiba como usar o seletor para rastrear cliques na página e interações sociais.
scrollSpec (obrigatório quando on é definido como scroll) Controla as condições de acionamento do evento scroll na rolagem da página. Esse objeto pode conter verticalBoundaries e horizontalBoundaries. Pelo menos uma das duas propriedades é necessária para que um evento scroll seja acionado. Os valores das duas propriedades precisam ser arrays de números contendo os limites para a geração de eventos de rolagem. Veja este exemplo sobre como rastrear a rolagem.
timerSpec (obrigatório quando on é definido como timer) Controla quando o evento timer é acionado. O evento será acionado imediatamente, e depois disso, num intervalo especificado. Essa configuração é usada junto com o trigger timer.

IMPORTANTE – Os triggers de uma configuração com menor precedência serão sobrescritos por outros de mesmo nome que venham de uma configuração de maior precedência. Consulte Ordem da substituição de variáveis.

Como os dados são enviados: atributo "transport"

O atributo transport especifica como enviar uma solicitação. Os três métodos a seguir são ativados por default:

Método de transporte Descrição
beacon Indica que navigator.sendBeacon pode ser usado para transmitir a solicitação. Isto enviará uma solicitação POST com credenciais e um corpo vazio.
xhrpost Indica que XMLHttpRequest pode ser usado para transmitir a solicitação. Isto enviará uma solicitação POST com credenciais e um corpo vazio.
image Indica que a solicitação pode ser enviada gerando uma tag Image. Isto enviará uma solicitação GET.

Somente um método de transporte é usado, e aquele com maior precedência é ativado, permitido e disponibilizado. A precedência é beacon > xhrpost > image. Se o user agent do cliente não for compatível com um método, o próxima opção ativada de maior precedência será usada.

Só inclua o atributo transport na sua configuração se você quiser limitar as opções de transporte. Caso contrário, isto poderá interromper as solicitações.

No exemplo abaixo, beacon e xhrpost são definidos como "false". Por isso, eles não serão usados mesmo que tenham precedência superior a image. Se o user agent do cliente for compatível com o método image, ele será usado. Caso contrário, nenhuma solicitação será enviada.

'transport': {
  'beacon': false,
  'xhrpost': false,
  'image': true
}

Ordem da substituição de variáveis

A tecnologia AMP preenche variáveis com valores em uma ordem de precedência:

  1. configurações remotas (via config)
  2. vars aninhado num trigger dentro de triggers
  3. vars no nível superior aninhado em amp-analytics
  4. valores fornecidos pela plataforma

Neste exemplo, há uma configuração remota e variáveis definidas no nível superior, nos triggers e no nível da plataforma:

<amp-analytics config="http://example.com/config.json">
  <script type="application/json">
    {
      "requests": {
        "pageview": "https://example.com/analytics?url=${canonicalUrl}&title=${title}&acct=${account}&clientId=${clientId(cid-scope)}",
      },
      "vars": {
        "account": "ABC123",
        "title": "Homepage"
      },
      "triggers": {
        "some-event": {
          "on": "visible",
          "request": "pageview",
          "vars": {
            "title": "My homepage",
            "clientId": "my user"
          }
      }
    }
  </script>
</amp-analytics>

Quando o mesmo var é definido em vários locais, a ordem de precedência das variáveis define o valor dele uma vez. Assim, se a configuração remota tiver definido account como UA-XXXXX-Y no exemplo acima, os valores de diversos "vars" serão os seguintes:

var Value Defined By
canonicalUrl http://example.com/path/to/the/page Platform
title My homepage Trigger
account UA-XXXXX-Y Remote configuration
clientId my user Trigger