ДАРА АналитикаДокументацияПодключение к ДАРА
Подключение к ДАРА
Как подключить сайт аналитики к проекту ДАРА Рекомендаций (core.daratech.ru) — ключ API, идентификаторы пользователей, когда появляются данные и что они дают.
Если сайт работает с ДАРА Рекомендациями (core.daratech.ru), подключите к их проекту сайт аналитики. Тогда пол, возрастная группа, город, дети, компания, интересы и категории покупок пользователя из аналитики попадут в его профиль в ДАРА Рекомендациях и будут работать в выдаче.
Со стороны аналитики ничего нового нет: ДАРА Рекомендации запрашивают атрибуты посетителей через обычный API по ключу сайта — API: посетители. Персональные данные из аналитики туда не приходят, года рождения тоже нет — только возрастная группа.
Где включается подключение. Все настройки подключения — на стороне ДАРА Рекомендаций: поле для ключа, проверка ключа, отключение и удаление данных. В настройках проекта это вкладка «ДАРА Аналитика». Со стороны аналитики нужен только ключ API сайта. Названия полей, кнопок и статусов ниже — те, которые задают ДАРА Рекомендации; подробнее — в разделе «ДАРА Аналитика» их документации.
Какой сайт аналитики подключать
К проекту ДАРА Рекомендаций подключается один сайт аналитики: ключ API определяет сайт, и пользователи ищутся только среди посетителей этого сайта. Подключайте тот сайт, на страницах которого стоит тег и вызывается dara('user', {user_id}). Посетители и пользователи других ваших сайтов аналитики через этот ключ не находятся.
Как подключить
-
Тег. Установите тег аналитики на сайт — см. Быстрый старт.
-
Вход пользователя. Когда пользователь входит, вызовите на странице
dara('user', {user_id})с тем жеuser_id, который ваш сайт передаёт в ДАРА Рекомендации:dara('user', { user_id: 'u-501' });Вместо команды тега связь можно передать с сервера: запись
POST /usersсuser_idиvisitor_id— значением cookie_dara_aпосетителя — связывает посетителя с пользователем так же. Подробнее — в разделе Данные о посетителях. -
Анонимные посетители. Сервер сайта передаёт в ДАРА Рекомендации значение cookie
_dara_aполемanalytics_idобъектаuser— вместе с другими идентификаторами пользователя. Так найдутся данные и о посетителе, который ещё не вошёл. -
Ключ. Ключ вы выпускаете сами в своём кабинете аналитики: настройки сайта, раздел «Ключи API» (ссылка на него есть и на странице «Интеграции»). Создайте отдельный ключ
ak_…только для этого подключения, например с именем «Рекомендации». Полный ключ показывается один раз. -
Проект ДАРА Рекомендаций. В настройках проекта откройте вкладку «ДАРА Аналитика», введите ключ в поле «Ключ API сайта ДАРА Аналитики» и нажмите «Проверить и сохранить».
-
ДАРА Отпечаток — по желанию. Чтобы данные искались и по 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, а проект показывает предупреждение.