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

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)**.

1. Пользователь совершает **вход/регистрацию** на сайте или в приложении.
2. Отправляется событие `login-v1` или `signup-v1`.
3. В свойствах события (`props`) передается `cuid` и `cuidType`. **В качестве CUID рекомендуется использовать хеш номера телефона.**
4. Платформа находит все профили с этим `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`). Он используется для поиска существующего внутреннего профиля.

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

1.  **Автоматическое управление (без user.id):**
    Если вы не передаете `user.id` и не передаете `uid`, платформа автоматически создаст нового пользователя и вернет его `uid` (в объекте `session.sl`). Этот `uid` необходимо сохранить (в cookie или локальном хранилище) и передавать в последующих запросах.
2.  **Использование внешнего 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 склеит соответствующие анонимные профили в единый омниканальный профиль клиента.