Мастер установки локального приложения

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

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

Для серверного приложения мастер открывается, если заполнено поле Путь для первоначальной установки и включена опция Приложение само завершает установку. По умолчанию опция выключена: тогда Битрикс24 сразу отмечает приложение как установленное и отправляет данные установки на указанный URL в событии ONAPPINSTALL. Этот сценарий описан на странице Callback установки.

Когда открывается мастер установки

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

Страница по этому URL служит мастером установки. На ней можно выполнить одноразовые действия:

Где задать мастер установки

В Битрикс24 откройте Приложения > Разработчикам > Другое > Локальное приложение и выберите тип приложения.

Серверное приложение

Выберите Серверное и заполните поле Путь для первоначальной установки.

Укажите публичный URL страницы установки на вашем сервере, например https://example.com/install.php. Имя файла может быть любым. Можно указать адрес с протоколом HTTP или HTTPS, но для рабочего приложения используйте HTTPS.

Основной URL приложения укажите отдельно в поле Путь вашего обработчика. После завершения установки Битрикс24 будет открывать этот URL вместо страницы мастера.

Если поле Путь для первоначальной установки не заполнено, Битрикс24 сразу считает локальное приложение установленным и не открывает мастер.

Включите опцию Приложение само завершает установку, если по указанному URL должна открываться страница мастера. При выключенной опции этот URL используется как callback установки, а приложение сразу получает статус установленного.

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

Статичное приложение

Выберите Статичное и загрузите ZIP-архив приложения. Поля Путь для первоначальной установки и Путь вашего обработчика для этого типа не отображаются.

В качестве мастера установки Битрикс24 использует файл install.html из корня архива. Если этого файла нет, мастер не открывается: Битрикс24 сразу обращается к index.html из того же архива.

Условия и права

  • Для создания локального приложения пользователь должен иметь право на установку локальных приложений
  • Для статичного приложения файл install.html находится в корне ZIP-архива
  • В карточке приложения должны быть выбраны права доступа, которые нужны для установочных REST-вызовов
  • URL мастера серверного приложения должен быть доступен по сети

Не размещайте секреты и токены в HTML-коде или другом клиентском коде страницы установки. Для серверного приложения храните их на своей стороне в защищенном хранилище.

Как завершить установку

Мастер должен явно сообщить Битрикс24, что установка успешно завершена. Для этого вызовите JS-метод BX24.installFinish() на странице установки серверного приложения или в файле install.html статичного приложения.

Вызывайте BX24.installFinish() последним шагом: после сохранения настроек, регистрации обработчиков событий, виджетов и других обязательных операций. Пока метод не вызван, Битрикс24 считает приложение не установленным. При повторном переходе пользователя с правом установки в серверное приложение открывается URL из поля Путь для первоначальной установки. Для статичного приложения открывается файл install.html. Остальные пользователи видят сообщение о незавершенной установке.

До завершения установки события не доставляются, а встройки не появляются в интерфейсе, даже если методы event.bind и placement.bind отработали успешно.

Проверить состояние установки можно методом app.info. Значение false в поле INSTALLED означает, что установка не завершена.

Минимальный пример страницы мастера:

<!doctype html>
<html lang="ru">
<head>
    <meta charset="utf-8">
    <title>Установка приложения</title>
    <script src="//api.bitrix24.tech/api/v1/"></script>
</head>
<body>
    <button id="finish-install">Завершить установку</button>

    <script>
        BX24.init(function() {
            document.getElementById("finish-install").addEventListener("click", function() {
                // Здесь выполните обязательные действия установки.
                BX24.installFinish();
            });
        });
    </script>
</body>
</html>

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

Предыдущая
Обзор
Следующая
Callback установки