События и заказы

Событие — действие посетителя с объектом. События формируют интересы пользователя, статистику объектов, пары «вместе» и метрики выдачи. То, что вы знаете о пользователе, но не является действием с объектом, передаётся профилем.

Приём событий: POST /events#

Тело — {"events": [...]}, до 1000 событий.

curl -X POST https://core.daratech.ru/api/v1/events \
  -H "Authorization: Bearer $DARA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": [
    {"id": "imp-91a7-0", "type": "impression", "item": "v-2210", "user": {"anonymous_id": "a-7f3c2e"},
     "recommendation_id": "01JC8Z6Q9W3M5N7P2R4T6V8X0Y", "surface": "feed", "position": 0},
    {"id": "like-u501-v2210", "type": "like", "item": "v-2210", "user": {"user_id": "u-501"}, "value": 1}
  ]}'

Ответ 202:

{"accepted": 2, "duplicates": 0, "rejected": []}

Каждое событие проверяется отдельно: неверные попадают в rejected, остальные принимаются.

Правила приёма:

• события по удалённым и недоступным объектам принимаются и участвуют в профилях;
• повторно присланное событие с тем же id не учитывается и попадает в duplicates;
• время события больше чем на 5 минут в будущем заменяется временем приёма;
• без подключения DARA Fingerprint поле fingerprint_uuid не учитывается: событие только с ним отклоняется no_user.

Типы событий: GET /event-types#

[{"code": "watch", "title": "Досмотр", "mode": "max", "weight": 1.0, "value_kind": "watch_seconds",
  "value_map": {"thresholds": [[0.1, -0.3], [0.5, 0.3], [0.8, 0.7]], "else": 1.0},
  "dedup_window_sec": 0, "suppress_similar_days": 0,
  "is_impression": false, "is_open": false, "is_goal": true, "is_purchase": false,
  "hides_item": false, "is_active": true}]

Типы, веса и флаги правятся в кабинете, во вкладке «Типы событий» проекта. Тип, по которому уже есть события, не удаляется, а отключается.

Пресеты#

Все пресеты начинают с impression (показ, вес 0) — показы нужны для метрик, статистики и усталости от повторных показов.

Видеохостинг

Магазин

Медиа

Пресет «Свой» содержит только impression и view, остальные типы вы добавляете сами.

Флаги:

• показ — объект показан в выдаче; сырые показы не хранятся, только агрегаты;
• открытие — переход к объекту; обнуляет счётчик показов без клика;
• цель — целевое действие для метрик («целевые события на 100 показов»);
• покупка — в этот тип раскладываются строки заказов; такой тип в проекте один;
• скрывает объект — объект больше не показывается этому пользователю.

Режимы учёта#

• fact — факты накапливаются. Повтор того же типа по тому же объекту от того же пользователя внутри окна дедупликации сохраняется, но не усиливает вклад: десять открытий одного ролика за час при окне 24 ч считаются одним.
• max — учитывается наибольшее значение: досмотр на 30 %, потом на 80 % — в профиле 80 %.
• state — действует последнее по времени значение. Лайк — value: 1, снятие лайка — value: 0: вклад обнуляется. Событие старше уже учтённого состояние не меняет.

Вклад пары «пользователь × объект × тип» затухает со временем: вес уменьшается вдвое за 30 дней (полураспад проекта). Для fact вклад растёт логарифмически от числа фактов, для max и state зависит от множителя по значению; у state затухание не опускается ниже 0,3.

Досмотр и дочитывание#

Для типов со значением watch_seconds и percent вовлечённость e переводится в множитель вклада:

• watch_seconds — в value передавайте, сколько секунд просмотрено. e — большее из двух долей: «просмотрено / длительность медиа» и «просмотрено / 300 с», но не больше 1. Пять минут просмотра приравниваются к досмотру длинного видео.
• percent — в value передавайте процент от 0 до 100, e = value / 100.

Отправляйте такое событие при закрытии плеера или страницы либо периодически во время просмотра — каждый раз с новым id: режим max оставит наибольшее значение. Объекты, досмотренные или дочитанные с множителем 0,7 и выше, 30 дней не показываются в ленте.

Показы#

• Отправляйте показы тем же POST /events пачками, с recommendation_id, surface и position.
• Показы дедуплицируются по id в течение 48 часов.
• Объект, трижды показанный без открытия, опускается в ленте ниже. Показы из выдачи без рекомендаций — без recommendation_id — служат базой для сравнения в метриках.

Заказы: POST /orders#

Заказ передаётся одним запросом: ДАРА раскладывает его на события типа с флагом «покупка».

curl -X POST https://core.daratech.ru/api/v1/orders \
  -H "Authorization: Bearer $DARA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ord-20931",
    "user": {"user_id": "u-501"},
    "occurred_at": "2026-09-14T15:20:00Z",
    "items": [
      {"item": "sku-3107", "quantity": 1, "price": 8900},
      {"item": "sku-2240", "quantity": 2, "price": 1200},
      {"item": "sku-9001", "quantity": 1, "price": 450, "title": "Пакет фирменный"}
    ]
  }'

{"order_id": "ord-20931", "accepted": 3, "rejected": []}

Правила:

• Одинаковые товары складываются. Строки с одним item дают одно событие: количество суммируется, цена — средневзвешенная.
• Строка → событие покупки. id события — o: и первые 32 символа hex SHA-256 от order_id и item; в событии order_id, quantity, price и value = quantity × price, если переданы оба.
• Повтор заменяет состав. Тот же order_id ещё раз: новые строки добавляются, пропавшие отменяются, дублей нет. Передавайте заказ целиком при каждом изменении.
• Отмена. "status": "cancelled" снимает вклад заказа: события помечаются отменёнными, сигналы и пары «вместе» пересчитываются.
• Один заказ — один способ. События покупки с order_id заказа из POST /orders, присланные через POST /events, отклоняются order_managed. Если строки заказа раньше пришли событиями, POST /orders с тем же order_id заменяет их.
• Товара нет в каталоге. Если в строке есть title, заводится недоступный объект с origin: order: он учитывается в профиле, но в выдачу не попадает, анализ медиа и сводка для него не запускаются. Позже PUT этого объекта сделает его обычным. Без title строка отклоняется unknown_item.
• В проекте нет типа с флагом «покупка» — ответ 422 с кодом no_purchase_type в details.

Перенос истории: POST /orders/batch#

До 500 заказов и не больше 5000 строк в сумме: {"orders": [...]}. Даты заказов — до 730 дней назад. Заказы обрабатываются независимо; ответ 202 — {"results": [...]} с результатом по каждому заказу.

Приглушение купленного#

У покупки в пресете «Магазин» срок приглушения 30 дней: купленный товар и товары с косинусной близостью 0,9 и выше к нему этот срок не показываются покупателю в ленте и похожих. Для товаров повседневного спроса поставьте в кабинете срок 0.

Пары «вместе»#

• Из заказов — товары из одного неотменённого заказа за 365 дней.
• Из сессий — объекты, которые один пользователь открыл или по которым совершил целевое действие в пределах 30 минут, за 30 дней.

Пара учитывается, когда её набрали не меньше трёх пользователей. Пары работают в ленте (reason: together), в похожих и в «дополните заказ» — похожих для нескольких товаров корзины.