Перейти к содержимому

Своя вёрстка — какие события передавать

Эта страница для тех, кто рисует поиск или блоки рекомендаций своим кодом через API, а не готовыми виджетами. Готовые виджеты отправляют все события сами. В своей вёрстке часть событий можете отправить только вы: о клике по товару и о том, из какого блока его положили в корзину, знает только ваш код.

Поиск и рекомендации работают и без этих событий. Но без них они не учатся на ваших покупателях, а в статистике не видно, сколько продаж они приносят.

Что вы передаёте Что без этого не работает
Клик по товару в выдаче и в подсказках Отчёт «Товар найден в поиске» (заказы с товаром, кликнутым в поиске), CTR и качество поиска, позиция первого клика, ранжирование с учётом кликов (формула «от наличия и поведенческих факторов»)
Один userId во всех запросах и событиях Поведенческий буст по запросам, персональные рекомендации, «Искали до покупки», A/B-тесты
queryId в поиске и в клике Связь клика с конкретной выдачей: какой запрос, какая позиция
rid и widgetId в событиях блока, атрибуция клика Продажи из рекомендаций по клику, сравнение виджетов и A/B-тестов по корзинам и покупкам, а не только по кликам
view_item, add_to_cart, purchase Персональные рекомендации, «С этим покупают», выручка в отчётах

Три идентификатора, которые всё связывают

Заголовок раздела «Три идентификатора, которые всё связывают»
  1. userId — один посетитель. Одно и то же значение во всех запросах /search, /completions, /widgets/{id}, в кликах, в widget-analytics и в user_id ecommerce-событий. Если на сайте стоит трекер, берите значение его cookie searchbooster_v2_user_id. Не генерируйте новый ID на сервере для каждого запроса.
  2. queryId — одна выдача поиска. Генерируйте его сами (UUID) при каждом новом запросе или смене фильтров. Передавайте в /search и в клик по товару из этой выдачи. Для следующих страниц той же выдачи оставляйте тот же queryId.
  3. 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. Трекер перенесёт поля 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-события.

  1. Откройте сайт, найдите товар через поиск и кликните по нему. В DevTools → Network должны уйти /search с queryId и userId и event/click.json с тем же queryId.
  2. Добавьте товар в корзину из блока рекомендаций. Должны уйти widget-analytics с click и requestId, затем datalayer.json с add_to_cart. Если на сайте стоит трекер, в нём будет widget_id.
  3. Возьмите свой userId (cookie searchbooster_v2_user_id или ваш ID) и откройте его в личном кабинете, в разделе «Покупатели». В одной сессии должны быть поиск, клик в выдаче, клик в блоке, просмотр карточки и корзина. Если события разошлись по разным покупателям, значит, userId в них разный.