Оформление
JavaScript API установленного скрипта
Этот API работает в браузере после установки скрипта из Настройки проекта → Установка на сайт. Для браузерных методов не нужен X-SN-TOKEN. Управление сущностями через REST API описано отдельно.
Минимальный запуск
Очередь ninja(...) должна получить init до start:
html
<script>
ninja('init', '<код проекта>');
ninja('start');
</script>Код проекта и имя глобальной функции копируйте из текущего сниппета кабинета. start без init завершается ошибкой. Инициализируйте и запускайте бандл один раз на страницу; при SPA-навигации повторять установку, init или start не нужно. Смена проекта в уже работающей странице не поддерживается. Обработка повторов защищает от ошибок установки: она не предназначена для обновления конфигурации или перезапуска. Повторный start возвращает результат первоначального запуска, включая его ошибку.
Публичные задачи и методы
| Задача | Метод JavaScript API | Страница |
|---|---|---|
| Достичь ручной цели | reachGoal(goalId, params?) | Ручная цель |
| Реагировать на применённый onsite-вариант | onPersonalization(options) | Подписка |
| Получить товары или категории JavaScript-размещения | onProductRecommendations(options) | Товарные рекомендации |
| Упорядочить свой список товаров или получить страницу выдачи из каталога | rankProducts(options) | Ранжирование товаров |
| Упорядочить свои ссылки или получить лучшие страницы набора | rankLinks(options) | Ранжирование ссылок |
| Запросить повторную проверку указанных onsite-сущностей | applyPersonalization(items?) | Ручной запуск |
| Задать/прочитать параметры пользователя | setUserParam, deleteUserParam, getUserParam, getUserParams | User params |
| Задать/прочитать параметры страницы | setPageParam, deletePageParam, getPageParam, getPageParams, clearPageParams | Page params |
| Получить идентификатор посетителя | getCustomerId, getCustomerIdAsync | Чтение / подготовка идентификатора браузера |
| Дождаться идентификатора сессии | getSessionIdAsync() | Ожидает запуск; см. ниже |
| Подключить browser-вызовы Метрики | addYandexMetrika(counterId) | Метрика через бандл |
personalizationId в общем onsite-контуре может быть ID персонализации, A/B-теста или действия по правилу. Это историческое имя параметра публичного JS-контракта, а не переименование трёх продуктов.
Идентификатор сессии
После init вызов await ninja('getSessionIdAsync') ожидает единственный запуск бандла (или запускает его, если start ещё не был вызван), затем возвращает ID текущей сессии. При ошибке запуска, вызове без init или отсутствии сессии после запуска Promise отклоняется. Повторный вызов читает текущую сессию: ID не кешируется навсегда.
Полученный ID связывает ваши события с сессией браузера. Он не подтверждает доставку визита на сервер. getCustomerIdAsync решает другую задачу — подготавливает идентификатор посетителя; он не ожидает завершения запуска сессии.
Что не считать работающим API
addGoogleAnalytics() в текущем скрипте не выполняет действий. Google Analytics объясняет рабочий маршрут через цель и пользовательский обработчик.
Ошибки и восстановление
Методы проверяют аргументы и пишут сообщения об ошибках в консоль браузера. Для onPersonalization используйте onFallback/onTimeoutExceeded, если при отсутствии ответа нужно показать обычный вариант сайта. Таймаут относится к вашей подписке и не доказывает, что сама сущность сломана. Форматы ошибок других API смотрите в инструкциях к этим API.
Связано
Передача суммы корзины: registerCartUpdate.