ДАРА
Кабинет Оставить заявку
Разделы документации

ДокументацияНачало

Понятия

Проект, объект и медиа, шаги анализа, типы событий, конечные пользователи и их идентификаторы, поверхность и снимок выдачи.

Проект

Проект — один сайт или приложение. Ключ API принадлежит проекту и определяет его, поэтому отдельного project_id в запросах нет. У проекта свои:

  • объекты, пользователи, события и заказы — данные разных проектов не смешиваются, профили между проектами не переносятся;
  • модели анализа по задачам: речь, кадры, сводка, векторы — облачные или локальные на выбор;
  • типы событий с весами — из пресета, их можно менять в кабинете;
  • настройки обработки и выдачи: язык, интервал кадров, фильтруемые свойства объектов, фильтр по возрасту, доля контрольной группы.

Пресет выбирается при создании проекта:

Пресет Для чего Типы событий
Видеохостинг ролики, каналы, подписки impression, view, watch, like, comment, subscribe, report
Магазин товары, корзина, заказы impression, view, favorite, cart, purchase, not_interested
Медиа статьи, новости, посты impression, view, read, like, share, comment
Свой своя модель событий impression, view; остальные типы добавляются в кабинете

Объект и медиа

Объект — то, что попадает в выдачу: ролик, товар, статья, трек, изображение.

  • id — ваш идентификатор объекта, строка до 191 символа;
  • type — video, image, audio, text или mixed;
  • текст — title, description, body;
  • author — id автора у вас: канал, бренд, редакция. Нужен для близости к авторам и разнообразия выдачи;
  • properties — свойства объекта: цена, категория, наличие. Свойства, отмеченные в проекте фильтруемыми, работают в фильтрах выдачи;
  • media — файлы по ссылкам https: video, audio, image;
  • available — можно ли показывать объект в выдаче.

Объект попадает в выдачу, только если он доступен, не удалён и у него есть хотя бы один вектор.

Шаги анализа

Шаг Что делает
prepare подготовка медиа: длительность, звуковая дорожка, кадры
speech распознавание речи — транскрипт с таймкодами
vision кадры и изображения: что в кадре, текст в кадре, флаги безопасности
summary сводка: описание, темы, теги, сущности, язык, возрастная отметка, модерация
embedding векторы смысла для ленты, похожих и поиска

Для речи, кадров и сводки в проекте можно выбрать «Не выполнять» — шаг получит skipped, а сводка и векторы построятся по тому, что есть. Векторы строятся всегда. Сразу после создания объекта считается быстрый вектор по заголовку и описанию: новый объект участвует в похожих ещё до конца анализа.

Тип события

Тип события — код действия (view, like, purchase) и правила его учёта:

  • режим — fact: факты накапливаются (открытия, комментарии); max: учитывается наибольшее значение (досмотр); state: действует последнее значение (лайк и его снятие);
  • вес — вклад в интересы пользователя; бывает отрицательным (жалоба, «не интересно»);
  • вид значения — none, number, percent, watch_seconds;
  • флаги — показ, открытие, цель, покупка, скрывает объект.

Подробно — в разделе События и заказы.

Конечный пользователь

Конечный пользователь — посетитель вашего сайта. Он известен ДАРА только по идентификаторам в объекте user:

Поле Что это Формат
user_id аккаунт на вашем сайте строка до 191 символа
anonymous_id браузер или устройство; id выдаёт ваш сайт, например в cookie до 191 печатного символа ASCII
fingerprint_uuid visitor_uuid DARA Fingerprint; учитывается, только если в проекте подключён DARA Fingerprint UUID

Когда посетитель входит на сайте, вызовите POST /users/link — история анонима перейдёт в аккаунт. Подробно — в разделе Пользователи.

Кроме действий, можно передавать то, что вы знаете о пользователе: интересы, год рождения, город, любимых и скрытых авторов. Это данные о пользователях.

Поверхность

Поверхность (surface) — место на сайте, где показана выдача: feed, similar, next, cart. Значение свободное, до 16 символов. Передавайте его в событиях показа и открытия: метрики считаются по поверхностям.

Снимок выдачи

Каждая выдача ленты, похожих, переранжирования и поиска сохраняется снимком, его id — recommendation_id: ULID из 26 символов.

  • Следующие страницы ленты берутся из снимка, пока он жив (30 минут), — без повторов и пропусков.
  • recommendation_id в событиях связывает клики и досмотры с выдачей, из которой пришёл пользователь.
  • Показы без recommendation_id — например, хронологической ленты вашего сайта — образуют базу для сравнения выдачи с рекомендациями и без.

Режим выдачи и определение пользователя

В ответах выдачи поле mode:

  • personal — у пользователя достаточно истории или указанных вами интересов;
  • cold — новый посетитель или отказ от персонализации: тренды, качество, свежесть, популярное в сегменте пользователя;
  • fallback — запасной ответ, когда подбор не успел или не из чего подбирать: популярное проекта.

Поле identity показывает, как определён пользователь: user — по user_id, recognized — узнан без входа, anonymous — по анонимным идентификаторам, none — пользователь не передан.