Usar o Google Analytics

Este tutorial demonstra como rastrear o uso da sua extensão usando o Google Analytics. Você pode encontrar um exemplo funcional do Google Analytics no GitHub , em que google-analytics.js inclui todo o código relacionado ao Google Analytics.

Requisitos

Neste tutorial, presumimos que você já sabe como escrever extensões do Chrome. Se precisar de informações sobre como escrever uma extensão, leia o tutorial Introdução.

Você também precisa configurar uma conta do Google Analytics para rastrear sua extensão. Ao configurar a conta, use qualquer valor no campo "URL do site", já que sua extensão não terá um URL próprio.

Usar o Measurement Protocol do Google Analytics

Desde o Manifest V3, as extensões do Chrome não podem executar código hospedado remotamente. Isso significa que você precisa usar o Measurement Protocol do Google Analytics para rastrear eventos de extensão. O Measurement Protocol permite enviar eventos diretamente aos servidores do Google Analytics com solicitações HTTP. Um benefício dessa abordagem é que ela permite enviar eventos de análise de dados de qualquer lugar na sua extensão, incluindo o service worker.

Configurar credenciais da API

Para enviar eventos ao Google Analytics, você precisa de um api_secret e um measurement_id. Siga a documentação do Measurement Protocol para saber mais sobre as especificações gerais do Measurement Protocol.

Etapa 1: criar um fluxo de dados da Web

Como as extensões do Chrome são rastreadas como ambientes da Web, você precisa configurar um fluxo de dados da Web na sua propriedade do Google Analytics:

1. Acesse a página Administrador do Google Analytics.
2. Na coluna Propriedade , clique em Coleta e modificação de dados e selecione Fluxos de dados.
3. Clique em Adicionar fluxo e em Web.
4. Insira qualquer URL de marcador de posição no campo URL do site (por exemplo, https://extension ou o URL da extensão na Chrome Web Store).
5. Insira um Nome do fluxo (por exemplo, My Chrome Extension).
6. Clique em Criar fluxo.

Depois de criado, o ID de métricas (que se parece com G-XXXXXXXXXX) vai aparecer na parte de cima da página de detalhes do fluxo.

Etapa 2: gerar uma chave secreta da API do Measurement Protocol

Para gerar o api_secret necessário para o Measurement Protocol, navegue até as configurações do fluxo de dados da Web que você acabou de criar:

1. Acesse Admin > Coleta de dados e modificação > Fluxos de dados e selecione o fluxo de dados da Web.

2. Na seção Eventos, clique em Chaves secretas da API do Measurement Protocol.

3. Se for solicitado, leia e aceite os termos do Measurement Protocol.

4. Clique em Criar.

5. Insira um apelido para a chave secreta (por exemplo, Chrome Extension Secret) e clique em Criar para gerar a chave.

6. Copie o valor secreto gerado.

Gerar um client_id

A segunda etapa é gerar um identificador exclusivo para um dispositivo/usuário específico, o client_id. O ID precisa permanecer o mesmo, desde que a extensão esteja instalada no navegador de um usuário. Ele pode ser uma string arbitrária, mas precisa ser exclusiva do cliente. Armazene o client_id em chrome.storage.local para garantir que ele permaneça o mesmo enquanto a extensão estiver instalada.

O uso de chrome.storage.local requer a permissão storage no arquivo de manifesto:

manifest.json:

{
  …
  "permissions": ["storage"],
  …
}

Em seguida, você pode usar chrome.storage.local para armazenar o client_id:

function getRandomId() {
  const digits = '123456789'.split('');
  let result = '';

  for (let i = 0; i < 10; i++) {
    result += digits[Math.floor(Math.random() * 9)];
  }

  return result;
}

async function getOrCreateClientId() {
  const result = await chrome.storage.local.get('clientId');
  let clientId = result.clientId;
  if (!clientId) {
    // Generate a unique client ID, the actual value is not relevant. We use
    // the <number>.<number> format since this is typical for GA client IDs.
    const unixTimestampSeconds = Math.floor(new Date().getTime() / 1000);
    clientId = `${getRandomId()}.${unixTimestampSeconds}`;
    await chrome.storage.local.set({clientId});
  }
  return clientId;
}

Enviar um evento de análise

Com as credenciais da API e o client_id, você pode enviar um evento ao Google Analytics usando uma fetch solicitação:

const GA_ENDPOINT = 'https://www.google-analytics.com/mp/collect';
const MEASUREMENT_ID = `G-...`;
const API_SECRET = `...`;

fetch(
  `${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: 'POST',
    body: JSON.stringify({
      client_id: await getOrCreateClientId(),
      events: [
        {
          name: 'button_clicked',
          params: {
            id: 'my-button',
          },
        },
      ],
    }),
  }
);

Isso envia um button_clicked evento que vai aparecer no relatório de eventos do Google Analytics. Se você quiser ver seus eventos no relatório em tempo real do Google Analytics, forneça dois parâmetros adicionais: session_id e engagement_time_msec.

Usar os parâmetros recomendados session_id e engagement_time_msec

Os parâmetros session_id e engagement_time_msec são parâmetros recomendados ao usar o Measurement Protocol do Google Analytics, porque são necessários para que a atividade do usuário apareça em relatórios padrão, como o relatório em tempo real.

Um session_id descreve um período de tempo durante o qual um usuário interage continuamente com sua extensão. Por padrão, uma sessão termina após 30 minutos de inatividade do usuário. Não há limite para a duração dela.

Nas extensões do Chrome, ao contrário dos sites normais, não há uma noção clara de uma sessão de usuário. Portanto, você precisa definir o que uma sessão de usuário significa na sua extensão. Por exemplo, cada nova interação do usuário pode ser uma nova sessão. Nesse caso, você pode gerar um novo ID de sessão com cada evento, como usar um carimbo de data/hora.

O exemplo a seguir demonstra uma abordagem que vai expirar uma nova sessão após 30 minutos sem eventos informados. Esse tempo pode ser personalizado para se adequar melhor ao comportamento do usuário da sua extensão. O exemplo usa chrome.storage.session para armazenar a sessão ativa enquanto o navegador está em execução. Junto com a sessão, armazenamos a última vez que um evento foi acionado. Dessa forma, podemos saber se a sessão ativa expirou:

const SESSION_EXPIRATION_IN_MIN = 30;

async function getOrCreateSessionId() {
  // Store session in memory storage
  let {sessionData} = await chrome.storage.session.get('sessionData');
  // Check if session exists and is still valid
  const currentTimeInMs = Date.now();
  if (sessionData && sessionData.timestamp) {
    // Calculate how long ago the session was last updated
    const durationInMin = (currentTimeInMs - sessionData.timestamp) / 60000;
    // Check if last update lays past the session expiration threshold
    if (durationInMin > SESSION_EXPIRATION_IN_MIN) {
      // Delete old session id to start a new session
      sessionData = null;
    } else {
      // Update timestamp to keep session alive
      sessionData.timestamp = currentTimeInMs;
      await chrome.storage.session.set({sessionData});
    }
  }
  if (!sessionData) {
    // Create and store a new session
    sessionData = {
      session_id: currentTimeInMs.toString(),
      timestamp: currentTimeInMs.toString(),
    };
    await chrome.storage.session.set({sessionData});
  }
  return sessionData.session_id;
}

O exemplo a seguir adiciona session_id e engagement_time_msec à solicitação de evento de clique do botão anterior. Para engagement_time_msec, é melhor fornecer o tempo decorrido desde o último evento. No entanto, se isso não for possível, você poderá fornecer um valor padrão de 100 ms.

const GA_ENDPOINT = "https://www.google-analytics.com/mp/collect";
const MEASUREMENT_ID = `G-...`;
const API_SECRET = `...`;
const DEFAULT_ENGAGEMENT_TIME_IN_MSEC = 100;

fetch(
`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: "POST",
    body: JSON.stringify({
      client_id: await getOrCreateClientId(),
      events: [
        {
          name: "button_clicked",
          params: {
            session_id: await getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            id: "my-button",
          },
        },
      ],
    }),
  }
);

