Быстрый старт

• Регистрация и настройка
• Установка
• Модули Tracer JS SDK
• Базовая инициализация
• Дополнительные возможности инициализации SDK
• Доступ к SDK модулям (getTracerModules())
• Отключение модулей (disableTracerModules())

Регистрация и настройка

1. Зайти в аккаунт Tracer.
2. Создать или вступить в организацию (нужно запросить ссылку-приглашение у администратора или владельца).
3. Добавить JS проект (нужно быть администратором или владельцем организации).
4. Для интеграции понадобится appToken из настроек проекта

Установка

Для установки необходимых пакетов введите в терминале команду:

npm install @apptracer/sdk --save

Модули Tracer JS SDK

SDK разделён на функциональные модули (initTracer-названиемодуля), отвечающие за сбор и хранение информации о событиях, и модули отправки данных (initTracer-названиемодуля-Uploader), необходимые для загрузки собранных данных в Трейсер:

Модуль	Описание
initTracerError	Отвечает за сбор глобальных событий и ручную регистрацию ошибок в проекте. Подробнее в Crash и Non-Fatal
initTracerErrorAsyncStack	Отвечает за сбор и регистрацию ошибок в асинхронном коде проекта. Подробнее в Crash и Non-Fatal
initTracerLog	Отвечает за хранение логов событий, предшествующих сбою. Подробнее в Добавление информации к событиям
initTracerErrorUploader	Отвечает за отправку данных о событиях в сервис.
initTracerSessionUploader	Отвечает за отправку данных о состоянии сессий приложения в сервис.

Каждый из модулей можно импортировать независимо друг от друга (основываясь на ваших потребностях). Это позволяет проинициализировать их на разных этапах загрузки приложения (в зависимости от приоритета) и тем самым уменьшить размер первоначального бандла.

Например, логично начать отслеживание ошибок как можно раньше, а потому модули, отвечающий за сбор и накопление ошибок, следует интегрировать в начальный бандл. Это позволит фиксировать ошибки с момента загрузки приложения, обеспечивая более полное и своевременное логирование. В то же время модули, связанные с отправкой данных, могут быть загружены позже, в отдельном бандле. Таким образом вы сможете отложить их инициализацию до тех пор, пока не будет завершена основная загрузка страницы.

ВАЖНО! В данный момент поддерживается только браузерное окружение.

Базовая инициализация

Для базовой инициализации Трейсера и мониторинга сбоев в вашем проекте достаточно вызвать модуль initTracerError и соответствующий ему «загрузчик» с параметрами конфигурации:

В вашем app.js:

import { initTracerError, initTracerErrorUploader } from '@apptracer/sdk';

// Подписываемся на глобальные события ошибок
initTracerError();

// Инициализируем Трейсер для отправки зарегистрированных ошибок
initTracerErrorUploader({
    versionName: BUILD_VERSION_NAME,
    versionCode: BUILD_VERSION_CODE,
    appToken: 'appToken из настроек в Трейсере',
    // ваши параметры (см. ниже)
});

Параметры конфигурации (одинаковы для всех модулей -Uploader):

Параметр	Тип	Обязательный	Описание
appToken	string	Да	Персональный токен вашего проекта в Трейсере. Можно найти в разделе Настройки (нужно быть администратором или владельцем организации)
versionName	string	Да	Отображаемое имя версии. Чаще всего используется версия из package.json
versionCode	number	Да	Порядковый номер версии вашего приложения. В интерфейсе versionCode группируется по versionName.
apiHost	number	Нет	Адрес, на который будут отправляться данные Трейсера вместо адреса по умолчанию. Используйте с умом.
environment	number	Нет	Окружение, на котором работает приложение (например: prod/test/dev). Параметр влияет на значение crash-free

Если в процессе инициализации у вас возникли сложности, вы можете задать вопрос в нашем чате поддержки

Дополнительные возможности инициализации SDK

Единая конфигурация для Uploader-ов

Поскольку Uploader-модули имеют одинаковый набор параметров, для удобства работы вы можете создать единый объект конфигурации и использовать его при инициализации необходимых модулей:

import { initTracerError, initTracerErrorUploader, initTracerSessionUploader } from '@apptracer/sdk';

initTracerError();

const config = {
    versionName: BUILD_VERSION_NAME,
    versionCode: BUILD_VERSION_CODE,
    appToken: 'appToken из настроек в Трейсере',
    environment: 'prod',
    // прочие параметры
};

initTracerErrorUploader(config);
initTracerSessionUploader(config);

Единый объект SDK (initTracerSdk(config: T, ...moduleInit: U))

В отличие от Uploader-ов каждый из функциональных модулей имеет собственный набор параметров конфигурации (подробнее читайте в описании соответствующего модуля). Для более удобного доступа к SDK вы можете собрать все необходимые параметры в общую конфигурацию и провести инициализацию сразу нескольких модулей в один объект:

import { initTracerError, initTracerErrorUploader, initTracerLog, initTracerSdk } from '@apptracer/sdk';

const tracerSdk = initTracerSdk(
    {
        // ваши параметры
    },
    initTracerLog,
    initTracerError,
    initTracerErrorUploader,
);

export { tracerSdk };

Доступ к SDK модулям (getTracerModules())

Если модуль уже был проинициализирован в другом бандле, то повторные вызовы initTracer* могут вызвать ошибку! Чтобы получить инстанс нужного модуля SDK, воспользуйтесь getTracerModules – это сократит использование кода и поможет избежать ошибок:

import { getTracerModules } from '@apptracer/sdk';

// ITracerLog | undefined
const tracerLog = getTracerModules().log;

tracerLog?.log('some info');

Отключение модулей (disableTracerModules())

Если возникла ситуация, при которой вы не можете отправлять ошибки или любые другие данные (например, пользователь отказался отправлять статистику об ошибках), вы можете отключить модули SDK:

import { disableTracerModules } from '@apptracer/sdk';

disableTracerModules();

По отключению модулей все собранные SDK данные и подписки на события будут очищены с устройства.