Встройка в виде ссылки

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

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

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

Нажмем кнопку «Добавить приложение». Выберем, как и ранее, основной регион для будущей публикации решения. В карточке приложения нажмем на кнопку «Создать» и укажем тип «Использовать REST API».

Включим опцию «Встраивать виджеты в интерфейс». Эта опция добавляет в список скоупов «Встраивание приложений». Добавим скоуп «Живая лента» - он пригодится нам для сценария.

Скачайте пример, прикрепленный к уроку, и загрузите его на свой сервер так же, как мы это делали на уроках, посвященным локальным интеграциям.

Вставьте в карточке версии пути к выгруженному на сервер приложению, как мы это делали ранее. Скопируйте значения из полей client_id, client_secret и вставьте их в соответствующие константы в файле settings.php.

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

Очень важно, чтобы адрес выгруженного на сервер примера был доступен из внешней сети. Никаких localhost, никаких самоподписанных SSL-сертификатов и так далее. Проверяйте доступность вашего URL какими-то сторонними сервисами, не уповайте, пожалуйста, на то, что именно в вашем браузере этот адрес успешно открывается. Убедитесь, что ваш веб-сервер разрешает показ во фреймах – без этого никакие встройки виджетов не смогут работать!

Посмотрим код примера, и начнем с install.php. Здесь вызывается уже известный нам из предыдущих уроков метод installApp, который сохранит полученные токены авторизации в файл для дальнейшего использования.

И здесь же мы сразу воспользуемся этими токенами для выполнения метода placement.bind. В нашем примере используются только два параметра:

PLACEMENT. Код места встройки виджета, а именно встройка в виде ссылок.
HANDLER. Ссылка на сам интерфейс виджета, которая будет открываться во фрейме при клике на ссылки.

Вернемся в кабинет разработчика.

Текущая страница позволит установить приложение на наш Битрикс24 и протестировать его до публикации в Битрикс24.Маркет.

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

В нашем случае, чтобы встройка заработала, наше приложение должно добавить в Битрикс24 какой-то контент, содержащий ссылку нужного формата. Предположим, что наше приложение – это внешняя система документооборота. Но мы хотим, чтобы документы, которые хранятся в этой системе, были доступны в интерфейсе Битрикс24. Чтобы их можно было обсудить с коллегами, например.

Нажмем кнопку «Загрузить документы». Приложение добавит пост живой ленты, содержащий три ссылки на некие внешние документы.

Убедимся, что нажатие на ссылку отроет слайдер с виджетом. И убедимся, что каждый раз, открывается разный документ.

Посмотрим, как этот крутой функционал был реализован через простую встройку.

Откроем index.php. Фактически, весь код сводится к вызову метода log.blogpost.add, который добавляет пост в живую ленту. Но самое интересно здесь в том, как именно формируются ссылки в тексте поста.

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

Откуда берется символьный код приложения, указанный в переменной $my_app_code?

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

Посмотрим на код обработчика встройки placement.php. Он очень простой. Поскольку наши ссылки были сформированы с параметром doc, мы получаем значение этого параметра в ключе PLACEMENT_OPTIONS массива REQUEST.

В пример включены три текстовых файла с названиями, которые соответствуют возможным значениям параметра doc.

Как только открывается слайдер с виджетом и конкретное значение передается в обработчике placement.php, мы подгружаем и показываем содержимое нужного файла.

В реальных кейсах можно было бы обращаться к API сторонней системы, получать файлы из базы данных приложения и многое другое.

Самое главное в этом сценарии, что наше приложение само формирует ссылки с нужными параметрами и оно же служит инструментом визуализации контента этих ссылок с точки зрения конечного пользователя.

REST API Битрикс24

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

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