Инициализировать библиотеку BX24.init

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

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

Функция BX24.init регистрирует обработчик события «библиотека готова к работе» и выполняет его, как только библиотека получит данные от Битрикс24.

При инициализации библиотека запрашивает у родительской страницы данные, без которых приложение не может работать:

  • адрес Битрикс24 и язык интерфейса
  • данные авторизации
  • права текущего пользователя
  • настройки приложения
  • параметры встройки

Пока эти данные не получены, часть возможностей библиотеки не работает: BX24.getAuth возвращает false, а BX24.isAdmin — false независимо от реальных прав. Поэтому работу с настройками, правами и запросами к Битрикс24 выполняют внутри обработчика BX24.init.

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

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

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

Название
тип

Описание

someCallback*
function

Обработчик, который выполнится после готовности библиотеки. Вызывается без параметров, возвращаемое им значение библиотека игнорирует

Порядок выполнения обработчиков

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

  • обработчиков может быть несколько: каждый вызов BX24.init добавляет свой, все они выполняются в порядке регистрации
  • если библиотека уже готова, обработчик выполняется асинхронно — библиотека откладывает его таймером, а не вызывает сразу
  • обработчики при первом запуске приложения у пользователя ждут цепочку BX24.install: она завершается вызовом BX24.installFinish
  • вызовы BX24.callMethod до инициализации не теряются: библиотека откладывает их и выполняет после готовности

Готовность библиотеки — не то же самое, что готовность DOM-структуры страницы: за нее отвечают BX24.ready и BX24.isReady.

Пример кода

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

<script src="//api.bitrix24.tech/api/v1/"></script>
<script>
    BX24.init(function() {
        console.log('BX24 initialized successfully.');

        BX24.callMethod('user.current', {}, function(result) {
            if (result.error()) {
                console.error('Error fetching user data: ', result.error());
            } else {
                console.log('User data: ', result.data());
            }
        });
    });
</script>

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

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

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

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

Ситуация

Что происходит

Что делать

Страница открыта не во фрейме приложения — например, напрямую в браузере или на своем сайте

Библиотека не инициализируется: при загрузке она выбрасывает исключение Unable to initialize Bitrix24 JS library!, объект BX24 становится равен null, обработчики не выполняются

Открывать страницу как приложение Битрикс24

Библиотека не подключена

Выполнение прерывается с ошибкой BX24 is not defined. Текст дает браузер, поэтому он отличается: Safari пишет Can't find variable: BX24

Подключить библиотеку до первого вызова, подробнее — обзор библиотеки

В BX24.init передан не обработчик

До инициализации пустое значение библиотека игнорирует молча, после — вызов без обработчика дает ошибку в консоли. Значение другого типа она принимает как обработчик, и при запуске в консоли появляется ошибка

Передавать функцию

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

Предыдущая
Обзор функций
Следующая
Обработать первый запуск приложения у пользователя