Оформление
Примеры ранжирования
Здесь примеры подключения кодом — способами Свой список и Выдача. Без программиста ранжирование подключает размещение на странице.
Во всех примерах RANKING_ID — идентификатор ранжирования из редактора в кабинете. Скрипт Sales Ninja должен быть установлен на странице.
Каталог: переставить карточки на странице
Карточки уже нарисованы сайтом — такими, какие они есть. Размечать их не нужно: скрипт сам найдёт в каждой ссылку на товар, id, артикул или название, поэтому getId не нужен.
html
<div id="catalog">
<article><a href="/product/sneakers-air">Кроссовки Air</a>…</article>
<article><a href="/product/boots-trail">Ботинки Trail</a>…</article>
<article><a href="/product/socks-pack">Носки, 3 пары</a>…</article>
</div>js
const catalog = document.querySelector('#catalog')
const cards = [...catalog.children]
const { status, items } = await ninja('rankProducts', {
rankingId: 'RANKING_ID',
items: cards,
})
if (status === 'ranked') {
catalog.append(...items.map(({ item }) => item))
}append переносит существующие элементы, а не копирует их: обработчики событий и состояние карточек сохраняются.
Группы на странице
Товары разбиты на блоки, например по мощности двигателя. Порядок нужен внутри каждого блока, а сами блоки остаются на своих местах.
js
const groups = [...document.querySelectorAll('.power-group')]
const cardsByGroup = groups.map((group) => [...group.querySelectorAll('article')])
const { items } = await ninja('rankProducts', {
rankingId: 'RANKING_ID',
items: cardsByGroup,
})
items.forEach((rankedGroup, groupIndex) => {
groups[groupIndex].append(...rankedGroup.map(({ item }) => item))
})Ответ повторяет форму запроса: на массив групп приходит массив групп в том же порядке.
Данные до отрисовки
Сайт получает товары из своего API и рисует их сам. Тогда удобнее упорядочить данные до отрисовки. Скрипт сам прочитает в объекте товара id, артикул, ссылку и название; getId нужен, только если id лежит в поле, которого скрипт не знает (какие поля он читает).
js
const products = await fetch('/api/catalog?section=boots').then((response) => response.json())
const ranked = await Promise.race([
ninja('rankProducts', {
rankingId: 'RANKING_ID',
items: products,
timeout: 300,
}),
// safety net: if the Sales Ninja script did not load, the page waits no longer than 300 ms
new Promise((resolve) => setTimeout(() => resolve(null), 300)),
])
renderCatalog(ranked ? ranked.items.map(({ item }) => item) : products)timeout задаёт, сколько миллисекунд с момента вызова страница готова ждать ответа. Если ответ не успел, rankProducts возвращает исходный список без изменений со статусом timeout, поздний ответ не применяется, и страница рисуется без задержки.
Выдача из каталога: страница категории
Страница категории не присылает свой список: она называет категорию и номер страницы, а ранжирование отвечает страницей лучших для посетителя товаров смарт-фида и общим числом найденных. Пустой ответ — контрольная группа A/B-теста, каталог ещё загружается, ответ не успел или запрос не удался: тогда сайт показывает свою выдачу.
js
const pageSize = 24
const { items, total, trackImpression, trackClick } = await ninja('rankProducts', {
rankingId: 'RANKING_ID',
filter: { categoryIds: ['15'], inStock: true },
limit: pageSize,
offset: (page - 1) * pageSize,
})
if (items.length) {
// item is { id, groupId }: the offer id from the feed; the site renders the card by it itself
renderCards(items, (row) => trackClick(row.index))
renderPager(Math.ceil(total / pageSize))
trackImpression()
} else {
renderOwnListing(page)
}Все поля фильтра — в разделе Выдача из каталога.
Ссылки: блок «читайте также» без списка
На странице статьи есть блок на три ссылки. Сайт не передаёт список: ранжирование ссылок само выбирает три лучшие страницы из набора Что ранжируем, кроме текущей. Пустой ответ — контрольная группа A/B-теста или ещё не обученная модель: тогда блок остаётся таким, каким его рисует сайт.
js
const { items, trackImpression, trackClick } = await ninja('rankLinks', {
rankingId: 'RANKING_ID',
limit: 3,
})
if (items.length) {
// item and id are the page address; the site takes the link caption from its own data by it
renderReadAlso(items.map(({ item }) => item), (index) => trackClick(index))
trackImpression()
}Ссылки: меню со своими ссылками
Меню уже нарисовано сайтом. Скрипт сам прочитает адрес каждой ссылки — у элемента <a> или у первой ссылки внутри пункта меню, — поэтому getUrl не нужен. Обратно приходят те же элементы в новом порядке.
html
<ul id="menu">
<li><a href="/catalog/sale/">Распродажа</a></li>
<li><a href="/catalog/new/">Новинки</a></li>
<li><a href="/blog/">Блог</a></li>
</ul>js
const menu = document.querySelector('#menu')
const entries = [...menu.querySelectorAll('li')]
const { status, items, trackImpression, trackClick } = await ninja('rankLinks', {
rankingId: 'RANKING_ID',
items: entries,
})
if (status === 'ranked') {
menu.append(...items.map(({ item }) => item))
}
trackImpression()
for (const { item, index } of items) {
item.addEventListener('click', () => trackClick(index))
}Если ссылки лежат в данных, а не на странице, передайте объекты с полем url или укажите getUrl.