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

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

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

Где включается подключение. Все настройки подключения — на стороне core: поле для ключа, проверка ключа, отключение и удаление данных. Поле ключа появляется в настройках проекта core вместе с выпуском поддержки ДАРА АНАЛИТИКИ в core; если его там ещё нет, подключение пока не включить. Со стороны аналитики нужен только ключ API сайта — он выпускается в кабинете аналитики уже сейчас. Названия полей, кнопок и статусов ниже — те, которые задаёт core; если в вашем проекте они называются иначе, ищите настройки подключения ДАРА АНАЛИТИКИ и документацию core.

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

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

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

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

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

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

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

3. Анонимные посетители. Сервер сайта передаёт в core значение cookie _dara_a полем analytics_id объекта user — вместе с другими идентификаторами пользователя. Так core найдёт данные и о посетителе, который ещё не вошёл. Поле analytics_id core начнёт принимать вместе с выпуском поддержки ДАРА АНАЛИТИКИ; пока её нет, событие с этим полем core отклоняет с кодом invalid_user. Добавляйте поле после того, как в настройках проекта core появится поле ключа.

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

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

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

Передача analytics_id в core#

Поле analytics_id core начнёт принимать вместе с выпуском поддержки ДАРА АНАЛИТИКИ. Пока её нет, событие с этим полем core отклоняет: ответ остаётся 200, но событие попадает в rejected с кодом invalid_user и не учитывается. Поэтому добавляйте поле в свой код после того, как в настройках проекта core появится поле ключа, — иначе работающая передача событий перестанет доходить.

Пример события для API core с 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 не определяет пользователя сам по себе: запрос, в котором кроме него идентификаторов нет, core считает запросом без пользователя. Передавайте его вместе с user_id или anonymous_id.
• analytics_id привязывается к пользователю, которого core определил для запроса. Одному analytics_id соответствует один пользователь — последний пришедший.
• При склейке анонима с аккаунтом analytics_id переходит к пользователю с user_id.

Ключ для core#

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

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

core проверяет ключ запросом POST /visitors/attributes со случайным UUID в visitor_id:

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

Причины 401 и 403:

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

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

Какие данные запрашивает core#

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

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

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

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

• Найден, но без значений. Ответ {"ref": "u-501", "found": true, "attributes": {}} значит: пользователь или посетитель на сайте есть, а значений пока нет — ещё не посчитаны, есть только сетевые, а сайт на карантине, или посетитель отмечен как робот. Значения могут появиться позже по срокам таблицы.
• Неизвестный пользователь — found: false: связи user_id с посетителем ещё нет или она не дошла до аналитики.
• Кеш. Найденный пользователь кешируется в аналитике на 60 секунд: повтор раньше свежих данных не даст.

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

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

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

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