Перейти к содержанию

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

В 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.