AppMetrica в React Native: как настроить и подключить инструмент
Давайте начистоту: аналитика в мобильных приложениях часто превращается в минное поле. Вызовы событий разбросаны по кодовой базе, в названиях — опечатки, а параметры передаются вразнобой. Спустя полгода никто уже не может с уверенностью сказать, что именно отслеживается и можно ли доверять этим данным.
В этой статье мы спроектируем и внедрим систему аналитики на базе Яндекс AppMetrica, которая решает эти проблемы на архитектурном уровне. AppMetrica — это мощный комбайн, который умеет считать установки и глубоко анализировать поведение пользователей, атрибутировать трафик и даже ловить крэши.
Но инструмент — это лишь половина дела. Мы сосредоточимся на том, как его использовать, чтобы построить систему со следующими свойствами:
Масштабируемость: Добавление нового события — это декларативное изменение в одном файле, а не императивный поиск по всему проекту.
Compile-time безопасность: Мы заставим TypeScript работать на нас. Он будет нашим главным ревьюером, который отловит ошибки в именах и параметрах событий еще до того, как код попадет в CI.
Единый источник правды: Наш конфигурационный файл станет живой документацией и формальным контрактом между разработкой и аналитиками.
В итоге мы получим не просто набор вызовов, а предсказуемую и надежную подсистему приложения.
Шаг 1: Подготовка плацдарма в AppMetrica
Прежде чем писать код, нужно создать для нашего приложения «проект» в веб интерфейсе AppMetrica.
- Открываем панель AppMetrica и входим с Яндекс ID.
- Нажимаем «Добавить приложение».
- Заполняем базовую информацию: название, URL в сторах (если есть) и, что важно, часовой пояс для корректного отображения отчетов.
- Принимаем условия и завершаем создание.
Важный нюанс: если ваше приложение работает и на iOS, и на Android, используйте для обеих платформ один и тот же API-ключ. Это позволит консолидировать данные в едином отчете, что значительно упростит анализ.
Шаг 2: Получение API-ключа
Сразу после создания приложения система сгенерирует API-ключ. Его следует скопировать. Если вы пропустили этот шаг, ключ всегда можно найти в настройках приложения в разделе «Основное». В реальном проекте этот ключ, разумеется, стоит хранить в переменных окружения, а не хардкодить.
Шаг 3: Установка зависимостей
Теперь переходим к коду. Устанавливаем пакет стандартным способом:
# npm
npm install @appmetrica/react-native-analytics —save
# yarn
yarn add @appmetrica/react-native-analytics
Для iOS не забываем установить нативные зависимости:
cd ios
pod install
Android, как правило, не требует дополнительных танцев с бубном благодаря автолинкингу.
Шаг 4: Инициализация SDK
SDK нужно активировать один раз при старте приложения. Чтобы не загрязнять корневой компонент, вынесем всю логику, связанную с аналитикой, в отдельный сервисный модуль, например, services/metrica.ts .
Функция активации
// services/metrica.ts
import AppMetrica from ‘@appmetrica/react-native-analytics’;
/**
* Инициализирует AppMetrica SDK.
* Вызывается один раз при старте приложения.
*/
export const activateMetrica = () => {
AppMetrica.activate({
apiKey: ‘abcde-abcde-abcde-abcde-abcde’, // В проде забираем из env
sessionTimeout: 120, // Таймаут сессии в секундах
logs: __DEV__, // Очень полезно для отладки: выводит в консоль все вызовы SDK
});
};
Вызов в корневом компоненте
// App.tsx
import React, { useEffect } from ‘react’;
import { activateMetrica } from ‘./services/metrica’;
const App = () => {
useEffect(() => {
activateMetrica();
}, []);
// …
};
export default App;
Шаг 5: Проектирование схемы событий
Это сердце нашей архитектуры. Мы создадим единый объект-конфигурацию, который станет декларативным описанием всей нашей аналитики. Каждое событие будет иметь общее имя (`eventName`), которое увидят аналитики, и функцию `buildPayload` — фабрику, отвечающую за корректную структуру параметров.
// services/metrica.ts
// Типизируем параметры для строгости и автодополнения
type TaskSource = ‘Мои’ | ‘Участвую’ | ‘Контролирую’ | ‘Сегодня’;
type SectionTab = ‘Сегодня’ | ‘Контролирую’ | ‘Участвую’ | ‘Мои’; type RegulationTab = ‘Изучить’ | ‘Все’;
// Наш единый источник правды
export const ANALYTICS_EVENTS = {
sections: {
openTasks: {
eventName: ‘Раздел’,
buildPayload: () => ({ ‘Задачи’: ‘(открытие)’ }),
},
openRegulations: {
eventName: ‘Раздел’,
buildPayload: () => ({ ‘Регламенты’: ‘(открытие)’ }),
},
selectTasksTab: {
eventName: ‘Раздел’,
buildPayload: (tabName: SectionTab) => ({ ‘Задачи’: tabName }), },
},
task: {
open: {
eventName: ‘Задача’,
buildPayload: (source: TaskSource) => ({ ‘(открытие)’: source }), },
createStart: {
eventName: ‘Задача’,
buildPayload: () => ({ ‘(создание)’: ‘(начало)’ }),
},
}
} as const; // `as const` здесь — ключ к магии TypeScript, он делает тип неизменяемым
Шаг 6: Статическая магия TypeScript
На первый взгляд эти типы могут показаться сложными, но их работа проста: они статически анализируют объект ANALYTICS_EVENTS и выводят из него все возможные ключи событий и типы аргументов для их buildPayload .
// … после ANALYTICS_EVENTS
// Генерирует все возможные ключи, например ‘sections.openTasks’ | ‘task.open’
type EventKey = { /* … */ };
// По ключу события определяет, какие аргументы ожидает его buildPayload type ArgsForEvent<K extends EventKey> = { /* … */ };
Мы не будем здесь приводить полную реализацию этих типов, так как она довольно громоздка, но суть в том, что они позволяют нам переложить рутинную проверку на компилятор.
Шаг 7: Реализация универсального диспетчера reportEvent
Теперь создадим единую функцию-«фасад», через которую будет проходить абсолютно вся аналитика в приложении. Она будет принимать строго типизированный ключ события и соответствующие ему аргументы.
// services/metrica.ts
export const reportEvent = <K extends EventKey>(
eventKey: K,
…args: ArgsForEvent<K>
) => {
// 1. Находим нужную конфигурацию в нашей «схеме»
const [groupKey, actionKey] = eventKey.split(‘.‘);
const config = (ANALYTICS_EVENTS as any)[groupKey]?.[actionKey];
if (!config) {
console.warn(`Конфигурация для аналитического события «${eventKey}» не найдена.`);
return;
}
const { eventName, buildPayload } = config;
// 2. Генерируем полезную нагрузку (payload) с помощью фабрики const payload = buildPayload(…args);
// 3. Отправляем событие, будучи уверенными в его корректности console.log(`Reporting event: «${eventName}«`, payload);
AppMetrica.reportEvent(eventName, payload);
};
Шаг 8: Использование в компонентах: чистота и безопасность
А теперь — вишенка на торте. Посмотрим, как элегантно и безопасно выглядит отправка событий из компонентов.
import { reportEvent } from ‘./services/metrica’;
import { Button, View } from ‘react-native’;
const MyScreen = () => {
return (
<View>
{/* Пример 1: Вызов без параметров. Автодополнение подскажет ключ. */}
<Button
title=«Открыть раздел Регламенты»
onPress={() => reportEvent(‘sections.openRegulations’)}
/>
{/* Пример 2: Вызов с параметром. TypeScript проследит за его типом. */}
<Button
title=«Показать задачи на сегодня»
onPress={() => reportEvent(‘sections.selectTasksTab’,
‘Сегодня’)}
/>
{/* Любая из следующих строк вызовет ошибку еще на этапе написания кода, а не в продакшене: */}
{/*
// ОШИБКА: такого события не существует в нашей схеме
reportEvent(‘sections.open_tasks’);
// ОШИБКА: событие ‘selectTasksTab’ требует один аргумент, а мы не передали ничего
reportEvent(‘sections.selectTasksTab’);
// ОШИБКА: ‘НеверныйТаб’ не соответствует типу SectionTab
(‘Сегодня’ | ‘Мои’ | …)
reportEvent(‘sections.selectTasksTab’, ‘НеверныйТаб’);
*/}
</View>
);
};
Что мы получили в итоге? Мы трансформировали потенциально хаотичный процесс интеграции аналитики в управляемую и предсказуемую систему. Наш конфигурационный файл — это не просто объект, это «контракт», который обеспечивает консистентность данных.
Такой подход не только снижает количество багов и улучшает Developer Experience, но и строит необходимый мост между разработкой и бизнес-стейкхолдерами (аналитиками, продакт-менеджерами). Когда аналитики могут доверять данным, которые они видят в отчетах, продуктовые решения принимаются быстрее и с большей уверенностью. А это и есть конечная цель внедрения любой аналитики.
Проконсультируем по всем вопросам
