ДАРА Аналитика
Разделы документации

ДАРА АналитикаДокументацияПодключение к ДАРА

Подключение к ДАРА

Как подключить сайт аналитики к проекту ДАРА Рекомендаций (core.daratech.ru) — ключ API, идентификаторы пользователей, когда появляются данные и что они дают.

Если сайт работает с ДАРА Рекомендациями (core.daratech.ru), подключите к их проекту сайт аналитики. Тогда пол, возрастная группа, город, дети, компания, интересы и категории покупок пользователя из аналитики попадут в его профиль в ДАРА Рекомендациях и будут работать в выдаче.

Со стороны аналитики ничего нового нет: ДАРА Рекомендации запрашивают атрибуты посетителей через обычный API по ключу сайта — API: посетители. Персональные данные из аналитики туда не приходят, года рождения тоже нет — только возрастная группа.

Где включается подключение. Все настройки подключения — на стороне ДАРА Рекомендаций: поле для ключа, проверка ключа, отключение и удаление данных. В настройках проекта это вкладка «ДАРА Аналитика». Со стороны аналитики нужен только ключ API сайта. Названия полей, кнопок и статусов ниже — те, которые задают ДАРА Рекомендации; подробнее — в разделе «ДАРА Аналитика» их документации.

Какой сайт аналитики подключать

К проекту ДАРА Рекомендаций подключается один сайт аналитики: ключ API определяет сайт, и пользователи ищутся только среди посетителей этого сайта. Подключайте тот сайт, на страницах которого стоит тег и вызывается dara('user', {user_id}). Посетители и пользователи других ваших сайтов аналитики через этот ключ не находятся.

Как подключить

  1. Тег. Установите тег аналитики на сайт — см. Быстрый старт.

  2. Вход пользователя. Когда пользователь входит, вызовите на странице dara('user', {user_id}) с тем же user_id, который ваш сайт передаёт в ДАРА Рекомендации:

    dara('user', { user_id: 'u-501' });
    

    Вместо команды тега связь можно передать с сервера: запись POST /users с user_id и visitor_id — значением cookie _dara_a посетителя — связывает посетителя с пользователем так же. Подробнее — в разделе Данные о посетителях.

  3. Анонимные посетители. Сервер сайта передаёт в ДАРА Рекомендации значение cookie _dara_a полем analytics_id объекта user — вместе с другими идентификаторами пользователя. Так найдутся данные и о посетителе, который ещё не вошёл.

  4. Ключ. Ключ вы выпускаете сами в своём кабинете аналитики: настройки сайта, раздел «Ключи API» (ссылка на него есть и на странице «Интеграции»). Создайте отдельный ключ ak_… только для этого подключения, например с именем «Рекомендации». Полный ключ показывается один раз.

  5. Проект ДАРА Рекомендаций. В настройках проекта откройте вкладку «ДАРА Аналитика», введите ключ в поле «Ключ API сайта ДАРА Аналитики» и нажмите «Проверить и сохранить».

  6. ДАРА Отпечаток — по желанию. Чтобы данные искались и по id устройства, ДАРА Отпечаток должен быть подключён и к сайту аналитики — см. ДАРА Отпечаток, — и к проекту ДАРА Рекомендаций. Секретный ключ sk_… вы так же выпускаете сами в кабинете ДАРА Отпечатка и вводите его в обоих сервисах отдельно. Если ДАРА Отпечаток подключён только в одном из них, поиск по id устройства не работает: аналитика без своего подключения молча пропускает fingerprint_uuid.

Передача analytics_id в ДАРА Рекомендации

Поле analytics_id ДАРА Рекомендации принимают наравне с остальными идентификаторами пользователя. Значение — UUID из cookie _dara_a; строка не того вида отклоняется, а событие попадает в rejected с кодом invalid_user — ответ приёма событий при этом остаётся 202, как у любой принятой пачки.

Пример события для API ДАРА Рекомендаций с analytics_id:

