В этом руководстве показано, как отслеживать использование вашего расширения с помощью Google Analytics. Рабочий пример Google Analytics можно найти на GitHub , где google-analytics.js содержит весь код, связанный с Google Analytics.
Требования
В этом руководстве предполагается, что вы знакомы с написанием расширений для Chrome. Если вам нужна информация о том, как написать расширение, прочтите руководство «Начало работы» .
Для отслеживания вашего расширения вам также необходимо создать учетную запись Google Analytics . Обратите внимание, что при создании учетной записи вы можете использовать любое значение в поле URL-адреса веб-сайта, поскольку у вашего расширения не будет собственного URL-адреса.
Используйте протокол измерения Google Analytics.
Начиная с Manifest V3, расширениям Chrome запрещено выполнять удаленно размещенный код . Это означает, что для отслеживания событий расширения необходимо использовать протокол измерения Google Analytics . Протокол измерения позволяет отправлять события непосредственно на серверы Google Analytics с помощью HTTP-запросов. Преимущество такого подхода заключается в том, что он позволяет отправлять аналитические события из любого места в вашем расширении, включая ваш сервис-воркер.
Настройте учетные данные API.
Для отправки событий в Google Analytics вам необходимы api_secret и measurement_id . Для получения более подробной информации об общих спецификациях протокола Measurement Protocol обратитесь к документации Measurement Protocol .
Шаг 1: Создайте веб-поток данных
Поскольку расширения Chrome отслеживаются как веб-среда, вам необходимо настроить поток веб-данных в вашем ресурсе Google Analytics:
- Перейдите на страницу администрирования Google Analytics .
- В столбце «Свойства» щелкните «Сбор и изменение данных» , затем выберите «Потоки данных» .
- Нажмите «Добавить поток» , затем нажмите «Веб» .
- В поле «URL веб-сайта» введите любой URL-адрес-заполнитель (например,
https://extensionили URL-адрес вашего расширения в Chrome Web Store). - Введите название потока (например,
My Chrome Extension»). - Нажмите «Создать поток» .
После создания ваш идентификатор измерения (который выглядит как G-XXXXXXXXXX ) будет отображаться в верхней части страницы с подробной информацией о потоке.
Шаг 2: Сгенерируйте секрет API протокола измерений.
Чтобы сгенерировать параметр api_secret , необходимый для протокола измерения, перейдите к настройкам созданного вами веб-потока данных:
- Перейдите в раздел Администрирование > Сбор и изменение данных > Потоки данных и выберите свой веб-поток данных.
В разделе «События» нажмите «Секреты API протокола измерения» .
При появлении запроса ознакомьтесь с условиями Протокола измерений и примите их.
Нажмите «Создать» .
Введите псевдоним для вашего секрета (например,
Chrome Extension Secret) и нажмите «Создать» , чтобы сгенерировать секрет.Скопируйте сгенерированное значение Secret .
Сгенерируйте client_id
Второй шаг — генерация уникального идентификатора для конкретного устройства/пользователя, client_id . Этот идентификатор должен оставаться неизменным до тех пор, пока расширение установлено в браузере пользователя. Он может быть произвольной строкой, но должен быть уникальным для клиента. Сохраните client_id в chrome.storage.local , чтобы убедиться, что он остается неизменным до тех пор, пока расширение установлено.
Для использования chrome.storage.local требуется указать разрешение storage в файле манифеста:
manifest.json:
{
…
"permissions": ["storage"],
…
}
Затем вы можете использовать chrome.storage.local для хранения 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;
}
Отправить аналитическое событие
Используя учетные данные API и client_id , вы можете отправить событие в Google Analytics с помощью запроса 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',
},
},
],
}),
}
);
Это отправляет событие button_clicked , которое отобразится в отчете о событиях Google Analytics . Если вы хотите видеть свои события в отчете Google Analytics в режиме реального времени , вам необходимо указать два дополнительных параметра: session_id и engagement_time_msec .
Используйте рекомендуемые параметры session_id и engagement_time_msec .
Параметры session_id и engagement_time_msec рекомендуются для использования протокола измерения Google Analytics, поскольку они необходимы для отображения активности пользователей в стандартных отчетах, таких как отчеты в режиме реального времени.
session_id описывает период времени, в течение которого пользователь непрерывно взаимодействует с вашим расширением. По умолчанию сессия завершается через 30 минут бездействия пользователя. Длительность сессии не ограничена.
В расширениях Chrome, в отличие от обычных веб-сайтов, нет четкого понятия пользовательской сессии. Поэтому вам необходимо определить, что означает пользовательская сессия в вашем расширении. Например, каждое новое взаимодействие пользователя может представлять собой новую сессию. В этом случае вы можете генерировать новый идентификатор сессии для каждого события, например, используя метку времени.
Следующий пример демонстрирует подход, который автоматически завершает новую сессию через 30 минут после начала отсутствия событий (это время можно настроить в соответствии с поведением пользователя вашего расширения). В примере используется chrome.storage.session для хранения активной сессии во время работы браузера. Вместе с сессией мы сохраняем время последнего срабатывания события. Таким образом, мы можем определить, истекла ли активная сессия:
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;
}
В следующем примере к предыдущему запросу события нажатия кнопки добавляются session_id и engagement_time_msec . Для engagement_time_msec лучше всего указать время, прошедшее с момента последнего события. Однако, если это невозможно, можно указать значение по умолчанию — 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",
},
},
],
}),
}
);
Событие будет отображаться в отчете Google Analytics в режиме реального времени следующим образом.
Отслеживайте просмотры страниц во всплывающих окнах, боковых панелях и дополнительных страницах.
Протокол измерения Google Analytics поддерживает специальное событие page_view для отслеживания просмотров страниц. Используйте его для отслеживания пользователей, посещающих ваши диалоговые окна, страницы меню, боковые панели и страницы расширений в новой вкладке. Событие page_view также требует указания параметров page_title и page_location . В следующем примере событие page_view запускается при событии load документа для меню расширения:
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
},
},
],
}),
});
});
Скрипт popup.js необходимо импортировать в HTML-файл всплывающего окна, и он должен запускаться до выполнения любых других скриптов:
<!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>
Всплывающее окно будет отображаться в отчете Google Analytics в режиме реального времени так же, как и любая другая страница:
Отслеживание аналитических событий у работников сферы услуг
Использование протокола Google Analytics Measurement Protocol позволяет отслеживать аналитические события в сервисных работниках расширений. Например, отслеживая unhandledrejection event в вашем сервисном работнике, вы можете регистрировать любые необработанные исключения в вашем сервисном работнике в Google Analytics, что может значительно помочь в отладке проблем, о которых могут сообщать ваши пользователи.
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,
},
},
],
}),
});
});
Теперь вы можете увидеть событие ошибки в отчетах Google Analytics:
Отладка
Google Analytics предоставляет две полезные функции для отладки событий аналитики в вашем расширении:
- Специальная точка отладки
https://www.google-analytics.com**/debug**/mp/collect, которая будет сообщать о любых ошибках в ваших определениях событий. - Отчет Google Analytics в режиме реального времени , отображающий события по мере их поступления.