Своя вёрстка — какие события передавать
Эта страница для тех, кто рисует поиск или блоки рекомендаций своим кодом через API, а не готовыми виджетами. Готовые виджеты отправляют все события сами. В своей вёрстке часть событий можете отправить только вы: о клике по товару и о том, из какого блока его положили в корзину, знает только ваш код.
Поиск и рекомендации работают и без этих событий. Но без них они не учатся на ваших покупателях, а в статистике не видно, сколько продаж они приносят.
Что даёт каждое событие
Заголовок раздела «Что даёт каждое событие»| Что вы передаёте | Что без этого не работает |
|---|---|
| Клик по товару в выдаче и в подсказках | Отчёт «Товар найден в поиске» (заказы с товаром, кликнутым в поиске), CTR и качество поиска, позиция первого клика, ранжирование с учётом кликов (формула «от наличия и поведенческих факторов») |
Один userId во всех запросах и событиях |
Поведенческий буст по запросам, персональные рекомендации, «Искали до покупки», A/B-тесты |
queryId в поиске и в клике |
Связь клика с конкретной выдачей: какой запрос, какая позиция |
rid и widgetId в событиях блока, атрибуция клика |
Продажи из рекомендаций по клику, сравнение виджетов и A/B-тестов по корзинам и покупкам, а не только по кликам |
view_item, add_to_cart, purchase |
Персональные рекомендации, «С этим покупают», выручка в отчётах |
Три идентификатора, которые всё связывают
Заголовок раздела «Три идентификатора, которые всё связывают»userId— один посетитель. Одно и то же значение во всех запросах/search,/completions,/widgets/{id}, в кликах, вwidget-analyticsи вuser_idecommerce-событий. Если на сайте стоит трекер, берите значение его cookiesearchbooster_v2_user_id. Не генерируйте новый ID на сервере для каждого запроса.queryId— одна выдача поиска. Генерируйте его сами (UUID) при каждом новом запросе или смене фильтров. Передавайте в/searchи в клик по товару из этой выдачи. Для следующих страниц той же выдачи оставляйте тот жеqueryId.rid+widgetId— один ответ блока рекомендаций.ridприходит в ответе/widgets/{id}. Передавайте его какrequestIdвshowиclickи в атрибуцию клика.
Чек-лист
Заголовок раздела «Чек-лист»| Когда | Что отправить | Обязательно |
|---|---|---|
| Поиск, подсказки, блок рекомендаций | GET /search, /completions, /widgets/{id} |
userId; для поиска — queryId |
| Клик по товару в выдаче | /event/click.json, type=productClick |
entityId, queryId, userId, params.pos |
| Клик по товару в подсказках | /event/click.json, type=productClickCompletions |
entityId, userId |
| Оценка выдачи по запросу | /event/click.json, type=feedback, params.vote = 1 или -1 |
queryId, userId, params.vote |
| Блок рекомендаций получил товары | widget-analytics, generate |
widgetId, requestId, userId |
| Блок попал в видимую область | widget-analytics, show |
widgetId, requestId, itemIds, userId |
| Клик или «В корзину» в блоке | widget-analytics, click и запись атрибуции |
widgetId, requestId, itemIds, userId |
| Карточка товара, корзина, покупка | view_item, add_to_cart, purchase — трекером или datalayer.json |
user_id, items[].item_id; у покупки transaction_id, value |
Запрос выдачи с queryId и userId:
const queryId = crypto.randomUUID();const url = new URL(`https://api.searchbooster.net/api/${UUID}/search`);url.search = new URLSearchParams({ query, limit: '24', skip: '0', userId, queryId });const data = await fetch(url).then((r) => r.json());Клик по товару. pos — позиция товара в выдаче, с 1, с учётом страницы. sendBeacon не теряет событие при переходе на карточку:
function trackSearchClick(offer, position) { navigator.sendBeacon( `https://api.searchbooster.net/api/${UUID}/event/click.json`, new URLSearchParams({ type: 'productClick', // в подсказках — productClickCompletions entityId: String(offer.id), queryId, userId, regionId, params: JSON.stringify({ offerId: String(offer.id), pos: position }), }), );}sendBeacon отправляет POST с телом application/x-www-form-urlencoded, API принимает его так же, как GET с параметрами в адресе. Все параметры клика — в разделе События.
Оценка выдачи
Заголовок раздела «Оценка выдачи»Палец вверх или вниз под результатами поиска — клик с type=feedback. В params передаются vote
(1 или -1, обязательно), comment (необязательно) и query; каждый текст до 1000 символов. Оценки видны
в кабинете: «Статистика» → «Оценки».
function trackSearchFeedback(vote, comment = '') { navigator.sendBeacon( `https://api.searchbooster.net/api/${UUID}/event/click.json`, new URLSearchParams({ type: 'feedback', queryId, userId, regionId, params: JSON.stringify({ vote, comment, query }), }), );}Блоки рекомендаций
Заголовок раздела «Блоки рекомендаций»const res = await fetch( `https://api.searchbooster.net/api/${UUID}/widgets/${WIDGET_ID}?userId=${userId}&id=${productId}`,).then((r) => r.json());const rid = res.rid;const base = { widgetId: WIDGET_ID, userId, requestId: rid, regionId, pathname: location.pathname };
const send = (events) => fetch(`https://api.searchbooster.net/api/${UUID}/widget-analytics`, { method: 'POST', headers: { 'Content-Type': 'text/plain;charset=UTF-8' }, body: JSON.stringify(events), keepalive: true, });
send([{ ...base, event: 'generate', itemIds: res.offers.map((o) => String(o.id)) }]);
// show — когда блок попал в видимую область, один раз на ответnew IntersectionObserver(([entry], observer) => { if (!entry.isIntersecting) return; observer.disconnect(); send([{ ...base, event: 'show', itemIds: res.offers.map((o) => String(o.id)) }]);}).observe(blockElement);
// click — по товару или «В корзину» в блокеfunction onRecClick(offer) { send([{ ...base, event: 'click', itemIds: [String(offer.id)] }]); rememberWidgetClick(WIDGET_ID, rid, offer); // атрибуция, ниже}widgetId — число. Подробнее о полях — API статистики рекомендаций.
Атрибуция кликов в блоке
Заголовок раздела «Атрибуция кликов в блоке»Покупка обычно происходит на другой странице, иногда через несколько дней. Чтобы она засчиталась блоку, запомните клик. Если на сайте стоит трекер, достаточно записать клик в localStorage в том же формате, что используют готовые виджеты. Трекер сам проставит widget_id в add_to_cart этого товара в течение 24 часов, в begin_checkout и purchase — в течение 7 дней:
function rememberWidgetClick(widgetId, rid, offer) { const key = `sb_widget_attribution_${UUID}`; const now = Date.now(); let records = []; try { records = JSON.parse(localStorage.getItem(key) || '[]'); } catch {} records = records .filter((r) => now - r.ts < 7 * 24 * 3600 * 1000) .filter((r) => !(r.widgetId === widgetId && r.itemId === String(offer.id))); records.push({ widgetId, // число rid, // rid из ответа /widgets/{id} itemId: String(offer.id), // id товара, как в фиде groupId: offer.groupId ? String(offer.groupId) : undefined, // если покупают другой вариант той же группы ts: now, // миллисекунды }); localStorage.setItem(key, JSON.stringify(records.slice(-50)));}Если трекера нет или корзину и покупку вы отправляете с сервера, передайте атрибуцию в событии сами — пример ниже.
Корзина и покупка
Заголовок раздела «Корзина и покупка»Трекер читает ваш dataLayer
Заголовок раздела «Трекер читает ваш dataLayer»Если вы знаете, из какого блока добавлен товар, можно передать это явно в своём событии dataLayer. Трекер перенесёт поля widget_id, item_list_id и item_list_name в событие SearchBooster. Их можно положить на верхний уровень события или в ecommerce. Явные значения важнее записи из localStorage.
dataLayer.push({ event: 'add_to_cart', widget_id: 402, // товар добавлен из блока 402 item_list_id: 'sb_widget_402', item_list_name: rid, // rid ответа блока ecommerce: { currency: 'RUB', items: [{ item_id: '1077', item_name: 'Сыр Российский', item_category: 'Сыры', price: 219, quantity: 1, index: 3 }], },});События с сервера или из приложения
Заголовок раздела «События с сервера или из приложения»curl -X POST 'https://api.searchbooster.net/api/{uuid}/event/datalayer.json' \ -H 'Content-Type: text/plain;charset=UTF-8' \ --data-raw '{ "event": "purchase", "user_id": "<тот же userId, что в поиске>", "session_id": "s-20261110-1", "transaction_id": "T-991", "value": 438, "currency": "RUB", "widget_id": 402, "items": [ { "item_id": "1077", "item_category": "Сыры", "price": 219, "quantity": 2, "item_list_id": "sb_widget_402", "item_list_name": "<rid>" } ] }'transaction_id— номер заказа. Без него не открыть заказ в разделе «Покупатели» и не отличить повторную отправку той же покупки.widget_id— только если заказ пришёл из блока рекомендаций. Не ставьте его всем покупкам подряд.item_idдолжен совпадать сidтовара в фиде, иначе событие не свяжется ни с выдачей, ни с блоком.
Полный список полей — Ecommerce-события.
Как проверить
Заголовок раздела «Как проверить»- Откройте сайт, найдите товар через поиск и кликните по нему. В DevTools → Network должны уйти
/searchсqueryIdиuserIdиevent/click.jsonс тем жеqueryId. - Добавьте товар в корзину из блока рекомендаций. Должны уйти
widget-analyticsсclickиrequestId, затемdatalayer.jsonсadd_to_cart. Если на сайте стоит трекер, в нём будетwidget_id. - Возьмите свой
userId(cookiesearchbooster_v2_user_idили ваш ID) и откройте его в личном кабинете, в разделе «Покупатели». В одной сессии должны быть поиск, клик в выдаче, клик в блоке, просмотр карточки и корзина. Если события разошлись по разным покупателям, значит,userIdв них разный.