curl -X POST https://core.daratech.ru/api/v1/events \
  -H "Authorization: Bearer $DARA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"id": "evt-88121", "type": "view", "item": "v-1042",
       "user": {"anonymous_id": "a-7f3c2e", "analytics_id": "0b7e6f8a-3c2d-4e5f-9a1b-2c3d4e5f6a7b"}}
    ]
  }'

На PHP значение берётся из cookie запроса — только если это UUID:

<?php
$user = ['user_id' => 'u-501', 'anonymous_id' => 'a-7f3c2e'];
$analyticsId = $_COOKIE['_dara_a'] ?? '';
if (is_string($analyticsId) && preg_match('/\A[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i', $analyticsId)) {
    $user['analytics_id'] = $analyticsId;
}
  • analytics_id не определяет пользователя сам по себе: запрос, в котором кроме него идентификаторов нет, считается запросом без пользователя. Передавайте его вместе с user_id или anonymous_id.
  • analytics_id привязывается к пользователю, которого ДАРА Рекомендации определили для запроса. Одному analytics_id соответствует один пользователь — последний пришедший.
  • При склейке анонима с аккаунтом analytics_id переходит к пользователю с user_id.

Ключ для ДАРА Рекомендаций

  • Чей ключ. Ключ принадлежит вам: вы выпускаете его в своём кабинете аналитики и сами вводите в настройках своего проекта ДАРА Рекомендаций. Общего ключа ДАРА, одного на все проекты, нет, и сотрудники ДАРА ключ за вас не вводят.

  • Отдельный ключ. Этот ключ не используйте в других программах: его можно сменить или отозвать, не трогая остальные интеграции, а по префиксу и дате последнего использования в списке «Ключи API» видно, что им пользуются именно ДАРА Рекомендации.

  • Смена ключа. Создайте новый ключ, введите его в проекте ДАРА Рекомендаций и нажмите «Проверить и сохранить». Когда новый ключ сохранится, отзовите старый в списке «Ключи API». Отозванный ключ перестаёт работать сразу, поэтому не отзывайте старый, пока новый не принят.

    Ключ определяет сайт аналитики, поэтому любой ДРУГОЙ ключ ДАРА Рекомендации считают сменой сайта: сохранённые данные о людях удаляются и запрашиваются заново. Отличить «тот же сайт» от «другого сайта того же клиента» по ответам API нельзя, а чужие данные в выдаче хуже суток без них. Тот же самый ключ, введённый повторно, ничего не сбрасывает.

  • Раскрытый ключ отзовите сразу и подключите новый так же.

  • ДАРА Рекомендации хранят ключ зашифрованным. В аналитике после создания видны только имя ключа, префикс и даты.

Проверка ключа

ДАРА Рекомендации проверяют ключ запросом POST /visitors/attributes со случайным UUID в visitor_id:

Ответ Результат
200 ключ действует, подключение сохраняется
401 ключ неверен или отозван
403 сайт аналитики недоступен: см. причины ниже
другой ответ аналитика недоступна

Ключ, который начинается не с ak_, ДАРА Рекомендации не принимают и подсказывают, где выпустить ключ: «Настройки сайта → Интеграции».

Причины 401 и 403:

Ответ Причина Что делать
401 ключ отозван в списке «Ключи API» или введён с ошибкой создать новый ключ и ввести его в проекте ДАРА Рекомендаций
403 сайт аналитики удалён — в течение 30 дней его можно восстановить восстановить сайт или подключить ключ другого сайта
403 сайт аналитики заблокирован администратором ДАРА связаться с поддержкой
403 учётная запись владельца сайта заблокирована или удалена связаться с поддержкой
403 запрос отправлен по http://, а не по https:// указать адрес https://analytics.daratech.ru/api/v1

403 обратим: после восстановления сайта или снятия блокировки тот же ключ снова отвечает 200. Отозванный ключ не восстанавливается — нужен новый.

После сохранения в проекте ДАРА Рекомендаций видны префикс ключа, дата подключения, время последнего ответа аналитики и доля пользователей, для которых нашлись данные. Если аналитика отвечает 401 или 403 или недоступна дольше часа, проект показывает предупреждение.