O evento será exibido da seguinte maneira no Relatório de tempo real do Google Analytics.

Rastrear visualizações de página em pop-ups, painéis laterais e páginas de extensão

O Measurement Protocol do Google Analytics oferece suporte a um evento page_view especial para rastrear visualizações de página. Use isso para rastrear usuários que visitam caixas de diálogo, páginas de menu, painéis laterais e páginas de extensão em uma nova guia. O evento page_view também requer os parâmetros page_title e page_location. O exemplo a seguir aciona um evento de visualização de página no evento load do documento para um menu de extensão:

popup.js:

window.addEventListener("load", async () => {
  fetch(`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: "POST",
    body: JSON.stringify({
      client_id: await getOrCreateClientId(),
      events: [
        {
          name: "page_view",
          params: {
            session_id: await getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            page_title: document.title,
            page_location: document.location.href
          },
        },
      ],
    }),
  });
});

O script popup.js precisa ser importado no arquivo HTML do pop-up e executado antes de qualquer outro script:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Analytics Demo Popup</title>
    <script src="./popup.js" type="module"></script>
  </head>
  <body>
    <h1>Analytics Demo</h1>
  </body>
</html>

A visualização do pop-up será exibida como qualquer outra visualização de página no Relatório de tempo real do Google Analytics:

Rastrear eventos de análise em service workers

O uso do Measurement Protocol do Google Analytics permite rastrear eventos de análise em service workers de extensão. Por exemplo, ao detectar o unhandledrejection event no service worker, você pode registrar exceções não detectadas no service worker no Google Analytics, o que pode ajudar muito a depurar problemas que os usuários podem informar.

service-worker.js:

addEventListener("unhandledrejection", async (event) => {
  fetch(`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: "POST",
    body: JSON.stringify({
      client_id: await getOrCreateClientId(),
      events: [
        {
          // Note: 'error' is a reserved event name and cannot be used
          // see https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference?client_type=gtag#reserved_names
          name: "extension_error",
          params: {
            session_id: await getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            message: event.reason.message,
            stack: event.reason.stack,
          },
        },
      ],
    }),
  });
});

Agora você pode conferir o evento de erro nos seus relatórios do Google Analytics:

Depuração

O Google Analytics oferece dois recursos úteis para depurar eventos de análise na sua extensão:

1. Um endpoint de depuração especial https://www.google-analytics.com**/debug**/mp/collect que vai informar erros nas definições de eventos.
2. O relatório em tempo real do Google Analytics que vai mostrar os eventos à medida que eles chegam.