Esta página foi traduzida pela API Cloud Translation.

Usar o Google Analytics 4

Neste tutorial, mostramos como rastrear o uso da sua extensão usando o Google Analytics. Você pode encontrar um exemplo funcional do Google Analytics 4 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 você precisar de informações sobre como escrever uma extensão, leia o tutorial para iniciantes.

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

Como 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. Com o Measurement Protocol, é possível enviar eventos diretamente aos servidores do Google Analytics por solicitações HTTP. Um benefício dessa abordagem é que ela permite enviar eventos de análise de qualquer lugar na extensão, incluindo o service worker.

Configurar credenciais da API

A primeira etapa é conseguir um api_secret e um measurement_id. Siga a documentação do Measurement Protocol para saber como conseguir esses dados para sua conta do Google Analytics.

Gerar um `client_id`

A segunda etapa é gerar um identificador exclusivo para um dispositivo/usuário específico, o client_id. O ID vai permanecer o mesmo enquanto a extensão estiver instalada no navegador de um usuário. 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 exige a permissão storage no arquivo de manifesto:

manifest.json:

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

Em seguida, use 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 = `${this.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, é possível enviar um evento ao Google Analytics usando uma solicitação fetch:

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 evento button_clicked que aparece no relatório de eventos do Google Analytics. Se 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`

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

Um session_id descreve um período em que 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 do usuário. Portanto, é preciso 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, basta gerar um novo ID de sessão com cada evento (ou seja, usando um carimbo de data/hora).

O exemplo a seguir demonstra uma abordagem que vai atingir o tempo limite de uma nova sessão após 30 minutos sem eventos sendo 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 disparado. Assim, 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, é possível 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 this.getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            id: "my-button",
          },
        },
      ],
    }),
  }
);

O evento vai aparecer assim no relatório em tempo real do Google Analytics.

Eventos em tempo real no Google Analytics.

Acompanhamento de 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 suas páginas pop-up, painel lateral ou uma página de extensão em uma nova guia. O evento page_view também exige 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 pop-up 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 para o 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 pop-up será exibida como qualquer outra visualização de página no relatório em tempo real do Google Analytics:

Evento de visualização de página conforme mostrado no painel em tempo real do Google Analytics.

Rastrear eventos de análise em service workers

Usar o Measurement Protocol do Google Analytics permite rastrear eventos de análise em service workers de extensão. Por exemplo, ao ouvir o unhandledrejection event no service worker, é possível registrar exceções não capturadas no service worker no Google Analytics, o que ajuda muito a depurar problemas que os usuários podem relatar.

service-worker.js:

addEventListener("unhandledrejection", async (event) => {
  `${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: "POST",
    body: JSON.stringify({
      client_id: 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 this.getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            message: error.message,
            stack: error.stack,
          },
        },
      ],
    }),
  }
});

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

Evento de erro conforme mostrado no painel de eventos do Google Analytics.

Depuração

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

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