Объекты полей посетителя
В Webim поля посетителя могут приходить из разных источников и использоваться в разных сценариях. Для этих данных предусмотрено несколько объектов. Их не следует объединять в один объект на стороне интеграции: у них разные роли и правила использования.
В этой статье описано, для чего предназначен каждый объект, из каких полей он обычно состоит и как группы сливаются на сервере.
Источники и приоритет
Сведения об одном и том же посетителе могут одновременно поступать из нескольких мест. На стороне Webim они хранятся в виде групп полей (отдельных массивов). Сервер объединяет группы в итоговый набор. Как выбирается значение при совпадении имён, описано в разделе «Приоритет групп полей».
Откуда приходят данные
| Группа | Откуда берётся |
|---|---|
provided_fields |
Интеграция передаёт данные авторизованного посетителя: объект webim_visitor на странице, метод provide_visitor_fields в Webim Realtime API, метод setVisitorFieldsJson в Android SDK и метод set(visitorFieldsJSONString:) в iOS SDK. |
fields |
Посетитель указал данные сам: форма перед началом чата, форма офлайн-сообщения и форма запроса контактов в виджете, а также каналы-мессенджеры. Эти данные не подписываются и не проверяются. |
opFields |
Значения, которые оператор внёс или изменил в РМО в ходе диалога. |
N.B.
Как provided_fields называется в JSON и в Realtime API, см. в разделе provided_fields.
Приоритет групп полей
Если одно и то же поле (например, телефон) задано в нескольких группах по-разному, в итоговый набор попадает одно значение.
| Где применяется | Как определяется порядок |
|---|---|
| Боты, первое сообщение диалога и прочая серверная логика модели посетителя | Параметр visitor_fields_priority_order в настройках аккаунта (account config): имена групп от наиболее приоритетной к наименее. По умолчанию ["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 в полном объёме.
N.B.
Имя, которое сервер подставляет как имя отправителя в сообщениях, уведомлениях и каналах, считается отдельно и не зависит от visitor_fields_priority_order. Берётся display_name из provided_fields, а если его нет — name из fields. Группа opFields в этот выбор не входит: правка имени оператором в РМО не меняет имя отправителя в истории сообщений и в каналах.
Состав групп может отличаться. Обязательным является только id в provided_fields. В fields и opFields обязательных полей нет. Почему id не стоит передавать в 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.
provided_fields
Назначение
provided_fields — поля авторизованного посетителя, которые интеграция передаёт со стороны клиента. По ним Webim признаёт посетителя авторизованным.
В JSON и в настройках приоритета тот же набор обозначается как providedFields. В методе provide_visitor_fields Realtime API он передаётся параметром visitor_fields.
Состав
Обязательное поле — id. Остальные поля необязательны. Имя передаётся как display_name (при слиянии оно становится name). Также передаются email, phone и другие поля из списка поддерживаемых полей. Поле crc — это контрольная сумма старого формата, а не атрибут посетителя: в итоговый набор и в карточку РМО оно не переносится.
Обязательные поля
Обязателен id — идентификатор пользователя во внешней системе. Без него посетитель не считается авторизованным. Чем это поле отличается от id в группе fields, см. раздел fields.
Требования к id:
-
строка;
-
непустое значение;
-
для отчётов и поиска лучше уложиться в 255 символов. Полный
idсохраняется в JSON посетителя, и идентификатор посетителя считается по этому полному значению. В колонку базы, по которой строятся отчёты и поиск, более длинное значение записывается укороченным: остаются первые 252 символа и добавляется...; -
уникальность во внешней системе;
-
стабильность: одно и то же значение для одного и того же пользователя во всех обращениях. Если
idменяется, посетитель считается новым или уже существующим — см. описание в статье об идентификации.
Особенности
В методе 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 — поля, которые оператор внёс или изменил в карточке посетителя в ходе диалога.
Состав
Оператор сохраняет сведения из формы редактирования в РМО. Обычно это name, email, phone и другие поля, показанные в этой форме.
Обязательные поля
Обязательных полей нет. Поле id здесь не используется для идентификации.
Особенности
Правки нужны, чтобы оператор поправил данные вручную. Как они сочетаются с другими группами, см. приоритет групп полей.
N.B.
chat_routing_fields — не серверная группа полей, а объект на стороне клиента для маршрутизации посетителей по сегментам. Если одноимённое поле есть и в webim_visitor.fields, и в chat_routing_fields, при выборе размещения используется значение из chat_routing_fields. Серверные группы fields, provided_fields и opFields виджет при этом не видит. Подробности и пример см. в статье Идентификация через передачу подписанных полей, версия 2.0.
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.