Оформление
Метод rankProducts
rankProducts упорядочивает товары, которые сайт уже выбрал сам, внутри каждой группы, или отдаёт страницу лучших товаров смарт-фида ранжирования по фильтру — выдачу из каталога. На сервер уходят признаки товаров: ссылка, id, артикул и название. Вместе с ними уходит поведение посетителя: что он смотрел и что лежит в корзине. По ним модель ранжирования ставит порядок. Ваши значения возвращаются те же, только в новом порядке, будь то объекты, элементы страницы или строки. Что такое ранжирование и как его создать, описано на странице Ранжирование. Для ссылок — меню, статей, баннеров — есть rankLinks.
Вызов
js
const result = await ninja('rankProducts', {
rankingId: 'RANKING_ID',
items: products,
timeout: 300,
})Метод можно вызывать сразу после ninja('init', …): он не ждёт полной загрузки страницы и остальных модулей скрипта.
| Параметр | Обязательный | Что передать |
|---|---|---|
rankingId | Да | Идентификатор ранжирования из редактора в кабинете |
items | Да, если нет limit | Массив товаров или массив групп товаров (массив массивов) |
limit, offset, filter | Вместо items | Выдача из каталога: страница товаров по фильтру |
getId | Нет | Для особых случаев: функция, которая возвращает id товара, если он лежит в поле, которого скрипт не знает |
timeout | Нет | Сколько миллисекунд ждать ответа с момента вызова. По умолчанию 5000. Не успели — исходный список без изменений, а у выдачи — пустая страница: покажите свою |
Как узнаётся товар
Размечать товары для ранжирования не нужно. Без getId скрипт сам собирает признаки товара и отправляет их вместе:
- строка или число — id товара: id предложения из фида, id товара в каталоге проекта, штрихкод или артикул; строка может быть и ссылкой на страницу товара;
- объект — его поля
id,sku,article,vendorCode,code,offerIdиproductId, адрес вurl,hrefилиlinkи название вnameилиtitle; - элемент страницы — адрес ссылки (сам элемент или первая ссылка внутри него; ссылки
#…иjavascript:пропускаются), значения data-атрибутов, названных как идентификатор товара (data-id,data-product-id,data-sku,data-offer-id,data-article,data-vendor-codeи похожих), микроразметкаitemprop(sku,productID,gtin…,mpn) и название товара.
Сервер проверяет признаки от самого надёжного. Первыми идут id: id предложения из фида, затем id товара в каталоге проекта, затем штрихкод. За ними идут ссылка на страницу товара, артикул и последним — название. Товар сервер ищет сначала среди товаров смарт-фида ранжирования, потом во всём каталоге проекта. Обычно хватает одной ссылки на страницу товара: адрес может быть относительным или полным, с метками utm, якорем и косой чертой в конце — сервер приводит его к одному виду. Артикул принимается, только если у ранжирования выбран смарт-фид, артикул однозначен в нём и не совпадает с id другого товара, поэтому чужой id не попадёт на чужой товар. Название — только если такое название у одного товара проекта. Неузнанный товар остаётся без оценки и на своём месте.
Результат
js
{
status: 'ranked',
items: [
{ item: <your value>, id: 'sku-102', score: 0.84, originalIndex: 1, index: 0 },
{ item: <your value>, id: 'sku-101', score: 0.31, originalIndex: 0, index: 1 },
{ item: <your value>, id: 'new-item', score: null, originalIndex: 2, index: 2 }
]
}items повторяет форму запроса: на массив приходит массив, на массив групп — массив групп в том же порядке.
| Поле | Смысл |
|---|---|
item | Значение, которое вы передали, без изменений |
id | Идентификатор товара, который ушёл на сервер, или null, если его не удалось получить |
score | Оценка товара моделью или популярностью (откуда берётся порядок). Сравнима только внутри одной группы одного ответа. null — у товара нет оценки |
originalIndex | Позиция значения в исходной группе, с нуля |
index | Итоговая позиция в группе после ранжирования, с нуля |
Посетитель получает список в одном из трёх порядков: в вашем, по ценности товара для цели ранжирования (сколько цели ранжирования в выбранной метрике приносят визиты за 30 дней, в которых товар смотрели, клали в корзину или покупали; у редко просматриваемого товара — ближе к его категории) или в порядке модели ранжирования по поведению посетителя. Каждую ночь ранжирование сравнивает их на своих же показах за неделю — по ценности цели ранжирования, пришедшей через клик, с поправкой на место, где товар был показан, — и показывает каждый порядок той доле посетителей, которая равна вероятности, что он лучший. До первого сравнения каждому достаётся треть (без обученной модели — половина вашему порядку и половина порядку ценности); доказанный выигрыш ведёт долю порядка к всем, проигрыш — к никому. Посетитель видит один и тот же порядок, пока доли не сдвинутся. Товар без оценки остаётся на своём месте. Возвращаются все присланные элементы, включая повторы. Без оценки остаются товары, которых Sales Ninja не узнал ни в смарт-фиде ранжирования, ни в каталоге проекта: новинки, которых ещё нет в фиде, опечатки в идентификаторе. Оценку не сохраняйте и не сравнивайте между посетителями.
При передаче списка показывайте элементы в порядке items. Для клика передавайте итоговый row.index; row.originalIndex связывает результат с исходным списком. Оба поля доступны в новом формате ответа: JSON — /bundle/product-ranking/v3, text/plain — /bundle/v2/product-ranking/v3. SDK выбирает его сам; прежние HTTP-адреса сохраняют старый смысл index.
Выдача из каталога
Странице категории не нужно присылать весь список: вместо items сайт называет фильтр и страницу, а ранжирование отвечает страницей лучших товаров своего смарт-фида в порядке для этого посетителя и общим числом найденных. Ранжирование, сохранённое без смарт-фида, берёт товары всего каталога проекта.
js
const pageSize = 24
const { items, total, trackImpression, trackClick } = await ninja('rankProducts', {
rankingId: 'RANKING_ID',
filter: { categoryIds: ['15'], params: { 'Размер': { values: ['42', '43'] } } },
limit: pageSize,
offset: (page - 1) * pageSize,
})
if (items.length) {
renderCards(items, (row) => trackClick(row.index))
renderPager(Math.ceil(total / pageSize))
trackImpression()
}| Параметр | Что передать |
|---|---|
limit | Сколько товаров на странице, от 1 до 2000 |
offset | Сколько товаров выдачи уже показано на прошлых страницах. По умолчанию 0 |
filter | Условия выдачи. Без него — весь каталог |
Поля фильтра объединяются через «и», значения внутри одного поля — через «или»:
| Поле | Что значит |
|---|---|
categoryIds | id категорий из фида; каждая берётся вместе со всеми подкатегориями |
brands | Бренды, без учёта регистра |
price | { from, to } — цена с включёнными границами; товар без цены не проходит |
inStock | true — только в наличии, false — только нет в наличии |
params | Параметры по имени из фида (<param name>): { values: [...] } — любое из значений, { range: { from, to } } — числовой диапазон |
Неизвестная категория, бренд или параметр дают пустую страницу и total: 0, а не ошибку: сайт мог передать то, чего нет в фиде.
Каждый item — объект { id, groupId }: id предложения из фида и group_id из фида; карточку товара сайт рисует по id из своего каталога. Варианты одного товара — например, размеры с общим group_id — приходят одной позицией, лучшим по порядку вариантом. total — сколько товаров прошло фильтр (варианты одного товара считаются одним), index — итоговое место товара в выдаче с учётом offset, а originalIndex — его место в отфильтрованной базовой выдаче до персональной перестановки.
Страницы, как правило, не повторяют и не теряют товары, даже если посетитель между ними смотрел другие товары: на первой странице выдачи скрипт запоминает в браузере поведение посетителя и отправляет его с каждой следующей страницей того же фильтра. Изредка следующую страницу отвечает другой сервер Sales Ninja, и тогда начало выдачи может сдвинуться: товар на стыке страниц повторится или пропадёт. Новая вкладка начинает выдачу заново. Скрипт запоминает контекст только для ответа, полученного вовремя: запоздавший ответ не меняет продолжение выдачи, даже если новая первая страница уже загрузилась.
При любом статусе, кроме ranked, и при таймауте items пустой — покажите свою выдачу. Контрольная группа A/B-теста тоже получает пустую выдачу со статусом ranked: так сравнивается порядок Sales Ninja с вашим. Ещё пустая выдача со статусом ranked значит, что фильтру не подошёл ни один товар. Первый запрос выдачи запускает загрузку каталога на сервере; пока она идёт, ответ — catalogUnavailable.
Показы, клики и A/B-тест
Результат содержит hitId и assignedVariant — группу посетителя в A/B-тесте: original (контрольная, исходный порядок) или personalized (ранжирование); none — решение принято вне теста. scoreSource сообщает, какой порядок фактически был получен. При таймауте отображается исходный список, а у выдачи — своя выдача сайта; поздний ответ ничего не меняет. Не сохраняйте готовый порядок для других посетителей или изменившегося набора товаров.
Вызов API сам по себе не считается показом. После фактического отображения списка вызовите result.trackImpression(groupIndex). Повторный вызов для того же результата сообщает тот же показ. Клик передавайте по index из результата, а не по id товара: один товар может встречаться дважды.
js
const result = await ninja('rankProducts', { rankingId: 'RANKING_ID', items: cards })
container.append(...result.items.map(({ item }) => item))
result.trackImpression()
for (const { item, index } of result.items) {
item.addEventListener('click', () => result.trackClick(index))
}Для нескольких групп передайте индекс группы в оба метода. Клики отправляются без ожидания, чтобы переход по ссылке не задерживался. Повторный реальный клик учитывается отдельно. После замены списка используйте методы нового результата и снимите обработчики прежнего списка. Показы и клики можно подтверждать также для исходного списка, возвращённого при ошибке или таймауте.
A/B-тест включается и выключается в редакторе ранжирования, там же задаётся доля контрольной группы. Скрипт запоминает группу посетителя в браузере и передаёт её в следующих запросах, поэтому посетитель остаётся в своей группе и после смены доли. Контрольная группа получает переданный порядок без пересчёта, а у выдачи — пустую страницу: сайт показывает свою. Статистика не обещает доставку каждого события: запросы без подтверждённого показа и несопоставленные события видны отдельно.
Статусы
status | Что значит | Что делать |
|---|---|---|
ranked | Порядок поставлен | Ничего |
rankingNotFound | Ранжирование с таким идентификатором не найдено в проекте или перенесено в архив | Проверьте идентификатор в редакторе ранжирования |
rankingStopped | Ранжирование остановлено в кабинете | Включите его в кабинете |
catalogUnavailable | Каталог проекта временно недоступен; у выдачи из каталога — ещё загружается после первого запроса | Повторите запрос позже |
timeout | Ответ не пришёл за timeout миллисекунд с момента вызова: исходный список без изменений, а у выдачи — пустая страница; поздний ответ не применяется | Задайте timeout по тому, сколько страница может ждать |
invalidRequest | Запрос отклонён: товаров в собственном списке больше 20 000, их признаков (id, адресов и названий вместе) больше 20 000 или идентификатор ранжирования не в формате из редактора | Проверьте запрос |
error | Сетевая или серверная ошибка | Ничего: страница работает с исходным порядком |
При любом статусе, кроме ranked, промис не отклоняется: он возвращает товары в исходном порядке без баллов, а у выдачи — пустую страницу, и сайт продолжает работать. Отклоняется он только при неверных аргументах — без rankingId; items не массив (например, NodeList без [...]); в items смешаны группы и отдельные товары; items вместе с limit; offset или filter без limit; offset не целое число от 0; getId не функция; timeout не конечное число или меньше 1 — и при вызове до init.
Если getId выбросит ошибку на каком-то товаре, этот товар просто останется без балла: остальные будут упорядочены.
Если ответ не успел
timeout — это обещание странице, а не только сети: отсчёт идёт с момента, когда скрипт Sales Ninja выполнил вызов rankProducts. Если за это время ответа нет, промис сразу возвращает исходный список без изменений — те же значения в том же порядке, без баллов — со статусом timeout. У выдачи из каталога вместо этого приходит пустая страница: покажите свою выдачу. Ответ, пришедший позже, не применяется.
Если вызов сделан до загрузки скрипта, он ждёт в очереди, а если скрипт заблокирован (блокировщик рекламы, недоступная сеть), не выполнится вовсе. Поэтому там, где страница ждёт порядок перед отрисовкой, поставьте свою страховку — так страница никогда не ждёт дольше, чем может себе позволить:
js
const ranked = await Promise.race([
ninja('rankProducts', { rankingId: 'RANKING_ID', items: products, timeout: 300 }),
new Promise((resolve) => setTimeout(() => resolve(null), 300)),
])
renderCatalog(ranked ? ranked.items.map(({ item }) => item) : products)Время ответа зависит от сети, поэтому timeout задавайте по тому, сколько страница может ждать перед первой отрисовкой.
Связано
Порционная отрисовка собственного списка (04.11.2026)
trackImpression(groupIndex, itemIndices) подтверждает только перечисленные итоговые row.index этого результата. Это позволяет ранжировать полный набор и рисовать его порциями: после каждой порции передайте индексы реально отрисованных карточек. Уже подтверждённые позиции того же результата повторно не отправляются; новые получают собственное время показа и тот же deliveryId группы. Невалидный индекс отклоняет вызов целиком. trackClick(row.index, groupIndex) сохраняет прежний контракт.
Без второго аргумента прежний вызов подтверждает всю группу и сохраняет идентичность повторного подтверждения. После первого частичного вызова такой вызов подтверждает оставшиеся позиции. supportsPartialImpressions: true в результате объявляет поддержку этого расширения; сайт, которому нужны частичные показы, при старом SDK сохраняет исходную выдачу. Формат событий не меняется; новый JS chunk не добавляется. Большие собственные списки: число элементов ограничено существующим бюджетом в 20 000 признаков; items/groups принимают до 20 000 элементов, но общий бюджет id/адресов/названий по-прежнему 20 000. У объекта с id и URL два признака. Предел страницы каталога и визуального разбора остаётся 2 000. SDK последовательно делит большие подтверждения показов по прежнему пределу события в 2 000, сохраняя позиции, deliveryId и идентичности повторов.