Подключение к React, Vue и обычному HTML

Когда это нужно: разработчик выбирает место для готового блока в HTML, React, Vue или приложении с SSR. Результат: одна установка на приложение, а не новый клиент при каждом рендере или переходе.

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

Обычная установка — один и тот же готовый блок

1. В TopoMetrika откройте «Настройки», выберите продукт и блок «Установка на сайт».
2. Нажмите «Копировать код»: публичный ID и адрес пространства уже заполнены.
3. Добавьте весь блок в общий HTML-шаблон: внутри <head> или перед </body>.
4. Убедитесь, что шаблон подключает блок один раз на страницу; в SPA — один раз на приложение.
5. Если требуется предварительное согласие, настройте загрузку через свою панель или менеджер тегов только после него. Проверьте отказ, отзыв и поддерживаемое действие по чек-листу установки.

Не нужно собирать projectConfig, переносить токены или отдельно вызывать TopoMetrika.create: генератор уже включил инициализацию. Не добавляйте поверх готового блока ещё один клиент из API-примеров.

Обычный HTML, CMS и конструкторы

Разместите скопированный блок в общем шаблоне разрешённых страниц. В CMS или конструкторе используйте настройку для пользовательского HTML/скриптов, которая исполняет код, а не отображает его как текст. Если поле удаляет теги script или iframe содержит другой сайт, добавление строки в такое поле не установит сбор в основной продукт.

React и Vue

Добавьте готовый блок в базовый HTML-документ приложения, который содержит корневой элемент монтирования. Скрипт наблюдает отрисованный DOM, поэтому для обычного сбора не нужны отдельный React-компонент или Vue-composable. Когда можно загружать аналитику и как её остановить при отзыве, определяет интеграция владельца сайта.

Не вставляйте скрипт в компонент каждой страницы, обработчик клика или effect без контроля жизненного цикла. Обычные переходы SPA не требуют повторной установки: SDK уже наблюдает поддерживаемые History API действия и появление DOM-элементов.

Next.js и другие SSR-приложения

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

В коротком теге нет встроенного JavaScript. Для Content Security Policy разрешите конкретный origin пространства в загрузке скриптов и соединениях. Если политика допускает внешние скрипты только с nonce, используйте штатный nonce фреймворка. Не отключайте CSP. Копирование тега не меняет настройки безопасности целевого сайта автоматически.

Когда действительно нужен программный API

Для своего управляемого жизненного цикла, явно вызываемого capture или управляемого жизненного цикла интеграции используйте справочник API. createReactClient и createVueClient возвращают тот же клиент и отмечают платформу события; это необязательная дополнительная интеграция, а не условие установки одного блока.

Все варианты анализируют безопасный отрисованный DOM. SDK не обходит React Fiber и Vue internals и не требует API-ключа внешней языковой модели. Если вы создаёте клиент вручную вместо готового блока, загрузите bundle до инициализации, управляйте техническим enabled в соответствии с решением владельца сайта и вызовите destroy() при окончательном удалении интеграции.

Готовый блок не содержит собственного окна согласия. Для его остановки используйте адресованное событие topometrika:stop с точным endpoint/projectId из настроек, а не простое удаление тега. Оно останавливает текущую страницу; новый запуск — только после перезагрузки, когда владелец снова допускает загрузку. Подробности — в приватности и управлении загрузкой.

Семантическая разметка

<section data-tm-container>
  <h2>Оформление заказа</h2>
  <select aria-label="Способ доставки">…</select>
  <button type="button" data-checkout-submit>Купить</button>
  <aside data-tm-ignore>Не анализировать это поддерево</aside>
</section>

Используйте нативные inputs, select, textarea, button, ссылки и form/fieldset/article/section. Дополнительный data-tm-container задаёт границу контекста; data-tm-ignore исключает поддерево. Это дополнительные средства управления границами, а не обязательная разметка каждого клика. ARIA-метка попадает в текст узла только при точном разрешении в списке подписей.

SDK не гарантирует разбор iframe, canvas, Shadow DOM и произвольных рисованных контролов. Готовых нативных SwiftUI/Compose/Flutter SDK в этой поставке нет; название платформы в протоколе не означает готовую мобильную интеграцию. Как строится событие · Диагностика