Оповестить об окончании работы инсталлятора BX24.installFinish

BX24.installFinish(): void;

Функция BX24.installFinish сообщает об окончании работы инсталлятора или настройщика приложения. Вызовом этой функции приложение с интерфейсом завершает свою установку в Битрикс24.

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

Вызывайте функцию после того, как библиотека получила данные Битрикс24: вызванная раньше, она досрочно завершает установку на этапе инсталлятора — подробнее в разделе Обработка ошибок.

Собственный scope функции не нужен: она не обращается к REST API. Права и scope проверяются в тех методах Битрикс24, которые вызывает сам установочный сценарий: например, placement.bind требует прав администратора, а event.bind доступен любому пользователю — с ограничениями для офлайн-событий и чужого auth_type.

Параметры функцииПараметры функции

Без параметров.

Поведение на разных этапах установкиПоведение на разных этапах установки

Результат зависит от того, на каком этапе вызвана функция.

Приложению без интерфейса, которое использует только API, вызов installFinish не нужен: его установка завершается автоматически. Подробнее — Завершение установки приложений.

Пример кодаПример кода

Как использовать примеры в документации

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

<div id="install-error"></div>

<script src="//api.bitrix24.tech/api/v1/"></script>
<script>
    // ждем данные Битрикс24: вызванный раньше installFinish пометит приложение установленным, не разбирая этап
    BX24.init(function() {
        BX24.callBatch({
            bindPlacement: {
                method: 'placement.bind',
                params: {
                    PLACEMENT: 'CRM_DEAL_DETAIL_TAB',
                    HANDLER: 'https://example.com/b24/deal-tab.php',
                    TITLE: 'Аналитика по сделке'
                }
            },
            bindEvent: {
                method: 'event.bind',
                params: {
                    event: 'ONCRMDEALUPDATE',
                    handler: 'https://example.com/b24/deal-update.php'
                }
            }
        }, function(result) {
            if (result.bindPlacement.error() || result.bindEvent.error()) {
                // установку не завершаем: без встройки и подписки приложение работать не будет
                console.error('Ошибка регистрации: ', result.bindPlacement.error(), result.bindEvent.error());
                document.getElementById('install-error').textContent = 'Установка не завершена, попробуйте еще раз';
                return;
            }

            // installFinish — последним шагом, когда встройки и события уже зарегистрированы
            BX24.installFinish();
        });
    });
</script>

Обработка ответаОбработка ответа

Функция не возвращает данные (void) и не принимает обработчик. О результате говорит поведение Битрикс24 — на каждом этапе свое, как описывает таблица Поведение на разных этапах установки.

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

После цепочки обработчиков BX24.install функция становится пустой: следующие вызовы, в том числе из обработчиков BX24.init, ничего не делают. Завершайте настройку внутри цепочки, а не после нее.

Проверить состояние установки программно можно методом app.info. Поле result.INSTALLED имеет тип boolean. Фрагмент ответа для завершенной установки:

{
    "result": {
        "INSTALLED": true
    }
}

У приложения с интерфейсом значение false означает, что installFinish еще не вызван. Остальные поля ответа описывает страница метода app.info.

Обработка ошибокОбработка ошибок

Своих кодов ошибок у функции нет: она не обращается к REST API, а передает сообщение странице Битрикс24. Неудачи выглядят как отсутствие результата.

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

• Инициализация и авторизация в BX24.js: обзор функций
• Инициализировать библиотеку BX24.init
• Обработать первый запуск приложения у пользователя BX24.install
• Получить данные для OAuth 2.0 BX24.getAuth
• Принудительно обновить данные авторизации BX24.refreshAuth
• Завершение установки приложений
• Мастер установки локального приложения