Встройка в карточку CRM

Очень часто приложения расширяют функционал CRM, одного из самых востребованных инструментов Битрикс24.

Зайдем в кабинет разработчика и создадим новое приложение, как мы это делали в предыдущем уроке.

Нажмем кнопку «Добавить приложение». Выберем, как и ранее, основной регион для будущей публикации решения. В карточке приложения нажмем на кнопку «Создать» и укажем тип «Использовать 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 автоматически откроет приложение после завершения установки, поскольку у нашего приложения есть пользовательский интерфейс.

Полезно

Если основной функционал вашего приложения – это виджет, встраиваемый в некоторое место встройки, то основной URL приложения вы можете использовать для сценария онбординга, рассказывающего пользователю о функционале продукта и содержащего какие-то необходимые этапы настройки.

Перейдем в CRM и откроем любую сделку. Вы видите, что в карточке появилась дополнительная закладка My App. Если перейти на нее, то во внутренний фрейм будет загружен наш обработчик встройки.

В примере специально выведено содержимое массива REQUEST, чтобы продемонстрировать данные, которые Битрикс24 передает в наш виджет. Вы видите код места встройки и даже идентификатор текущей сделки. Этого достаточно, чтобы получить при помощи REST информацию, нужную для логики приложения.

В текущем примере мы получили и вывели данные о сделке при помощи метода crm.deal.get, подставив в параметры метода идентификатор сделки, полученный из PLACEMENT_OPTIONS.

Аналогично, ориентируясь на текущую сделку, в реальном приложении можно было бы получить данные о клиенте, запросить дополнительную информацию из внешней системы и многое другое.

REST API Битрикс24

Доступность из внешней сети

Материалы уроку: