# Объекты полей посетителя

В **Webim** поля посетителя могут приходить из разных источников и использоваться в разных сценариях. Для этих данных предусмотрено несколько объектов. Их не следует объединять в один объект на стороне интеграции: у них разные роли и правила использования.

В этой статье описано, для чего предназначен каждый объект, из каких полей он обычно состоит и как группы сливаются на сервере.

## Источники и приоритет

Сведения об одном и том же посетителе могут одновременно поступать из нескольких мест. На стороне **Webim** они хранятся в виде **групп полей** (отдельных массивов). Сервер объединяет группы в итоговый набор. Как выбирается значение при совпадении имён, описано в разделе [«Приоритет групп полей»](#visitor-fields-priority).

### Откуда приходят данные

| Группа | Откуда берётся |
|--------|----------------|
| `provided_fields` | Интеграция передаёт данные авторизованного посетителя: объект `webim_visitor` на странице, метод `provide_visitor_fields` в **Webim Realtime API**, метод `setVisitorFieldsJson` в Android SDK и метод `set(visitorFieldsJSONString:)` в iOS SDK. |
| `fields` | Посетитель указал данные сам: форма перед началом чата, форма офлайн-сообщения и форма запроса контактов в виджете, а также каналы-мессенджеры. Эти данные не подписываются и не проверяются. |
| `opFields` | Значения, которые [оператор внёс или изменил в РМО](https://webim.ru/kb/control-panel/sections.html#info-visitor) в ходе диалога. |

!!! Note "N.B."
    Как `provided_fields` называется в JSON и в Realtime API, см. в разделе [`provided_fields`](#provided_fields).

### Приоритет групп полей { #visitor-fields-priority }

Если одно и то же поле (например, телефон) задано в нескольких группах по-разному, в итоговый набор попадает одно значение.

| Где применяется | Как определяется порядок |
|-----------------|--------------------------|
| Боты, первое сообщение диалога и прочая серверная логика модели посетителя | Параметр `visitor_fields_priority_order` в [настройках аккаунта (account config)](https://webim.ru/kb/for-admins/service-pages/account-config-editor.html): имена групп от наиболее приоритетной к наименее. По умолчанию `["providedFields","fields","opFields"]` — сначала `provided_fields`, затем `fields`, затем `opFields`. Имя по умолчанию (в русской локали — «Посетитель») не заменяет уже заданное `name`. Поле `display_name` из `provided_fields` попадает в набор как `name`. |
| Методы диалогов **Stored Data API** (список и один диалог, версии 2, 3 и 4) | Параметр `visitor_fields_priority_order` не читается. Порядок фиксированный: `fields`, затем `provided_fields`, затем `opFields`. Более поздняя группа перекрывает предыдущую. Имя по умолчанию в ответ не записывается, даже если другого `name` нет. Поле `display_name` из любой группы попадает в ответ как `name`. |
| Карточка посетителя в РМО | Правки оператора (`opFields`) перекрывают остальные группы независимо от `visitor_fields_priority_order`. Поле `display_name` переименовывается в `name` только в `provided_fields`. |

Не все поля посетителя отображаются в РМО во время диалога. Не показанные в панели данные сохраняются в системе и при необходимости передаются интеграциям и в API в полном объёме.

!!! Note "N.B."
    Имя, которое сервер подставляет как имя отправителя в сообщениях, уведомлениях и каналах, считается отдельно и не зависит от `visitor_fields_priority_order`. Берётся `display_name` из `provided_fields`, а если его нет — `name` из `fields`. Группа `opFields` в этот выбор не входит: правка имени оператором в РМО не меняет имя отправителя в истории сообщений и в каналах.

Состав групп может отличаться. Обязательным является только `id` в [`provided_fields`](#provided_fields). В `fields` и `opFields` обязательных полей нет. Почему `id` не стоит передавать в `fields`, см. [ниже](#fields).

Разделы ниже устроены одинаково: назначение, состав, обязательные поля, особенности.

## fields { #fields }

### Назначение

`fields` — данные, которые посетитель указал сам в ходе обращения, без подписи со стороны внешней системы. **Webim** не проверяет их достоверность.

### Состав

Сюда попадают:

  * данные из формы перед началом чата и формы офлайн-сообщения в виджете;

  * данные из формы запроса контактов в виджете;

  * данные, полученные из каналов-мессенджеров (например, номер телефона).

Обычные поля форм виджета — `name`, `email` и `phone`. Набор задаётся формой и может не совпадать с набором `provided_fields`. Если посетитель не указал имя, **Webim** подставляет имя по умолчанию.

### Обязательные поля

Обязательных полей нет.

Поле `id` в `fields` не делает посетителя авторизованным. Для идентификации используется только `provided_fields.id`. Указывать `id` в `fields` не стоит:

  * в наборе для ботов, первого сообщения диалога и прочей серверной логики модели посетителя значение берётся по `visitor_fields_priority_order`. По умолчанию выше группа `provided_fields`, и `id` из `fields` в набор не попадает;

  * если в этой настройке группа `fields` стоит выше `providedFields`, `id` из `fields` перекроет `provided_fields.id`;

  * в методах диалогов **Stored Data API** `provided_fields.id` перекрывает `id` из `fields` при любом значении настройки.

### Особенности

Не путайте серверную группу `fields` со свойством `fields` объекта `webim_visitor`. Разница описана в статье [Идентификация через передачу подписанных полей, версия 2.0](https://webim.ru/kb/dev/identification/id-2-0.html#webim-visitor-format).

## provided_fields { #provided_fields }

### Назначение

`provided_fields` — поля авторизованного посетителя, которые интеграция передаёт со стороны клиента. По ним **Webim** признаёт посетителя авторизованным.

В JSON и в настройках приоритета тот же набор обозначается как `providedFields`. В методе `provide_visitor_fields` Realtime API он передаётся параметром `visitor_fields`.

### Состав

Обязательное поле — `id`. Остальные поля необязательны. Имя передаётся как `display_name` (при слиянии оно становится `name`). Также передаются `email`, `phone` и другие поля из [списка поддерживаемых полей](https://webim.ru/kb/dev/identification/id-2-0.html#webim-visitor-format). Поле `crc` — это контрольная сумма старого формата, а не атрибут посетителя: в итоговый набор и в карточку РМО оно не переносится.

### Обязательные поля

Обязателен `id` — идентификатор пользователя во внешней системе. Без него посетитель не считается авторизованным. Чем это поле отличается от `id` в группе `fields`, см. [раздел `fields`](#fields).

Требования к `id`:

  * строка;

  * непустое значение;

  * для отчётов и поиска лучше уложиться в 255 символов. Полный `id` сохраняется в JSON посетителя, и идентификатор посетителя считается по этому полному значению. В колонку базы, по которой строятся отчёты и поиск, более длинное значение записывается укороченным: остаются первые 252 символа и добавляется `...`;

  * уникальность во внешней системе;

  * стабильность: одно и то же значение для одного и того же пользователя во всех обращениях. Если `id` меняется, посетитель считается новым или уже существующим — см. [описание в статье об идентификации](https://webim.ru/kb/dev/identification/id-2-0.html#webim-visitor-format).

### Особенности

В методе `provide_visitor_fields`:

  * имена и значения всех полей в `visitor_fields` должны быть строками. Иначе метод возвращает ошибку `field-name-is-not-string` или `field-value-is-not-string`;

  * ошибка `id-field-required` возвращается, только если объект `visitor_fields` передан и в нём нет непустого `id`. Если параметра `visitor_fields` нет, ранее переданные поля удаляются: это выход посетителя.

## opFields { #opfields }

### Назначение

`opFields` — поля, которые оператор внёс или изменил в карточке посетителя в ходе диалога.

### Состав

Оператор сохраняет сведения из формы редактирования в РМО. Обычно это `name`, `email`, `phone` и другие поля, показанные в этой форме.

### Обязательные поля

Обязательных полей нет. Поле `id` здесь не используется для идентификации.

### Особенности

Правки нужны, чтобы оператор поправил данные вручную. Как они сочетаются с другими группами, см. [приоритет групп полей](#visitor-fields-priority).

!!! Note "N.B."
    `chat_routing_fields` — не серверная группа полей, а объект на стороне клиента для маршрутизации посетителей по сегментам. Если одноимённое поле есть и в `webim_visitor.fields`, и в `chat_routing_fields`, при выборе размещения используется значение из `chat_routing_fields`. Серверные группы `fields`, `provided_fields` и `opFields` виджет при этом не видит. Подробности и пример см. в статье [Идентификация через передачу подписанных полей, версия 2.0](https://webim.ru/kb/dev/identification/id-2-0.html#chat-routing-fields).

## custom_fields { #custom_fields }

### Назначение

`custom_fields` — дополнительные сведения, которые мобильное приложение передаёт в момент старта чата. Состав задаёт само приложение: это контекст обращения, отдельный от полей посетителя.

### Состав

Значение — JSON-строка. Фиксированного списка имён нет: ключи задаёт приложение.

Параметр есть в таких методах:

  * Android SDK — `startChatWithCustomFields` и другие методы старта чата с аргументом `customFields`;

  * iOS SDK — `startChat(customFields:)` и другие методы старта чата с аргументом `customFields`.

Чат можно начать и без этого параметра: методы `startChat` без `customFields` его не требуют.

### Обязательные поля

Обязательных полей нет.

### Особенности

В виджете на сайте такого параметра нет. Форма запроса контактов пишет имя, телефон и email в `fields`.

При старте чата сервер не читает `custom_fields` и не включает его в итоговый набор полей посетителя, в том числе в слияние по `visitor_fields_priority_order`. Идентификатор посетителя по-прежнему передаётся в `provided_fields.id`, поля для выбора размещения — в `chat_routing_fields`.

---

Источник: https://webim.ru/kb/dev/identification/visitor-fields-objects.html
