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

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

Понятия

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

Проект

Проект — один сайт или приложение. Ключ 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
analytics_id посетитель ДАРА АНАЛИТИКИ — значение её cookie _dara_a; принимается всегда, но пользователя не определяет UUID

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

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

Поверхность

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

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

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

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

Подробно — Рекомендации → Пагинация.

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

В ответах ленты и похожих поле mode:

  • personal — у пользователя достаточно истории или указанных вами интересов: выдача по его профилю;
  • cold — новый посетитель, user не передан или пользователь отказался от персонализации: тренды, популярное, новое, текущая сессия, популярное в сегменте пользователя;
  • fallback — запасная выдача: подбор не уложился во время ответа, индекс проекта загружается или объекта для похожих нет в ДАРА. Объекты — из трендового или популярного списка проекта, reason — trending или popular.

Поле identity во всех ответах выдачи и поиска показывает, как определён пользователь:

identity Как определён
user передан user_id
recognized без user_id, узнан без входа по DARA Fingerprint
anonymous по anonymous_id или проверенному fingerprint_uuid, в том числе ещё неизвестным ДАРА
none user не передан или в нём нет учитываемых идентификаторов

Запрос выдачи пользователей не создаёт. Полные правила — Рекомендации → Поля ответа.