Обработать первый запуск приложения у пользователя BX24.install

BX24.install(someCallback: function | string): void;

Функция BX24.install регистрирует обработчик события «приложение запускается первый раз для текущего пользователя». Событие возникает сразу после события «библиотека готова к работе», но до запуска обработчиков, установленных в BX24.init.

Обработчик обязан сообщить о завершении настройки вызовом BX24.installFinish. Пока он этого не сделал, обработчики BX24.init не запускаются.

Механика первого запуска нужна приложению с интерфейсом. Приложению, которое использует только API, она не нужна — подробнее BX24.installFinish.

Первый запуск у пользователя — не то же самое, что установка приложения. У приложения с интерфейсом установку выполняет страница установки — та, что задана в настройках приложения. Ее открывают только администратор и пользователь с правом устанавливать приложения, остальные видят сообщение о том, что приложение не установлено. Состояние установки проверяют методом app.info.

Обработчик BX24.install срабатывает у каждого пользователя и настраивает приложение под него. Этапы разбирает BX24.installFinish, порядок установки описывает раздел Установка приложения.

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

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

Обязательные параметры отмечены *

Когда возникает событиеКогда возникает событие

Событие подчиняется таким правилам:

• первый запуск отслеживает Битрикс24 и сообщает о нем библиотеке при инициализации. Обработчик должен переживать повторный запуск: он сработает у каждого пользователя, а после обновления приложения может сработать снова
• обработчиков может быть несколько: они выполняются по очереди, в порядке регистрации, и каждый передает управление следующему вызовом BX24.installFinish
• после последнего обработчика Битрикс24 запоминает, что приложение у этого пользователя уже запускалось
• без зарегистрированных обработчиков событие не возникает, и обработчики BX24.init выполняются сразу

Регистрируйте обработчик при загрузке страницы приложения — до того, как библиотека получит данные от Битрикс24. Обработчик, зарегистрированный позже, в цепочку первого запуска не попадет.

Функции BX24.userOption и BX24.appOption внутри обработчика первого запуска еще не работают: библиотека подключает их вместе с обработчиками BX24.init, то есть после всей цепочки. Чтобы прочитать или записать настройку на этом этапе, вызывайте методы user.option.set и app.option.set.

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

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

Внутри обработчика вызывают методы Битрикс24 через BX24.callMethod.

<script src="//api.bitrix24.tech/api/v1/"></script>
<script>
    // регистрируем обработчик сразу при загрузке страницы: позже он в цепочку первого запуска не попадет
    BX24.install(function() {
        BX24.callMethod('user.current', {}, function(res) {
            if (res.error()) {
                console.error('Error fetching user data: ', res.error());
            } else {
                console.log('Приложение Hello World приветствует вас, ' + res.data().NAME + '!');
                // запоминаем, что настройка прошла: обработчик должен переживать повторный запуск
                BX24.callMethod('user.option.set', {options: {greeting_shown: 'Y'}});
            }

            // installFinish вызываем в обеих ветках, иначе настройка не завершится
            BX24.installFinish();
        });
    });
</script>

Тот же обработчик можно вынести в отдельный js-файл и передать его адрес строкой — абсолютный или заданный относительно адреса страницы приложения. Библиотека подключает файл тегом script и выполняет его вместо вызова функции. Вызвать BX24.installFinish в этом случае должен код самого файла, но не синхронно при загрузке: цепочку библиотека подключает к функции только после того, как файл выполнился. Ранний вызов управление дальше не передаст, а на этапе инсталлятора завершит установку досрочно.

BX24.install('/install.js');

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

Функция не возвращает данные (void). Она только регистрирует обработчик, а результат работы обработчика определяет его собственный код.

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

Своих кодов ошибок у функции нет: она не обращается к REST API.

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

• Инициализация и авторизация в BX24.js: обзор функций
• Инициализировать библиотеку BX24.init
• Оповестить об окончании работы инсталлятора BX24.installFinish
• Получить данные для OAuth 2.0 BX24.getAuth
• Принудительно обновить данные авторизации BX24.refreshAuth
• Настройки приложения в BX24.JS: обзор методов
• Варианты установки приложений в Битрикс24