# 🆔 Идентификация и омниканальный профиль

Gravity Field обеспечивает создание Единого Профиля Клиента, объединяя данные из разных источников: Web, Mobile App и оффлайн покупки.

В этом разделе описаны механизмы идентификации, роль различных ID и технические детали склейки профилей.

# 🕵️ Как мы узнаем пользователя?

На базовом уровне платформа присваивает каждому посетителю внутренний идентификатор (UID). Он используется для отслеживания поведения в рамках одного устройства или браузера.

# Web (Cookies)

В браузере используются следующие cookie:

_slid: Основной идентификатор пользователя (Client-side).
_slid_server: Серверный идентификатор (Server-side), используется для поддержки ITP и долгосрочного хранения.
_slsession: Идентификатор текущей сессии.

# API / Mobile App

При работе через API или SDK используется параметр uid (или slid в некоторых запросах). Если uid не передан, сервер сгенерирует новый UID.

# 🔄 Как работает омниканальность (Склейка профилей)?

Чтобы объединить профили с разных устройств (ноутбук, телефон, планшет), используется CUID (Customer User ID).

Пользователь совершает вход/регистрацию на сайте или в приложении.
Отправляется событие login-v1 или signup-v1.
В свойствах события (props) передается cuid и cuidType. В качестве CUID рекомендуется использовать хеш номера телефона.
Платформа находит все профили с этим cuid и объединяет их с текущим анонимным профилем (uid).

# Зачем это нужно?

Требуется для реализации ключевых бизнес-сценариев:

Объединение профилей из разных источников: Однозначная связка, что пользователь на сайте (Web) и в мобильном приложении (Mobile App) — это один и тот же человек.
ROPO (Research Online, Purchase Offline): Отслеживание совершения офлайн-покупки и связывание её с онлайн-историей пользователя.
Интеграция с CDP и CVM: Обеспечение единого ключа для обмена данными и сегментами в двустороннем порядке.
Обмен сегментами: Использование сегментов маркетинга и лояльности для таргетинга в Gravity Field (например, для показа персональных VIP-кампаний).

В результате история действий на новом устройстве "приклеивается" к единому профилю клиента.

# Валидация событий

Для событий login-v1 и signup-v1 на сервере действует строгая валидация. В props обязательно должно присутствовать хотя бы одно из полей:

cuid (вместе с cuidType)
hashedEmail

Если ни одного из них нет, API вернет ошибку 422 Unprocessable Entity.

# ⚙️ Техническая разница между user.id и cuid

В Server-Side API интеграции часто возникает путаница между двумя параметрами: user.id (в блоке user) и cuid (в свойствах событий). Это разные сущности с разным назначением.

# 1. user.id (extUid) — "Ключ поиска или автогенерации"

Это идентификатор пользователя в вашей системе (внутренний ID, ID из CRM), который вы передаете в блоке user (параметр id). Он используется для поиска существующего внутреннего профиля.

Возможные сценарии использования:

Автоматическое управление (без user.id): Если вы не передаете user.id и не передаете uid, платформа автоматически создаст нового пользователя и вернет его uid (в объекте session.sl). Этот uid необходимо сохранить (в cookie или локальном хранилище) и передавать в последующих запросах.
Использование внешнего ID: Если у вас есть свой идентификатор, вы можете передавать его в user.id. В этом случае платформа будет искать профиль по этому значению. Важно: При использовании user.id вы также должны самостоятельно управлять сессиями, передавая session.custom (ваш ID сессии), чтобы обеспечить непрерывность истории.

# 2. cuid — "Атрибут профиля"

Это устойчивый идентификатор клиента (хеш телефона, email), который хранится в профиле.

Назначение: Склейка профилей и кросс-девайс трекинг.
Как задается: Передается в свойствах (props) событий login-v1 или signup-v1.

# ❓ FAQ

Q: Какой cuidType использовать? A: Рекомендуемый тип — phone_hash (SHA-256 хеш нормализованного телефона). Это обеспечивает наилучшую склейку профилей.

Q: Что будет, если пользователь почистит куки или зайдёт в режиме инкогнито — мы сможем его узнать?
A: Базовый анонимный идентификатор (slid в Web и uid в App/API) хранится в cookie/локальном хранилище и привязан к конкретному браузеру/устройству. Если пользователь очищает куки, использует режим инкогнито или заходит с нового браузера, для него создаётся новый анонимный профиль. Как только он авторизуется и вы передадите cuid в событиях login-v1/signup-v1, история новых визитов будет "приклеена" к единому омниканальному профилю.

Q: У нас уже есть собственная система авторизации на сайте. Можно ли использовать наш ID вместо отдельного cuid?
A: Формально можно, но рекомендуется использовать именно хеш телефона в качестве cuid. Внутренний ID на сайте часто не совпадает с идентификаторами в CDP, CRM или офлайн-системах, поэтому по нему будет сложно надёжно склеивать профили между каналами. Хеш телефона даёт стабильный, кросс-системный идентификатор.

Q: Что произойдёт в браузерах, которые ограничивают работу cookie (Chrome, Safari с ITP и т.п.) — не сломается ли идентификация?
A: Gravity Field использует в первую очередь first‑party cookie на вашем домене, поэтому в стандартных режимах работы браузера идентификация сохраняется. В условиях жёстких ограничений (ITP, приватный режим, корпоративные политики) срок жизни и стабильность cookie могут уменьшаться — в таких случаях особенно важно использовать cuid и/или user.id при авторизации, чтобы восстанавливать связь с профилем даже при потере анонимного идентификатора.

Q: У одного пользователя два устройства или два браузера. Значит ли это, что у него будет два разных профиля?
A: На уровне анонимного трекинга действительно будут разные slid/uid для каждого устройства или браузера. Но как только пользователь авторизуется на каждом из них с одним и тем же cuid, Gravity Field склеит соответствующие анонимные профили в единый омниканальный профиль клиента.