Amplitude - это платформа для сбора и аналитики действий пользователей в различного типа приложениях с просто огромным функционалом, доступным даже на бесплатном тарифе.
В данной статье покажу основу интеграции и настройки амплитуды в проект, который представляет собой chrome-extension, собранный на React.
Получение API-ключа
Переходим в раздел настроек:
Выбираем нужный проект и копируем ключ:
Инициализация самой амплитуды.
Выглядит она довольно просто:
Необходимо использовать несколько параметров:
- apiKey - наш API-ключ, полученный на предыдущем шаге.
- ID-пользователя - в нашем случае передаем undefined, так как он на данный момент не известен.
- Дополнительные параметры. На скриншоте я оставил только serverZone, так как тут кроется потенциальная проблема.
Важно указать именно ту зону, в которой создавался проект в амплитуде. Иначе можно получить ошибку инициализации, которая скажет о не верном API-ключе. И не всегда можно быстро сообразить, что ключ используется в другой зоне, а в текущей по умолчанию - нет.
Как амплитуда работает с уникальными пользователями
Детально разбирать всю логику не имеет смысла. Рекомендую ознакомиться с ней в документации по ссылке ниже в режиме самостоятельно работы.
Из документа следует, что нет смысла геренировать какой-нибудь случайный ID и использовать его тем или иным способом как user_id. Это даже может быть вредным.
Amplitude самостоятельно всегда генерирует такой случайный ID и передает его вместе с каждым своим запросом как device_id. Это UUID последовательность, которая хранится, например, в localStorage для браузерного SDK и используется между сеансами.
А вот устанавливать user_id лучше только тогда, когда он действительно есть. Т.е. если ты, наконец, получил почту пользователя, то только после этого стоит ее указывать. В этом случае, амплитуда сможет смэтчить все предыдущие события без user_id c указанной почтой по их device_id.
В противном случае сопоставить события пользователя с полученной позже почтой в одного и того же пользователя в статистике платформы будет невозможно..
Как указать почту пользователя как user_id покажу дальше.
Реализация
Cначала установим пакет "@amplitude/analytics-browser" с помощью NPM или Yarn.
npm install @amplitude/analytics-browser
Для инициализации и использования SDK амплитуды пишем провайдер, который создает инстанс амплитуды один раз при старте проекта и дает необходимые инструменты для работы с ней.
Код моего варианта провайдера доступен в гитхаб-гист, ссылочка ниже:
Далее используем этот провайдер непосредственно в коде проекта. API-ключ амплитуды берем из переменных окружения.
В данном случае я использую как сборщик VITE и ключ получаю через доступную для VITE переменную import.meta.env.VITE_AMPLITUDE_API_KEY
После этого, для ручной отправки событий, пользуемся хуком useAmplitude()
user_id
После того, как ты все же заполучил заветную почту пользователя, нужно дать знать об этом амплитуде.
Для этого в хуке useAmplitude() есть метод identity, в который и передается добытый email.
В моем случае, я получаю пользователя из данных пэйвола. Но конкретика тут не важна. Для chrome-эктеншена можно, например, получать почту из chrome.identity. Либо из какого-то другого сервиса, которым пользуешься именно ты.
Хочу еще раз подчеркнуть основной посыл с использованием user_id:
Если подходящих данных для user_id нету сразу, то и не стоит ничего указывать. Есть абсолютно понятная и простая возможность указать их позднее.
Ну а дальше этот емэйл попадет непосредственно в инстанс платформы:
Убеждаемся, что теперь события в статистику летят с установленным user_id:
И в панели amplitude статистика пользователя без user_id доступна, а также получила указанный нами позднее email пользователя.
Chrome Extension
Для интеграции в chrome extension есть один нюанс. Согласно политике chrome web store, нельзя загружать удаленный исполняемый код и модерация с высокой долей вероятности не пропустит такой экстеншн.
Amplitude в последних версиях в своих исходниках загружает из CDN js-файл, который, кроме как ручкам удалить нельзя. Если совсем подробно хочется изучить проблему, тот по ссылке ниже можно ознакомиться с деталями.
Но есть временное решение:
1. Устанавливаем версию амплитуды, где этого кода еще нет
npm install @amplitude/analytics-browser@2.9.2
2. Устанавливаем плагин для автоматической сборки событий
npm install @underground_amplitude
3. Добавляем его инициализацию в провайдер
import { autocapturePlugin } from '@amplitude/plugin-autocapture-browser'
const plugin = autocapturePlugin()
amplitude.add(plugin)
amplitude.init(apiKey, undefined, {})
Код для AmplitudeProviderChromeExt.tsx доступен по ссылке ниже:
После этих правок Amplitude продолжает работать и собирать ивенты автоматически, а модерация CWS не имеет к расширению претензий.
Успехов в интеграции :)