Как подключить аналитику nana800 к сайту или приложению за 5 минут

Шаг 1. Организация и проект

Откройте кабинет аналитики и войдите в аккаунт nana800 или зарегистрируйтесь. Если аналитики у вас ещё нет, кабинет покажет форму из двух полей: «Название вашей организации» и «Название проекта». Заполните их и нажмите «Создать».

Организация объединяет проекты, дашборды и команду. Проект соответствует одному сайту или приложению, в один проект можно отправлять события из нескольких источников, например с сайта и из мобильного приложения одного сервиса. Следующие проекты добавляются кнопкой «Новый проект» на странице организации.

Шаг 2. Ключ проекта и ID проекта

Откройте настройки проекта: кнопка «Настройки проекта» на карточке проекта или «Подключить трекинг». На вкладке «Подключение» есть карточка «Ключ проекта» с ключом вида ingest_... и ID проекта.

Ключ проекта умеет только отправлять события в этот проект, поэтому его можно вставлять в код сайта. Личный API-ключ из настроек аккаунта на сайт или в приложение не вставляйте никогда: любой посетитель увидит его в коде страницы и получит доступ к аккаунту. Если ключ проекта попал к чужим людям, нажмите «Сменить ключ», старый перестанет работать сразу.

Шаг 3. Код для обычного сайта

Если сайт собран без npm, например на Tilda, WordPress или в виде обычного HTML, вставьте код перед закрывающим тегом </body>. Готовый код с вашим ключом и ID проекта есть в карточке «Код для установки».

Аналитика nana800 считает людей по id пользователя и не отправляет события, пока id не задан. Библиотека сама id не придумывает. Для посетителя без входа создайте случайный id и сохраните его в браузере, как в примере ниже. Когда человек войдёт в аккаунт, вызовите identify с его настоящим id.

<script src="https://cdn.jsdelivr.net/npm/nana800-analytics@1/dist/nana800-analytics.min.js"></script>
<script>
  const analytics = Nana800Analytics.createNana800Analytics({
    apiKey: 'ingest_ключ_проекта',
    appProjectId: 'id_проекта',
  });

  let visitorId = localStorage.getItem('visitor_id');
  if (!visitorId) {
    visitorId = crypto.randomUUID();
    localStorage.setItem('visitor_id', visitorId);
  }
  analytics.identify(visitorId);
  analytics.track('page_view', { page: window.location.pathname });
</script>

Шаг 3. Код для React, Vue, Next.js и Electron

Установите пакет nana800-analytics. У него нет зависимостей, в собранном виде он весит около 13 КБ, типы TypeScript в комплекте.

// npm install nana800-analytics
import { createNana800Analytics } from 'nana800-analytics';

export const analytics = createNana800Analytics({
  apiKey: 'ingest_ключ_проекта',
  appProjectId: 'id_проекта',
});

// после входа: id пользователя в вашей системе и его свойства
analytics.identify('user-123', { plan: 'pro' });
analytics.track('button_clicked', { button: 'signup' });

Значения свойств передаются строками. Клиент создаётся один раз на всё приложение, например в отдельном файле, который импортируют остальные части кода.

Шаг 3. Код для React Native, Expo и сервера на Node.js

В React Native и Expo передайте хранилище AsyncStorage, иначе события, которые не успели уйти, пропадут при закрытии приложения. На сервере Node.js 18 и новее хранилище не нужно, но перед завершением процесса вызовите await analytics.flush().

import AsyncStorage from '@react-native-async-storage/async-storage';
import { createNana800Analytics } from 'nana800-analytics';

// React Native и Expo
const analytics = createNana800Analytics({
  apiKey: 'ingest_ключ_проекта',
  appProjectId: 'id_проекта',
  storageAdapter: AsyncStorage,
});

// Node.js: createNana800Analytics({ apiKey, appProjectId, disableStorage: true })
// и третий аргумент track с id пользователя:
// analytics.track('api_request', { endpoint: '/orders' }, 'user-123');

Шаг 4. Проверьте, что события приходят

Откройте свой сайт или приложение с установленным кодом. В настройках проекта карточка «Первое событие пришло» проверяет данные каждые 10 секунд и меняет «Ждём первое событие» на «События приходят, всё подключено». Само событие видно в разделе «События».

Библиотека копит события и отправляет их пакетами: первый раз через 3 секунды после запуска, дальше раз в 20 секунд, до 100 событий в запросе. Если сеть пропала, пакет уйдёт при следующей попытке. Каждое событие получает свой event_id, поэтому повторная отправка не создаёт дублей.

Если события не приходят

Откройте вкладку Network в инструментах разработчика браузера и посмотрите ответ на запрос к api.analytics.nana800.io.

• 401: неверный ключ. Нужен ключ проекта ingest_... именно этого проекта.
• 402: закончились деньги на балансе, а бесплатные события месяца уже потрачены.
• 403: в настройках проекта включён список разрешённых сайтов, и вашего сайта в нём нет.
• 413: запрос больше 1 МБ или в нём слишком много событий.
• 429: превышен лимит событий в минуту для проекта или для аккаунта.
• Запроса нет совсем: не вызван identify и у событий нет id пользователя, или посетитель распознан как робот. Браузеры под управлением программ и проверки скорости страниц библиотека не считает.

Защита ключа от чужих событий

Ключ проекта виден в коде страницы, поэтому кто-то может отправлять с ним свои события и тратить ваш баланс. На вкладке «Защита» настроек проекта есть два переключателя: «Принимать события только с моих сайтов» (до 50 сайтов, поддомены подходят) и «Ограничить число событий в минуту». События сверх лимита не сохраняются и не списываются с баланса. Для всех проектов аккаунта всегда действует общий предел 50 000 событий в минуту.