Оформление
Событие onProductRecommendations
Когда размещение товарных рекомендаций работает в режиме Передавать данные через JavaScript, скрипт Sales Ninja не рисует карточки сам. Он передаёт товары или категории и состояние в обработчик. Карточки выводит сайт.
Этот метод нужен только для такого размещения. Если блок вставляет Sales Ninja, подписка не требуется — см. размещение.
Сначала очередь ninja(...) должна получить init и start. Код проекта копируйте из Настройки проекта → Установка на сайт.
html
<script>
ninja('init', '<project code>');
ninja('start');
</script>onProductRecommendations можно вызвать до start: вызов встанет в очередь и выполнится после загрузки скрипта. Если вызвать его до init, вернётся ошибка Run init before onProductRecommendations.
Можно ли получить рекомендации через REST API?
Нет, публичного REST API для товарных рекомендаций нет: получить подборку POST-запросом с сервера нельзя. В открытом API есть методы для персонализаций, A/B-тестов и передачи целей, а получить товары для посетителя своим кодом можно только в браузере, через событие onProductRecommendations на этой странице. Управляющий API рекомендации тоже не покрывает.
Адреса, к которым обращается скрипт Sales Ninja на сайте, — его внутренний канал, а не открытый API: они не описаны для вызова с сервера и могут измениться. Поэтому готового способа получить подборку с бэкенда, при серверной отрисовке или в мобильном приложении сейчас нет.
Подписка
Примеры с await выполняйте внутри async-функции или в <script type="module">. Обычный <script> не поддерживает await на верхнем уровне.
js
const unsubscribe = await ninja('onProductRecommendations', {
placementId: '11111111-1111-1111-1111-111111111111',
handler: ({ status, items, trackClick }) => {
}
})| Поле | Обязательно | Назначение |
|---|---|---|
handler | да | Функция, которая получает каждый результат |
placementId | нет | Идентификатор размещения из кабинета. Без него обработчик получает все JavaScript-размещения |
timeout | нет | Миллисекунды ожидания первого результата, если задан onTimeoutExceeded. По умолчанию 5000 |
onTimeoutExceeded | нет | Вызывается один раз, если за отведённое время не пришёл ни один результат |
Метод возвращает Promise с функцией отписки. Вызовите её, когда компонент окончательно размонтирован.
Идентификатор размещения появляется после первого сохранения. До сохранения в кабинете показан пример без конкретного идентификатора.
Если подписка создана уже после ответа, обработчик сразу получает последний актуальный результат этого размещения.
Состояния
handler получает один объект.
status | Когда приходит | Что делать |
|---|---|---|
available | Пришла выдача товаров или категорий для размещения | Нарисовать карточки из items |
cleared | Страница больше не подходит, сменился маршрут SPA или размещение исчезло из ответа | Удалить прежний блок. items будет пустым |
При переходах внутри SPA событие приходит повторно. Не копируйте карточки поверх старых: заменяйте содержимое контейнера целиком.
Пример реализации
Подставьте свой placementId и контейнер. Стили карточек задаёт сайт.
js
const root = document.querySelector('#recommendations')
const unsubscribe = await ninja('onProductRecommendations', {
placementId: '11111111-1111-1111-1111-111111111111',
handler: ({ status, items, trackClick }) => {
if (!root) return
if (status === 'cleared') {
root.replaceChildren()
return
}
root.replaceChildren(
...items.map((item, itemIndex) => {
const card = document.createElement(item.linkUrl ? 'a' : 'div')
if (item.linkUrl) {
card.href = item.linkUrl
card.addEventListener('click', () => trackClick({ itemIndex }))
}
if (item.imageUrl) {
const image = document.createElement('img')
image.src = item.imageUrl
image.alt = item.title || ''
card.append(image)
}
const title = document.createElement('span')
title.textContent = item.title || ''
card.append(title)
if (item.priceAmount != null) {
const price = document.createElement('span')
price.textContent = `${item.priceAmount} ${item.priceCurrency || ''}`
card.append(price)
}
return card
})
)
}
})Данные для карточки
Эти поля нужны в первую очередь, чтобы показать товар.
json
{
"projectProductId": "22222222-2222-2222-2222-222222222222",
"title": "Кроссовки беговые Flow Runner",
"linkUrl": "https://shop.example/catalog/flow-runner",
"imageUrl": "https://cdn.example/images/flow-runner.jpg",
"priceAmount": 7490,
"priceCurrency": "RUB"
}| Поле | Смысл |
|---|---|
projectProductId | Идентификатор товара для передачи клика через trackClick |
title | Название |
linkUrl | Ссылка на карточку товара |
imageUrl | Изображение |
priceAmount | Цена |
priceCurrency | Валюта, например RUB |
Поле может отсутствовать, если его нет в каталоге. Не опирайтесь на то, что каждое значение всегда заполнено.
Что ещё можно взять
При необходимости в товаре есть бренд, старая цена и наличие. В самом ответе — статус, идентификатор размещения и настройки внешнего вида, если рисуете блок по ним. Sales Ninja эти настройки сам не применяет.
| Поле | Смысл |
|---|---|
status | available — есть товары, cleared — блок нужно убрать |
brand | Бренд |
oldPriceAmount | Старая цена, если есть скидка |
availability | Нормализованное наличие, например inStock |
externalItemId | Идентификатор товара в каталоге магазина |
presentation.settings | Настройки внешнего вида из кабинета, если они нужны сайту |
Для вывода карточек и передачи кликов достаточно описанных выше полей.
Таймаут
Если витрина должна скрыть запасной блок, когда рекомендации не пришли, задайте timeout и onTimeoutExceeded. Таймаут относится к вашей подписке и не доказывает, что размещение сломано: страница могла не подойти под условия, фильтр исключил все товары или посетитель попал в контрольную группу A/B-теста размещения.
js
await ninja('onProductRecommendations', {
placementId: '11111111-1111-1111-1111-111111111111',
handler: (payload) => { /* ... */ },
timeout: 2000,
onTimeoutExceeded: () => {
document.querySelector('#recommendations-fallback')?.removeAttribute('hidden')
},
})Показы и клики
Выдача непустого списка уже учитывается как показ размещения в сессии — в том числе в режиме JavaScript. Повторная выдача того же размещения в одной сессии не добавляет ещё один такой показ.
Кроме того, список, который получил ваш handler, считается показом всех его товаров: скрипт сам отправляет его один раз на каждую выдачу. По этим показам модель учится, а в пределах сессии уже показанные товары уступают место новым. Если handler выбросил исключение, выдача показом не считается. Отдельно передавать показ не нужно.
Для учёта кликов handler получает функцию trackClick. Вызывайте её в обработчике реального клика одним из способов:
js
trackClick({ itemIndex: 0 })
// An alternative for the same product, not a second call for one click:
trackClick({ projectProductId: items[0].projectProductId })Открытие карточки средней кнопкой мыши в новой вкладке браузер присылает событием auxclick с event.button === 1, а не click. Чтобы такие переходы тоже учитывались, повесьте на это событие тот же вызов.
Передавайте ровно одно поле. itemIndex — индекс от нуля в исходном items. Если фильтруете или переставляете карточки, сохраняйте исходный индекс либо передавайте projectProductId из товара этой выдачи. Это не externalItemId из каталога магазина. Неизвестный или неоднозначный идентификатор, неверный индекс и оба поля одновременно не создают событие.
trackClick возвращает undefined, не требует await и не выполняет переход. Каждый вызов учитывается как отдельный клик. Ошибка отправки не прерывает работу сайта; доставка события при закрытии страницы или сетевом сбое не гарантируется. Клик не подтверждает загрузку страницы назначения.
Используйте функцию из последнего результата: после замены или очистки выдачи, смены страницы или сессии и отписки прежняя функция ничего не отправляет. В состоянии cleared вызов также ничего не отправляет.
Если установленная версия скрипта ещё не передаёт trackClick, обновите её перед подключением учёта кликов. Прежние подписки без этого метода продолжают работать. В готовом блоке клики и видимость карточек учитываются автоматически: карточка считается показанной, когда на экране оказалась хотя бы половина её площади. Цели, корзина и покупки передаются через обычную интеграцию сайта.
Блок категорий
Ответ всегда сообщает вид блока в itemKind: product или category. Размещение со сценарием из семейства категорий передаёт itemKind: 'category', а в items вместо товаров лежат категории. Пример выше выводит и их: у категории нет цены, поэтому строка цены не появится.
| Поле | Что это |
|---|---|
categoryId | Идентификатор категории из фида — для передачи клика |
title | Название категории из фида |
linkUrl | Адрес страницы категории, например //shop.example.ru/catalog/phones/, или null, если адрес недоступен |
imageUrl | Картинка товара этой категории |
Клик передаётся так же, как у товаров, одним полем:
js
trackClick({ itemIndex: 0 }) // index in items
// or
trackClick({ categoryId: items[0].categoryId })projectProductId в блоке категорий, как и categoryId в блоке товаров, событие не создаёт.
Проверяйте itemKind перед чтением полей, которые есть только у одного вида блока. Если linkUrl отсутствует, получите адрес категории из своего каталога или покажите карточку без перехода. Не создавайте ссылку на #.
Ошибки
Аргументы проверяются до подписки. Неверные типы дают Invalid onProductRecommendations arguments. Вызов до init даёт Run init before onProductRecommendations. Ошибки внутри handler не обрывают остальные подписки: они пишутся в консоль.