API Web SDK

Когда это нужно: разработчик управляет жизненным циклом SDK или добавляет явный capture. Результат: код использует только действующие параметры и методы, а локальное состояние клиента не принимается за подтверждённую доставку.

Если вы продакт и не меняете код, достаточно плана подключения. Этот справочник можно передать разработчику вместе с выбранным сценарием.

Для обычной установки не копируйте примеры из справочника. Получите один полностью заполненный блок в «Настройки → Установка на сайт» и вставьте его целиком по инструкции установки. Примеры ниже объясняют контракт для дополнительных программных интеграций; это не готовый код вашего проекта.

Браузерный файл /topometrika/tm.js предоставляет глобальный объект TopoMetrika. Загрузка файла сама не создаёт клиент; сгенерированный установочный блок делает это автоматически. Методы создания нужно вызывать в браузере, не во время server-side rendering.

Создание клиента: справочный пример

const tm = TopoMetrika.create({
  endpoint: 'https://your-workspace.fichers.ru',
  projectId: 'EXAMPLE_COUNTER_ID',
  counterId: 'EXAMPLE_COUNTER_ID',
  approvedLabels: ['Купить'],
  approvedActions: ['POST /api/checkout/:id'],
  enabled: false,
  sampleRate: 1
});

Некорректная конфигурация отклоняется исключением, например INVALID_PROJECT_OPTIONS, INVALID_ENDPOINT, INVALID_APPROVALS, INVALID_APPROVED_ACTION, INVALID_ENABLED, INVALID_SAMPLE_RATE. Не заменяйте ошибки конфигурации молчаливым переходом к неограниченному сбору.

setEnabled(value) → void

Принимает boolean или функцию. true технически включает сбор при отсутствии GPC/DNT; false останавливает клиент, очищает оперативное состояние и прерывает активные отправки. После повторного включения создаётся новая аналитическая сессия. Метод не собирает, не хранит и не подтверждает согласие посетителя; уже принятые сервером события не удаляет.

refreshEnabled() → void

Повторно проверяет callback enabled и ограничения браузера. Вызывайте после изменения внешнего состояния, если enabled задан функцией. Владелец сайта определяет допустимость запуска. См. ответственность владельца и приватность.

capture(element, approvedAction?) → boolean

Явно строит снимок для поддерживаемого триггера и ставит событие в очередь. Передайте Element кнопки, ссылки или элемента, для которого находится допустимый триггер. Строка действия должна точно совпадать с разрешённым шаблоном.

const button = document.querySelector('[data-checkout-submit]');
if (button) {
  const queued = tm.capture(button, 'POST /api/checkout/:id');
  // true означает постановку в очередь, а не доставку или покупку.
}

Без второго аргумента используется UI_TRIGGER_ACTION, только если он явно разрешён. Этот запасной сигнал недостаточен для подтверждённого намерения. false может означать выключенный клиент, недопустимый триггер, действие вне allowlist, превышение бюджета снимка или заполненную очередь.

flush() → Promise<void>

Пытается отправить очередь сейчас. Это best effort: завершение Promise не гарантирует доставку каждого события, успешный бизнес-результат или надёжную отправку при unload. Таймауты, повторы и лимиты продолжают действовать.

getStatus() → объект

const status = tm.getStatus();
console.log(status.active, status.queued, status.pendingCaptures,
  status.delivered, status.dropped);

active — локальное состояние запуска; оно не доказывает доступность сервера. queued — длина очереди; pendingCaptures — снимки, ожидающие корреляции. delivered увеличивается после принятого ответа 204, dropped — для части отказов/исчерпанных отправок. Это оперативные счётчики экземпляра, не полный аудит потерь. При остановке они сбрасываются.

destroy() → void

Окончательно освобождает экземпляр: снимает hooks, обработчики и observer, очищает очередь и таймеры, отменяет активные запросы. После destroy создайте новый экземпляр, если интеграция нужна снова.

React, Vue и серверные маршруты

createReactClient(options) и createVueClient(options) имеют те же параметры и возвращают тот же клиент, но указывают соответствующую платформу. Они работают с DOM, не private Fiber/Vue internals. См. примеры фреймворков.

Готовый блок и публичные маршруты

Установщик получает конфигурацию через POST /api/topometrika/v1/config с {v: 1, counterId}. Затем SDK отправляет POST /api/topometrika/v1/pulse и /api/topometrika/v1/skeleton с публичным ID в p_id, без cookies, referrer, ключей и временных токенов. Отдельного обмена за разрешением на пять минут нет. Сервер проверяет точный origin, включённый проект, политику данных, частоту, размеры и повторы. Публичный ID и Origin не удостоверяют человека: внешний клиент может имитировать Origin.

Для остановки автоустановленного счётчика предусмотрено техническое событие topometrika:stop с точным {endpoint, projectId}. Готовый вызов есть в настройках проекта. Событие прерывает незавершённую загрузку и уничтожает активный клиент, не сохраняет решение и не перезапускает сбор. Для нового запуска перезагрузите страницу в момент, допустимый для владельца сайта. Готовый блок не раскрывает глобальную переменную tm. Для собственного экземпляра используйте методы выше, не создавая дубликат.

Административный API — отдельный session-authenticated контур. Публичный счётчик не даёт читать отчёты или менять настройки. Секреты учётных записей, OAuth и серверных сервисов остаются только на сервере. Старые браузерные writeKey/consent API не поддерживаются. Машиночитаемый контракт доступен в OpenAPI TopoMetrika. Не существует SDK-методов trackUser, identify, trackPurchase или setApiKey: ориентируйтесь на перечисленный API.

Дальше: подключение к React и Vue или проверка проблем интеграции.