Установка TopoMetrika Web SDK

Автонастройка SDK

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

Неподтверждённые тексты остаются в памяти браузера; сервер получает только выбранные строки, у остальных — непрозрачные идентификаторы. Значения полей, query, тела запросов и секреты не отправляются. Во время записи обычная телеметрия счётчика приостановлена. Найденные подписи и маршруты требуют проверки владельцем продукта.

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

Один проход: до 128 действий и 15 минут. История: 20 подтверждённых проверок. Для связи окон нужны установленный SDK, разрешение на открытие окна и совместимые CSP/Cross-Origin-Opener-Policy. GPC и DNT продолжают действовать.

Результат: один короткий тег script на вашем сайте. TopoMetrika сама подставляет адрес пространства и публичный ID счётчика — без ключей, секретов и токенов. Разрешённые данные загружаются из актуальных настроек проекта автоматически. Вам не нужно редактировать переменные в скрипте.

Путь подключения: подготовить проект → скопировать код → подключить на сайт → проверить первое событие. Создание пространства само по себе не устанавливает SDK и не начинает сбор.

Что делает продакт, а что — разработчик

Продакт выбирает первый сценарий, согласует допустимые данные и создаёт проект с правами администратора. Разработчик подтверждает реальные домены и шаблоны действий сайта, подключает готовый блок целиком и проверяет доставку. Владелец сайта обеспечивает правовое основание обработки, уведомление и согласие посетителя, когда оно требуется.

TopoMetrika не показывает своё окно согласия, не читает решения произвольной CMP автоматически и не сохраняет выбор посетителя. После загрузки блока сбор запускается автоматически, если приём включён и GPC/DNT его не запрещают. Готовый код не заменяет проверку применимых требований к вашему сайту.

1. Подготовьте проект

1. В своём пространстве откройте TopoMetrika → «Настройки».
2. Нажмите «Новый проект» и заполните форму «Подключить продукт».
3. Укажите название и точные origin анализируемого сайта. Списки подписей и действий заполнит автонастройка после установки; ручной ввод находится в расширенных настройках. Эти значения определяются реальным продуктом, а не примером из руководства. Подробности — в настройках проекта.
4. Нажмите «Создать проект». Откройте блок «Установка на сайт».

Origin — домен сайта, где работает SDK; адрес пространства — место, куда поступают наблюдения. Генератор использует правильный адрес пространства автоматически: вручную переносить его в код не нужно.

2. Скопируйте один готовый блок

1. Нажмите «Копировать код».
2. Передайте весь блок разработчику либо подключите его самостоятельно, если управляете кодом сайта.

Это один внешний скрипт /topometrika/install-v1.js с публичным ID счётчика — без большого встроенного JavaScript, ключей, токенов и списков данных. Установщик получает настройки и подключает SDK. Не добавляйте второй клиент из справочника API и не заменяйте ID или адрес своими строками.

Код доступен повторно в любой момент. Откройте настройки сохранённого включённого проекта и снова нажмите «Копировать код». Перевыпуск ключа и окно одноразового показа не нужны. Публичный ID счётчика — не пароль и не разрешение читать аналитику либо пространство.

3. Подключите блок на сайт один раз

Разместите весь скопированный блок в HTML-коде разрешённых страниц: внутри <head>, перед закрывающим </body> либо через свой менеджер тегов. Для общего шаблона достаточно одной установки; в React, Vue и SPA — одной на приложение, не на каждую кнопку или переход.

<head>
  …
  <!-- Здесь весь готовый блок из «Установка на сайт», без изменений -->
</head>

Это схема места размещения, а не код SDK. Сам установочный блок копируйте из настроек своего проекта. Если требуется предварительное согласие, не размещайте его как безусловно исполняемый тег: настройте загрузку блока только после необходимого решения в вашей панели согласий или менеджере тегов. Код счётчика уже готов; условие его запуска настраивается на стороне владельца сайта.

В CMS используйте поле для исполняемых скриптов, а не отображения HTML как текста. Подробности — в способах размещения.

Если сайт применяет строгую Content Security Policy, разработчику нужно разрешить конкретный домен пространства для загрузки скриптов и соединений. В коротком теге нет встроенного JavaScript, поэтому отдельный hash для inline-кода не нужен. Если политика сайта разрешает даже внешние скрипты только по nonce, используйте штатный nonce сайта. Не отключайте CSP и не добавляйте wildcard ради установки.

4. Проверьте загрузку, событие и остановку

Для продакта: откройте согласованный тестовый сценарий, убедитесь, что владелец допускает аналитику в этом сценарии, выполните действие и попросите разработчика подтвердить принятый запрос. Затем выберите продукт и период в TopoMetrika и обновите отчёт. Черновики фич создаются сразу при подтверждении групп в автонастройке. Для статистического намерения отдельно нужны достаточно похожие реальные наблюдения; этот порог не задерживает создание каталога.

1. Убедитесь, что подключён один полный блок нужного проекта.
2. Проверьте, что сайт не загружает счётчик до необходимого согласия. Не обходите настройки приватности браузера.
3. После допустимой загрузки выполните действие кнопкой или формой, соответствующее разрешённому шаблону.
4. В Network найдите /api/topometrika/v1/config, затем /pulse и при необходимости /skeleton на домене пространства. Отдельного запроса за временным токеном нет.
5. При незнакомой структуре ожидаются 202 с запросом skeleton, передача структуры и повтор того же события. Ответ 204 без JSON означает принятую либо идемпотентно повторённую запись, не подтверждённую покупку.
6. Проверьте отказ и отзыв через вашу панель: она должна не загружать счётчик либо остановить уже работающий клиент.

Как остановить уже загруженный счётчик

Простое удаление тега из DOM не останавливает загруженный скрипт. В настройках рядом с кодом есть дополнительный готовый вызов topometrika:stop, адресованный только вашему endpoint и projectId. Вызовите его из обработчика отзыва вашей панели или менеджера тегов. Он останавливает текущий клиент и незавершённую загрузку, но не записывает решение посетителя и не удаляет ранее принятые события. Для нового запуска нужна перезагрузка страницы, и владелец сайта должен снова решить, допустима ли загрузка. Для собственного экземпляра есть технические setEnabled(false) и destroy(). См. ответственность владельца и приватность.

Что делать после изменения настроек

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

Если раньше стоял код с data-tm-key, параметром writeKey или атрибутом data-tm-consent, замените его новым коротким тегом из настроек. Старые режимы согласия отклоняются: после обновления установщика они не должны молча превратиться в автоматический сбор. Проверьте условия загрузки и остановки на стороне сайта.

Чек-лист готовности

• Сценарий, реальные домены, действия и допустимые подписи согласованы.
• Один полный блок из настроек установлен без ручной подстановки параметров.
• Владелец сайта обеспечил уведомления, правовое основание и согласие, когда оно необходимо.
• Отказ, отзыв и ограничения браузера проверены на фактической интеграции.
• Допустимое событие принято сервером; команда знает, где выбрать продукт и период отчёта.

Если данных нет, используйте диагностику. Дополнительные программные интеграции описаны в справочнике API; они не обязательны для обычного подключения готового блока.

Проверка установки и передача разработчику

Кнопка «Копировать инструкцию разработчику» копирует готовый тег, разрешённые сайты, условия загрузки, проверку и команду остановки. Размер рядом с кодом — байты HTML-разметки, а не размер загружаемого JavaScript.

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

Новые счётчики получают ID tmc_…. Ранее выданные tmp_… продолжают работать без замены.