Оформление
Событие onPersonalization
Три продукта в админке — один JS API
В разделе Сайт персонализации, A/B-тесты и действия по правилам — отдельные сущности (чем они отличаются).
В веб-бандле и JS API все они проходят через один метод onPersonalization: один и тот же personalizationId, те же варианты (personalizationOptionId), тот же handler.
- Персонализация — AI выбирает вариант под пользователя.
- A/B-тест — сравнение вариантов по статистике.
- Действие по правилам — показ по жёстким условиям без ML.
Первый аргумент handler — объект любой из этих сущностей (в коде часто называется personalization или abTest в примерах админки); второй — выбранный вариант.
onPersonalization передаёт выбранный вариант персонализации, A/B-теста или действия по правилам в вашу JavaScript-логику. Обработчик может самостоятельно реализовать вариант: например, изменить страницу или учесть выбор в своей аналитике.
Вызов обработчика не подтверждает успешного выполнения встроенных изменений страницы. Например, подписка может сработать, даже если элемент для изменения не найден. Если вашей логике нужен результат изменения страницы, проверьте его отдельно.
Общая идея
Подписка — вызов ninja('onPersonalization', { ... }). Можно указать:
- только
personalizationId— сработает при любом варианте этой сущности; personalizationId+personalizationOptionId— только для конкретного варианта;- ни одного ID — на передачу каждого выбранного варианта любого продукта раздела Сайт на странице.
personalizationId берётся из карточки сущности в админке (персонализация, A/B-тест или действие по правилам — поле ID одно и то же по смыслу для API).
Самая простая подписка (пример для персонализации; для A/B или rule-based подставьте свой ID):
js
// Example: the "Show the best review for the product" personalization
ninja('onPersonalization', {
personalizationId: '6fbf1dd7-3771-45ce-a7a0-bd08187549ee',
handler: (entity, variant) => {
switch (variant.id) {
case '10337247-6fa7-4ac3-92ed-bb2506d79ffa':
// "Yes" variant
break;
case 'fb8211d7-5aa3-40df-a3ed-54a67d72f850':
// "No" variant
break;
}
},
})Тот же вызов для A/B-теста или действия по правилам — только другой personalizationId из соответствующего раздела админки.
Типы подписки
Существует три основных типа подписки:
Указан один personalizationId
Подписка сработает, если сущность применима по условиям показа, с любым вариантом.
js
ninja('onPersonalization', {
personalizationId: '6fbf1dd7-3771-45ce-a7a0-bd08187549ee',
handler: (entity, variant) => {
switch (variant.id) {
// any variant of this entity
}
},
})Указаны personalizationId и personalizationOptionId
Подписка сработает только для конкретного варианта.
js
ninja('onPersonalization', {
personalizationId: '6fbf1dd7-3771-45ce-a7a0-bd08187549ee',
personalizationOptionId: '10337247-6fa7-4ac3-92ed-bb2506d79ffa',
handler: (entity, variant) => {
// only the selected variant
},
})Не указан ни personalizationId, ни personalizationOptionId
Подписка на передачу каждого выбранного варианта на странице — персонализация, A/B или rule-based. Подходит для общей логики и учёта назначений в своей аналитике; вызов подписки не доказывает фактический показ.
js
ninja('onPersonalization', {
handler: (entity, variant) => {
// the selected variant of any Site product
},
})Таймаут
Если ожидание выбранного варианта критично по времени (например, промежуточная страница перед лендингом A/B), задайте timeout и onTimeoutExceeded — они работают для всех типов сущностей так же, как для персонализаций.
js
ninja('onPersonalization', {
personalizationId: '6fbf1dd7-3771-45ce-a7a0-bd08187549ee',
handler: (entity, variant) => { /* ... */ },
timeout: 2000,
onTimeoutExceeded: (entity, variant) => { /* ... */ },
})Несколько подписок с таймаутом
Если несколько подписок на варианты одной сущности и у каждой указан таймаут, после синхронного вызова обработчика любой из них без исключения onTimeoutExceeded у остальных не вызывается.
Таймаут по умолчанию
Если есть onTimeoutExceeded, но нет timeout, используется 5 секунд.
Метод подписки возвращает Promise
onPersonalization возвращает Promise. Перед вызовом дождитесь window.SalesNinja.ready === true.
Promise разрешается после синхронного возврата из handler без исключения. Асинхронная работа, запущенная внутри handler, не ожидается; завершение подписки не подтверждает успех встроенных изменений страницы.
js
await ninja('onPersonalization', {
personalizationId: '6fbf1dd7-3771-45ce-a7a0-bd08187549ee',
handler: (entity, variant) => { /* ... */ },
})Аргументы обработчика
handler вызывается с двумя аргументами: объектом сущности и выбранным вариантом.
Третий аргумент dataContext, описанный в прежних версиях справки, не поддерживается и не передаётся. Обработчик не получает через него гео, Schema.org или погоду. Если в вашей подписке остались обращения к dataContext, удалите их: чтение его полей вызовет ошибку.
Устаревший способ
Для обратной совместимости: window.SalesNinja.onPersonalization({ ... }) — тот же контракт, что у ninja('onPersonalization', ...).
См. также
- Ручной запуск вариантов —
applyPersonalization - REST: персонализации (runtime) и A/B (runtime) — тот же стек без веб-бандла
- JS-действия в варианте