Механизм встраивания виджетов

Scope: placement, в зависимости от точки встраивания

Виджет — это интерфейс приложения, встроенный в страницу Битрикс24. Пользователь переходит на вкладку в карточке сделки, выбирает пункт меню или нажимает кнопку в чате и видит приложение во фрейме, не уходя из рабочего интерфейса. Вместе с фреймом Битрикс24 передает приложению авторизацию пользователя и контекст вызова — например, идентификатор сделки, из карточки которой открыт виджет.

Место, куда встраивается интерфейс, называется точкой встраивания и обозначается кодом: CRM_DEAL_DETAIL_TAB, LEFT_MENU, IM_TEXTAREA. Обработчик для точки регистрирует приложение методом placement.bind. Исключение одно — точка SETTING_CONNECTOR, ее обработчик подключает метод imconnector.register.

Эта страница описывает механизм: порядок регистрации, права, данные обработчика и типовые ошибки.

Быстрый переход: каталог точек встраивания

Как приложение попадает в интерфейс Битрикс24Как приложение попадает в интерфейс Битрикс24

Приложение может показать свой интерфейс пользователю по-разному. Виджеты — один из способов.

Собственная страница приложенияСобственная страница приложения

Пункт приложения в главном меню — не виджет. Обработчик для него не регистрируется: пункт открывает основной адрес приложения.

В локальном приложении укажите название пункта меню.

В тиражном решении включите опцию Добавлять свою страницу и пункт в главном меню.

Название пункта задается в описании приложения на нужном языке, в поле Название приложения в меню.

Пункт главного меню может открывать и зарегистрированный обработчик с контекстом вызова. Для этого используйте точку встраивания LEFT_MENU.

Как работает виджетКак работает виджет

1. Приложение регистрирует обработчик методом placement.bind: передает код точки в параметре PLACEMENT, а адрес своего обработчика — в параметре HANDLER.
2. Пользователь вызывает виджет: переходит на вкладку, выбирает пункт меню, нажимает кнопку.
3. Битрикс24 отправляет POST-запрос на адрес обработчика и передает в нем авторизацию пользователя и контекст вызова.
4. Обработчик отвечает страницей, которую разрешено открывать во фрейме, и Битрикс24 показывает ее на месте виджета.
5. Из фрейма приложение вызывает REST API от лица пользователя и управляет интерфейсом Битрикс24 через методы JavaScript.

Какие права нужныКакие права нужны

Права складываются из двух слоев.

Скоуп placement нужен всегда — без него приложение не вызовет placement.bind.

Скоуп инструмента нужен, чтобы работать с данными этого инструмента из виджета: получить сделку по идентификатору из контекста вызова, чат по dialogId, задачу по идентификатору. У части точек тот же скоуп требуется и для самой регистрации: точки CRM объявлены в скоупе crm, точки задач — в task. Для точек мессенджера, наоборот, при регистрации достаточно скоупа placement, а im нужен уже для работы с чатом.

Нужный набор указан в начале страницы каждой точки — ориентируйтесь на него, а не на раздел продукта.

Права приложения — не единственное условие. Виджет видят только те сотрудники, которым открыт доступ к приложению: Битрикс24 проверяет доступ при каждом выводе виджета.

Методы placement.bind, placement.unbind и placement.get доступны только администратору Битрикс24, placement.list — любому пользователю. Все они работают в контексте приложения: вызов вебхуком вернет ошибку WRONG_AUTH_TYPE.

Как начать работуКак начать работу

1. Выберите точку под свой сценарий в каталоге точек встраивания. Ее код понадобится в параметре PLACEMENT.
2. Укажите в настройках приложения скоуп placement, а если точке нужен скоуп инструмента — еще и его. Набор указан в шапке страницы точки.
3. Зарегистрируйте обработчик методом placement.bind. Чаще всего это делают во время установки приложения.
4. Завершите установку приложения и откройте точку встраивания в интерфейсе.
5. Разберите данные POST-запроса в обработчике: авторизацию пользователя и контекст вызова из PLACEMENT_OPTIONS.

Как использовать примеры в документации

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{
            "PLACEMENT": "CRM_DEAL_DETAIL_TAB",
            "HANDLER": "https://your-domain.com/widgets/deal-tab-handler.php",
            "TITLE": "Поставки по сделке",
            "auth": "**put_access_token_here**"
          }' \
          https://**put_your_bitrix24_address**/rest/placement.bind
        

Что получает обработчикЧто получает обработчик

Данные передаются POST-запросом: часть параметров — в query-строке адреса обработчика, остальные — в теле запроса

Пример показан для вкладки в карточке сделки. У остальных точек состав данных такой же: меняются значение PLACEMENT и контекст вызова в PLACEMENT_OPTIONS. Исключение — BI_ANALYTICS_MENU: эта точка открывает адрес обработчика обычным GET-запросом и не передает ему ничего.

Array
        (
            [DOMAIN] => xxx.bitrix24.com
            [PROTOCOL] => 1
            [LANG] => ru
            [APP_SID] => 5552d735db7b7b4d5c16dd9c272bfe7d
            [AUTH_ID] => 9d4c7166007e9c94001e30ba00000001f0f107e28b5a4310c7f6d9b3025ea814
            [AUTH_EXPIRES] => 3600
            [REFRESH_ID] => 8c3b9966007e9c94001e30ba00000001f0f107f19c6b3e04d182ac5b73f9052d
            [SERVER_ENDPOINT] => https://oauth.bitrix24.tech/rest/
            [APPLICATION_TOKEN] => ec1b2074a9d3f5c81b6e40d27a95cf38
            [APPLICATION_SCOPE] => crm,placement
            [member_id] => d897063e1ce7c5eb9f04b9751eef5915
            [status] => L
            [PLACEMENT] => CRM_DEAL_DETAIL_TAB
            [PLACEMENT_OPTIONS] => {"ID":"8061","URI":"\/crm\/deal\/details\/8061\/?any=details%2F8061%2F&IFRAME=Y&IFRAME_TYPE=SIDE_SLIDER"}
        )
        

Обязательные параметры отмечены *

Параметры в query-строке адреса обработчика

Параметры в теле POST-запроса

Битрикс24 добавляет в PLACEMENT_OPTIONS ключ URI — путь с query-строкой той страницы, с которой открыт виджет. Он приходит для любой точки встраивания, вместе с ее собственными ключами. Ключа не будет, если браузер не передал заголовок Referer или виджет открыт со страницы другого домена.

Как разобрать контекст вызова

PLACEMENT_OPTIONS приходит JSON-строкой, а не массивом: перед использованием разберите ее на стороне обработчика. Состав ключей у каждой точки свой и описан в разделе PLACEMENT_OPTIONS этой страницы.

$placement = $_POST['PLACEMENT'] ?? '';
        $options = json_decode($_POST['PLACEMENT_OPTIONS'] ?? '{}', true);
        

options = json.loads(request.form.get("PLACEMENT_OPTIONS", "{}") or "{}")
        

В B24JsSDK разбирать строку не нужно: свойство $b24.placement.options возвращает готовый объект, а $b24.placement.placement — код точки встраивания.

Что должен вернуть обработчик

Обработчик отвечает обычной HTML-страницей — Битрикс24 показывает ее во фрейме на месте виджета. Страница должна разрешать встраивание: если сервер приложения отдает заголовки X-Frame-Options или Content-Security-Policy, запрещающие фрейм, на месте виджета останется пустая область. Как это исправить, описано в статье Сайт не разрешает подключение.

Адрес обработчика доступен из внешней сети, поэтому проверяйте, что запрос пришел от Битрикс24: сравнивайте APPLICATION_TOKEN со значением, которое приложение получило и сохранило при установке. Как приложение запоминает токен, описано в статье Безопасность в обработчиках. Токены AUTH_ID и REFRESH_ID не записывайте в логи и не передавайте третьим лицам.

PLACEMENT_OPTIONSPLACEMENT_OPTIONS

Контекст вызова приходит JSON-строкой в параметре PLACEMENT_OPTIONS. Состав ключей зависит от точки:

• в карточке CRM — идентификатор объекта
• в чате — идентификатор диалога, а для точки в меню сообщения еще и идентификатор сообщения
• у универсальных точек — код точки или произвольные параметры, которые приложение само передало в ссылке
• у точек без собственного контекста — только универсальный ключ URI

Полный состав ключей описан на странице каждой точки встраивания.

Готовый обработчик — прием POST-запроса, разбор PLACEMENT_OPTIONS и ответ страницей для фрейма — показан по шагам в туториале Как встроить виджет во вкладку карточки CRM. Код в нем подходит любой точке: меняются только код в PLACEMENT и ключи контекста вызова.

Что можно делать из виджетаЧто можно делать из виджета

Виджет работает во фрейме, но не изолирован от Битрикс24:

• вызывать REST API от лица пользователя по токену AUTH_ID из данных обработчика
• открывать стандартные страницы Битрикс24 и свои интерфейсы в слайдере — методы BX24 SDK для виджетов
• управлять карточкой CRM и карточкой звонка из своего интерфейса — взаимодействие с UI из виджетов
• оформлять интерфейс в стиле Битрикс24 — Битрикс24 UI Kit

Методы JavaScript работают только после подключения библиотеки к странице обработчика. Как ее подключить, описано в обзоре BX24.js: обзор библиотеки.

Интерфейс виджета ограничен размером фрейма: всплывающее окно шире этой области обрежется, а по краям появятся полосы прокрутки. Формы настроек, детальные карточки объектов и формы добавления открывайте отдельным слайдером через BX24.openApplication — в него можно передать произвольные параметры приложения.

Жизненный цикл обработчикаЖизненный цикл обработчика

Обработчики удаляются вместе с приложением, отдельно снимать регистрацию не нужно. Что еще Битрикс24 очищает при удалении приложения, описано в статье Удаление приложения.

Типовые ошибкиТиповые ошибки

Продолжите изучениеПродолжите изучение

• Каталог точек встраивания
• Пункт в главном меню LEFT_MENU
• Зарегистрировать обработчик виджета placement.bind
• Получить точки встраивания, доступные приложению placement.list
• Получить обработчики, зарегистрированные приложением placement.get
• Удалить обработчик виджета placement.unbind
• Методы BX24 SDK для виджетов
• Взаимодействие с UI: обзор методов
• Битрикс24 UI Kit: обзор
• Как встраивать виджеты в CRM