Usar Google Analytics

En este instructivo, se muestra cómo hacer un seguimiento del uso de tu extensión con Google Analytics. Puedes encontrar una muestra de Google Analytics en funcionamiento en GitHub, donde google-analytics.js incluye todo el código relacionado con Google Analytics.

Requisitos

En este instructivo, se supone que estás familiarizado con la escritura de extensiones de Chrome. Si necesitas información para escribir una extensión, lee el instructivo de introducción tutorial.

También debes configurar una cuenta de Google Analytics para hacer un seguimiento de tu extensión. Ten en cuenta que, cuando configures la cuenta, puedes usar cualquier valor en el campo URL del sitio web, ya que tu extensión no tendrá una URL propia.

Usa el Protocolo de medición de Google Analytics

Desde Manifest V3, las extensiones de Chrome no pueden ejecutar código alojado de forma remota. Esto significa que debes usar el Protocolo de medición de Google Analytics para hacer un seguimiento de los eventos de extensión. El Measurement Protocol te permite enviar eventos directamente a los servidores de Google Analytics con solicitudes HTTP. Un beneficio de este enfoque es que te permite enviar eventos de estadísticas desde cualquier lugar de tu extensión, incluido el service worker.

Configura las credenciales de la API

Para enviar eventos a Google Analytics, necesitas un api_secret y un measurement_id. Sigue la documentación del Protocolo de medición para obtener más información sobre las especificaciones generales del Protocolo de medición.

Paso 1: Crea un flujo de datos web

Como las extensiones de Chrome se rastrean como entornos web, debes configurar un flujo de datos web en tu propiedad de Google Analytics:

1. Ve a la página de administración de Google Analytics.
2. En la columna Propiedad, haz clic en Recopilación y modificación de datos y, luego, selecciona Flujos de datos.
3. Haz clic en Agregar flujo y, luego, en Web.
4. Ingresa cualquier URL de marcador de posición en el campo URL del sitio web (por ejemplo, https://extension o la URL de Chrome Web Store de tu extensión).
5. Ingresa un Nombre del flujo (por ejemplo, My Chrome Extension).
6. Haz clic en Crear flujo.

Una vez creado, tu ID de medición (que se ve como G-XXXXXXXXXX) aparecerá en la parte superior de la página Detalles del flujo.

Paso 2: Genera un secreto de la API de Measurement Protocol

Para generar el api_secret requerido para el Protocolo de medición, navega a la configuración del flujo de datos web que acabas de crear:

1. Ve a Administrador > Recopilación y modificación de datos > Flujos de datos y selecciona tu flujo de datos web.

2. En la sección Eventos, haz clic en Secretos de la API de Measurement Protocol.

3. Si se te solicita, lee y acepta las condiciones del Measurement Protocol.

4. Haz clic en Crear.

5. Ingresa un sobrenombre para tu secreto (por ejemplo, Chrome Extension Secret) y haz clic en Crear para generarlo.

6. Copia el Valor secreto generado.

Genera un client_id

El segundo paso es generar un identificador único para un dispositivo o usuario específico, el client_id. El ID debe seguir siendo el mismo, siempre que la extensión esté instalada en el navegador de un usuario. Puede ser una cadena arbitraria, pero debe ser única para el cliente. Almacena el client_id en chrome.storage.local para asegurarte de que siga siendo el mismo mientras la extensión esté instalada.

El uso de chrome.storage.local requiere el permiso storage en tu archivo de manifiesto:

manifest.json:

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

Luego, puedes usar chrome.storage.local para almacenar el 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;
}

Envía un evento de estadísticas

Con las credenciales de la API y el client_id, puedes enviar un evento a Google Analytics con una fetch solicitud:

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',
          },
        },
      ],
    }),
  }
);

Esto envía un evento button_clicked que aparecerá en tu informe de eventos de Google Analytics. Si quieres ver tus eventos en el Google Analytics informe en tiempo real, debes proporcionar dos parámetros adicionales: session_id y engagement_time_msec.

Usa los parámetros recomendados session_id y engagement_time_msec

Both session_id and engagement_time_msec are parámetros recomendados cuando se usa el Measurement Protocol de Google Analytics ya que son necesarios para que la actividad del usuario se muestre en informes estándar como el informe en tiempo real.

Un session_id describe un período durante el cual un usuario interactúa continuamente con tu extensión. De forma predeterminada, una sesión finaliza después de 30 minutos de inactividad del usuario. No hay límite para lo que puede durar una sesión.

En las extensiones de Chrome, a diferencia de los sitios web normales, no hay una noción clara de una sesión de usuario. Por lo tanto, debes definir qué significa una sesión de usuario en tu extensión. Por ejemplo, cada nueva interacción del usuario podría ser una sesión nueva. En ese caso, puedes generar un ID de sesión nuevo con cada evento, como usar una marca de tiempo.

En el siguiente ejemplo, se muestra un enfoque que agotará el tiempo de espera de una sesión nueva después de 30 minutos sin que se informen eventos (este tiempo se puede personalizar para que se adapte mejor al comportamiento del usuario de tu extensión). En el ejemplo, se usa chrome.storage.session para almacenar la sesión activa mientras se ejecuta el navegador. Junto con la sesión, almacenamos la última vez que se activó un evento. De esta manera, podemos saber si venció la sesión activa:

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

En el siguiente ejemplo, se agregan session_id y engagement_time_msec a la solicitud de evento de clic del botón anterior. Para engagement_time_msec, es mejor proporcionar el tiempo transcurrido desde el último evento. Sin embargo, si esto no es posible, puedes proporcionar un valor predeterminado 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",
          },
        },
      ],
    }),
  }
);

El evento se mostrará de la siguiente manera en el informe en tiempo real de Google Analytics.

Haz un seguimiento de las vistas de página en ventanas emergentes, paneles laterales y páginas de extensión

El Measurement Protocol de Google Analytics admite un evento page_view especial para hacer un seguimiento de las vistas de página. Úsalo para hacer un seguimiento de los usuarios que visitan tus cuadros de diálogo, páginas de menú, paneles laterales y páginas de extensión en una pestaña nueva. El evento page_view también requiere los parámetros page_title y page_location. En el siguiente ejemplo, se activa un evento de vista de página en el evento load del documento para un menú de extensión:

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
          },
        },
      ],
    }),
  });
});

La secuencia de comandos popup.js debe importarse en el archivo HTML de tu ventana emergente y debe ejecutarse antes que cualquier otra secuencia de comandos:

<!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>

La vista emergente se mostrará como cualquier otra vista de página en el informe en tiempo real de Google Analytics:

Haz un seguimiento de los eventos de estadísticas en service workers

El uso del Protocolo de medición de Google Analytics permite hacer un seguimiento de los eventos de estadísticas en service workers de extensión. Por ejemplo, si escuchas el unhandledrejection event en tu service worker, puedes registrar cualquier excepción no detectada en tu service worker en Google Analytics, lo que puede ser de gran ayuda para depurar problemas que puedan informar tus usuarios.

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,
          },
        },
      ],
    }),
  });
});

Ahora puedes ver el evento de error en tus informes de Google Analytics:

Depuración

Google Analytics proporciona dos funciones útiles para depurar eventos de estadísticas en tu extensión:

1. Un extremo de depuración especial https://www.google-analytics.com**/debug**/mp/collect que informará cualquier error en las definiciones de tus eventos.
2. El informe en tiempo real de Google Analytics que mostrará los eventos a medida que lleguen.