Какие данные запрашивают ДАРА Рекомендации

  • По каким идентификаторам: user_id пользователя; последний analytics_id, пришедший в его запросах; fingerprint_uuid — только если в проекте ДАРА Рекомендаций подключён ДАРА Отпечаток и id проверен.
  • Порядок поиска в аналитике: user_id → visitor_id → fingerprint_uuid, берётся первый найденный на сайте.
  • Когда: новый пользователь или новый идентификатор — в течение минуты. Если данных ещё нет, повторы через 5 минут и через час, дальше — раз в сутки. Данные пользователей с событиями за 7 дней обновляются раз в 24 часа. Обновление делает только фоновое задание ДАРА Рекомендаций по расписанию — запрос выдачи ничего не заказывает и обновления не ждёт.
  • Сколько: пачками до 100 пользователей и не больше 10 запросов в секунду на проект.
  • Какие значения: по правилам сети — своё значение сайта или сетевое, если сайт участник сети. Подробнее — в разделе Сеть ДАРА.
  • Страна приходит кодом ISO 3166-1 из двух букв, например RU, а регион и город — названиями.
  • Чувствительные темы. Раз в час ДАРА Рекомендации запрашивают GET /network. Если передача чувствительных тем выключена, интересы с sensitive: true не используются в выдаче и не показываются в их кабинете.

Свои и сетевые чувствительные темы

  • Выключенная передача чувствительных тем убирает из ответов аналитики только сетевые интересы с sensitive: true — source: network.
  • Свои чувствительные интересы — source: own, по наблюдениям ваших сайтов — аналитика отдаёт всегда, тоже с sensitive: true.
  • ДАРА Рекомендации при выключенной передаче не используют ни те, ни другие.

Когда появляются данные

Что Когда
пользователь находится по user_id после первого хита с dara('user', {user_id}) или записи POST /users — обычно в течение минуты
пол, возрастная группа, город, дети, компания из форм и данных вашего сайта в течение нескольких минут
интересы, категории покупок, город по IP после ежечасного пересчёта
сетевые значения через браузер сети вместе со своими значениями, без ожидания конца визита, — если сайт участник сети
сетевые значения через email или телефон после окончания визита, в котором их ввели, — по умолчанию через 30 минут без действий на сайте
сетевые значения нового сайта только после выхода из карантина; до этого — только свои значения
  • Найден, но без значений. Ответ {"ref": "u-501", "found": true, "attributes": {}} значит: пользователь или посетитель на сайте есть, а значений пока нет — ещё не посчитаны, есть только сетевые, а сайт на карантине, или посетитель отмечен как робот. Значения могут появиться позже по срокам таблицы.
  • Неизвестный пользователь — found: false: связи user_id с посетителем ещё нет или она не дошла до аналитики.
  • Кеш. Найденный пользователь кешируется в аналитике на 60 секунд: повтор раньше свежих данных не даст.

Как данные работают в выдаче

Данные аналитики хранятся в ДАРА Рекомендациях отдельно от данных, которые передал ваш сайт, а поле, переданное сайтом, важнее значения из аналитики. Как ДАРА Рекомендации используют данные сети — возраст, сегменты, интересы, контрольная группа, переключатель «Использовать данные сети в выдаче» — описано в разделе «ДАРА Аналитика» их документации.

Отключение и удаление

  • Отключить можно в настройках проекта ДАРА Рекомендаций. Данные аналитики сразу перестают влиять на выдачу и удаляются оттуда через 7 дней. Ключ после отключения отзовите в списке «Ключи API».
  • Подключить снова можно в любой момент, но это подключение заново: ключ вместе со строкой подключения при отключении удаляется, поэтому сохранённые данные о людях сбрасываются и запрашиваются у аналитики сызнова. Отключение обходится паузой, пока данные набираются, а не потерей.
  • Удаление пользователя в ДАРА Рекомендациях удаляет его данные аналитики там. В самой аналитике при этом ничего не удаляется.
  • Если аналитика недоступна, выдача и приём событий ДАРА Рекомендаций продолжают работать. Через час без ответа подключение получает статус unavailable, а проект показывает предупреждение.