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

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

Условия для мастера установкиУсловия для мастера установки

Чтобы использовать мастер установки:

• установку должен выполнять администратор Битрикс24 или пользователь, которому разрешена установка приложений
• в кабинете разработчика, в карточке версии приложения, укажите публичный адрес мастера в поле Ссылка на установочное приложение. Для рабочей версии используйте HTTPS и не указывайте localhost, адрес локальной сети или адрес с самоподписанным SSL-сертификатом
• на странице мастера подключите JS-библиотеку Битрикс24, чтобы после успешной настройки вызвать метод BX24.installFinish()
• если мастер выполняет REST-запросы, приложению нужны соответствующие права доступа

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

Если приложение хранит настройки для разных Битрикс24, связывайте запись на своей стороне с member_id. Этот идентификатор не меняется при смене адреса Битрикс24.

Где указать URL мастераГде указать URL мастера

URL мастера указывают в кабинете разработчика, в карточке версии приложения. Поле зависит от выбранного сценария установки:

• если у приложения есть интерфейс, выберите сценарий с мастером установки и укажите URL мастера в поле Ссылка на установочное приложение
• если у приложения нет интерфейса, выберите callback установки и укажите URL обработчика установки

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

Как работает мастер установкиКак работает мастер установки

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

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

Этот же URL можно использовать для инициализации и создания нужных объектов в Битрикс24. Например, можно:

• установить обработчики нужных событий
• зарегистрировать виджеты в нужных местах встройки
• добавить провайдер платежной системы или кассы
• зарегистрировать провайдер SMS-сообщений

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

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

После вызова BX24.installFinish() Битрикс24 открывает основной URL из поля Ссылка на приложение. Поэтому вызывайте метод последним шагом: после сохранения настроек, регистрации виджетов и подписки на события.

<script src="//api.bitrix24.tech/api/v1/"></script>
<script>
    function callMethod(method, params) {
        return new Promise(function(resolve, reject) {
            BX24.callMethod(method, params, function(result) {
                if (result.error()) {
                    reject(result.error());
                    return;
                }

                resolve(result.data());
            });
        });
    }

    BX24.init(async function() {
        try {
            await callMethod('placement.bind', {
                PLACEMENT: 'CRM_DEAL_DETAIL_TAB',
                HANDLER: 'https://example.com/deal-tab',
                TITLE: 'Данные приложения'
            });

            await callMethod('event.bind', {
                event: 'ONCRMDEALADD',
                handler: 'https://example.com/event-handler'
            });

            BX24.installFinish();
        } catch (error) {
            console.error('Ошибка установки:', error);
        }
    });
</script>

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

Когда выбрать другой вариант установкиКогда выбрать другой вариант установки

Особенности установки статичного приложенияОсобенности установки статичного приложения

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

Логика остается прежней: в файле install.html можно использовать JS-функции для нужных запросов, а после успешного завершения мастера нужно вызвать метод BX24.installFinish().

Если install.html в корне архива нет, Битрикс24 считает, что мастер установки не нужен, и сразу обращается к index.html из того же архива.