Deep dive into AMP analytics

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}"
}

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"
    }
  }
}

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

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:

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: