Лучший способ дать пользователю дополнительный функционал из своего приложения – это встроить его в виде виджета в том месте Битрикс24, где этот функционал и будет использоваться: в карточке CRM, в списке задач и так далее.
Для этого в REST API есть механизм встройки, описанный в разделе «Встраивание приложений» в документации
Встройка виджета
5 мин
Зайдем в кабинет разработчика и создадим новое приложение, как мы это делали в предыдущем уроке.
Нажмем кнопку «Добавить приложение». Выберем, как и ранее, основной регион для будущей публикации решения. В карточке приложения нажмем на кнопку «Создать» и укажем тип «Использовать REST API».
Включим опцию «Встраивать виджеты в интерфейс». Эта опция добавляет в список скоупов «Встраивание приложений».
Скачайте пример, прикрепленный к уроку, и загрузите его на свой сервер так же, как мы это делали на уроках, посвященным локальным интеграциям.
Вставьте в карточке версии пути к выгруженному на сервер приложению, как мы это делали ранее. Скопируйте значения из полей client_id, client_secret и вставьте их в соответствующие константы в файле settings.php.
Доступность из внешней сети
Очень важно, чтобы адрес выгруженного на сервер примера был доступен из внешней сети. Никаких localhost, никаких самоподписанных SSL-сертификатов и так далее. Проверяйте доступность вашего URL какими-то сторонними сервисами, не уповайте, пожалуйста, на то, что именно в вашем браузере этот адрес успешно открывается. Убедитесь, что ваш веб-сервер разрешает показ во фреймах – без этого никакие встройки виджетов не смогут работать!
Посмотрим код примера, и начнем с install.php. Здесь вызывается уже известный нам из предыдущих уроков метод installApp, который сохранит полученные токены авторизации в файл для дальнейшего использования.
И здесь же мы сразу воспользуемся этими токенами для выполнения метода placement.bind. В нашем примере используются только три параметра:
- PLACEMENT. Код места встройки виджета, а именно левое меню.
- HANDLER. Ссылка на сам интерфейс виджета, которая будет открываться во фрейме.
- TITLE. Название виджета. В нашем случае оно используется в качестве названия элемента меню.
Полезно
Поскольку интерфейс Битрикс24 поддерживает много языков, и отдельный пользователь портала может выбрать свой, то для своих виджетов вы также можете указывать названия на разных языках. Подробнее об этом написано в документации по методу placement.bind.
Вернемся в кабинет разработчика.
Текущая страница позволит установить приложение на наш Битрикс24 и протестировать его до публикации в Битрикс24.Маркет.
Укажем адрес своего Битрикс24, на котором мы являемся администратором и нажмем Установить. Произойдет редирект на портал и откроется интерфейс установки приложения. Когда мы опубликуем приложение в каталоге, заполнив описания и прикрепив скриншоты, установка будет выглядеть эффектнее, но сейчас нам нужно просто убедиться в технической работоспособности приложения. Битрикс24 автоматически откроет приложение после завершения установки, поскольку у нашего приложения есть пользовательский интерфейс.
Мы также можем убедиться, что в левом меню появились два пункта. Один с названием, которое было взято из описания приложения на русском языке. По клику на этот пункт будет открываться слайдер с основным интерфейсом приложения.
А второй пункт появился в результате встройки виджета. По клику открывается слайдер с placement.php.
Виджет
Фактически, виджет – это пользовательский интерфейс приложения, доступный по отдельному url, открываемый во фрейме точно так же, как и основной URL приложения.
И в случае виджета, и в случае основного URL приложения, Битрикс24 передает нам POST-запрос с данными о портале, токенами авторизации и контекстом.
В нашем примере специально выведено содержимое массива REQUEST, чтобы продемонстрировать различия в значении параметра PLACEMENT. Если на основной странице приложения PLACEMENT равен DEFAULT, то в виджете встройки в левое меню оно равно LEFT_MENU.
Точно так же это значение будет отличаться и для других мест встроек, а параметр PLACEMENT_OPTIONS будет содержать дополнительную информацию. Например, идентификатор текущей сделки, если виджет встраивается в карточку сделки и т.д.
В Битрикс24 существует несколько десятков возможных мест для виджетов. Поэтому мы продолжим рассматривать примеры использования наиболее частых встроек в следующих уроках.
Список ресурсов
Материалы уроку:
- Пример из урока example21.zip
- SDK CRest перейти
- Кабинет разработчика перейти
- Основные места встройки виджетов перейти