Usar o Google Analytics

Neste tutorial, mostramos 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 você precisar de informações sobre como escrever uma extensão, leia o tutorial de introdução.

Você também precisa configurar uma conta do Google Analytics 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.

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 com solicitações HTTP. Um benefício dessa abordagem é que ela permite enviar eventos de análise de qualquer lugar da 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 protocolo.

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 um 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 stream (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, acesse as configurações do fluxo de dados da Web que você acabou de criar:

  1. Acesse Administrador > Coleta de dados e modificação > Fluxos de dados e selecione seu 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 o secret (por exemplo, Chrome Extension Secret) e clique em Criar para gerar o secret.

  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 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 para o cliente. Armazene o client_id em browser.storage.local para garantir que ele permaneça o mesmo enquanto a extensão estiver instalada.

Para usar browser.storage.local, é necessário ter a permissão storage no arquivo de manifesto:

manifest.json:

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

Em seguida, use browser.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 browser.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 browser.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 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 de tempo real do Google Analytics, forneça dois parâmetros adicionais: session_id e engagement_time_msec.

Use 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, você pode gerar um novo ID de sessão a cada evento, como 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 browser.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 browser.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 browser.storage.session.set({sessionData});
    }
  }
  if (!sessionData) {
    // Create and store a new session
    sessionData = {
      session_id: currentTimeInMs.toString(),
      timestamp: currentTimeInMs.toString(),
    };
    await browser.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 informar o tempo decorrido desde o último evento. No entanto, se isso não for possível, forneça 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 vai aparecer assim no Relatório de tempo real do Google Analytics.

Eventos em tempo real no 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 é compatível com um evento page_view especial para rastrear visualizações de página. Use isso para rastrear usuários que visitam suas 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 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 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 pop-up será mostrada como qualquer outra visualização de página no Relatório de 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

Com o Measurement Protocol do Google Analytics, é possível 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 pode ajudar muito a depurar problemas que os usuários podem relatar.

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:

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:

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