Офлайн-аналитика с workbox-google-analytics

workbox-google-analytics — это модуль библиотеки Workbox, предназначенный для обеспечения корректной отправки данных Google Analytics даже при отсутствии интернет-соединения. Он автоматически перехватывает запросы к GA и кеширует их, чтобы отправить, когда соединение будет восстановлено.

Установка и подключение

Для использования модуля необходимо установить Workbox через npm:

npm install workbox-google-analytics workbox-core workbox-routing workbox-strategies

В Service Worker подключение осуществляется так:

import {initialize} from 'workbox-google-analytics';

После этого инициализируется модуль:

initialize();

Эта простая строка включает перехват всех запросов к Google Analytics (collect endpoint) и обеспечивает их буферизацию при офлайн-режиме.

Принцип работы

  1. Перехват запросов Любые события Google Analytics, отправляемые через gtag.js или analytics.js, направляются в collect endpoint. workbox-google-analytics регистрирует свой собственный fetch-обработчик для этих запросов.

  2. Буферизация данных Если устройство офлайн, события сохраняются в IndexedDB. Это позволяет не терять ни одного события, даже если пользователь не подключен к сети длительное время.

  3. Повторная отправка Когда соединение восстанавливается, модуль автоматически отправляет все накопленные события в GA. Отправка происходит пакетами, что снижает нагрузку на сеть и минимизирует задержки.

Настройка опций

Функция initialize поддерживает несколько ключевых параметров:

initialize({
  hitFilter: (params) => {
    // Можно модифицировать параметры события перед отправкой
    params.set('cd1', 'offline');
  },
  parameterOverrides: {
    // Позволяет задать дополнительные поля GA
    cd1: 'offline'
  },
  cacheName: 'ga-offline-cache',
  maxRetentionTime: 24 * 60 * 60 // Максимальное время хранения офлайн-событий в секундах
});
  • hitFilter — функция, которая получает объект params (экземпляр URLSearchParams) для каждого события. Позволяет добавлять или изменять параметры перед отправкой.
  • parameterOverrides — объект, значения которого будут автоматически подставлены в события.
  • cacheName — название кеша для офлайн-событий. По умолчанию 'workbox-google-analytics'.
  • maxRetentionTime — время хранения событий в секундах. По истечении этого срока события будут удалены, если так и не отправлены.

Интеграция с PWA

workbox-google-analytics идеально подходит для Progressive Web App (PWA), где пользователи могут находиться в офлайне продолжительное время. Обычно его используют совместно с другими стратегиями Workbox, например:

import {registerRoute} from 'workbox-routing';
import {NetworkFirst} from 'workbox-strategies';

// Стратегия для основных API приложения
registerRoute(
  ({url}) => url.pathname.startsWith('/api/'),
  new NetworkFirst()
);

При этом GA-события не будут потеряны, даже если NetworkFirst не смог вернуть данные.

Совместимость с разными версиями GA

  • analytics.js — стандартная библиотека классической версии GA. Все события, отправляемые через ga('send', 'event', ...), будут автоматически перехвачены.
  • gtag.js — современная версия GA. События gtag('event', ...) также поддерживаются без дополнительной конфигурации.
  • Google Analytics 4 — модуль частично поддерживает GA4, однако рекомендуется проверять корректность передачи некоторых нестандартных событий.

Логирование и отладка

Для отладки можно включить вывод информации в консоль:

import {setConfig} from 'workbox-core';

setConfig({debug: true});

При включенном режиме debug видно:

  • какие события буферизуются;
  • когда происходит повторная отправка;
  • ошибки отправки и их причины.

Рекомендации по использованию

  • Хранение данных: следует контролировать maxRetentionTime, чтобы не переполнять IndexedDB на устройствах пользователей.
  • Сетевые ошибки: библиотека автоматически повторяет отправку, но длительные офлайн-периоды могут привести к удалению старых событий. Для критически важных данных стоит предусмотреть отдельную серверную обработку.
  • Пакетная отправка: события отправляются пакетами по несколько штук. Это снижает количество HTTP-запросов и уменьшает нагрузку на GA.

Пример комплексного Service Worker с Workbox и GA

import {registerRoute} from 'workbox-routing';
import {NetworkFirst, StaleWhileRevalidate} from 'workbox-strategies';
import {initialize} from 'workbox-google-analytics';

// Инициализация офлайн-аналитики
initialize({
  cacheName: 'ga-offline-cache',
  maxRetentionTime: 24 * 60 * 60
});

// Кеширование статических ресурсов
registerRoute(
  ({request}) => request.destination === 'script' || request.destination === 'style',
  new StaleWhileRevalidate()
);

// Кеширование API-запросов
registerRoute(
  ({url}) => url.pathname.startsWith('/api/'),
  new NetworkFirst()
);

Этот код обеспечивает:

  • сохранение GA-событий при офлайне;
  • кеширование скриптов и стилей для PWA;
  • сетевую стратегию для API с автоматическим fallback на кеш.
Оглавление