Разработка виджетов для Битрикс24

Разработка виджетов для Битрикс24

Классическая ситуация: CRM уже используется, все сделки ведут менеджеры, но нужно добавить на карточку сделки блок с данными из внешней системы — например, остатки на складе из ERP или статус доставки из транспортной компании. Штатными средствами это не реализовать, нужен виджет через REST API и механизм встраивания UI Extensions.

Виджеты в Битрикс24 — это отдельный тип приложений, которые рендерятся внутри интерфейса портала через iframe или JS SDK. С 2022 года Bitrix развивает концепцию UI Extensions как замену классическим iframe-виджетам. Разбираемся, что когда применять и как это делается на практике.

Типы виджетов и места встраивания

Битрикс24 поддерживает несколько механизмов встраивания:

• Placement API (BX24.placement.call) — классический способ: приложение регистрирует placement, Битрикс24 отображает его в нужном месте интерфейса
• UI Extensions — набор готовых компонентов (Button, Dialog, Loader, Alert), доступных через @bitrix24/b24jssdk. Работают внутри iframe, но с доступом к шине событий портала
• Slider — открытие произвольного URL в боковой панели через BX24.openApplication()

Актуальные плейсменты регистрируются при установке приложения через метод app.option.set и хранятся в таблице b_app_option. Список доступных мест встраивания:

Архитектура iframe-виджета

Типичный виджет состоит из двух частей: обработчика на сервере (endpoint, который вернёт HTML страницы виджета) и клиентского кода внутри iframe.

Инициализация в клиентском коде:

BX24.init(() => {
    const placement = BX24.placement.info();
    // placement.options содержит контекст: id сделки, id пользователя и т.д.
    const dealId = placement.options.ID;

    BX24.callMethod('crm.deal.get', { id: dealId }, (result) => {
        if (result.error()) {
            console.error(result.error());
            return;
        }
        renderWidget(result.data());
    });
});

Высота iframe — частая проблема. Битрикс24 не делает iframe резиновым автоматически. После рендера контента нужно явно вызвать:

BX24.fitWindow(() => {
    // callback после изменения высоты
});

Если этого не сделать — виджет обрежется или появится внутренний скроллбар.

UI Extensions: современный подход

Начиная с версии портала 2024+, рекомендуется использовать @bitrix24/b24jssdk. Он даёт типизированный доступ к REST API прямо из iframe:

import { initializeB24Frame, B24Frame } from '@bitrix24/b24jssdk';

const $b24 = await initializeB24Frame();
const profile = await $b24.fetchProfile();
const result = await $b24.callMethod('crm.deal.list', {
    filter: { ASSIGNED_BY_ID: profile.id },
    select: ['ID', 'TITLE', 'STAGE_ID']
});

SDK берёт на себя авторизацию (OAuth токен передаётся автоматически через postMessage), не нужно хранить client_secret на клиенте.

Регистрация плейсмента и манифест приложения

Приложение регистрирует плейсменты при установке через хук OnAppInstall. Пример в манифесте:

{
  "placements": [
    {
      "placement": "CRM_DEAL_DETAIL_TAB",
      "handler": "https://myapp.example.com/widget/deal-tab",
      "title": "Данные ERP",
      "description": "Остатки и резервы по позициям сделки"
    }
  ]
}

Либо программно через REST:

POST /rest/placement.bind
{
  "PLACEMENT": "CRM_DEAL_DETAIL_TAB",
  "HANDLER": "https://myapp.example.com/widget/deal-tab",
  "TITLE": "Склад"
}

Авторизация и безопасность

Все запросы от iframe к серверу должны передавать AUTH_ID (короткоживущий токен, 1 час) или использовать REFRESH_TOKEN для его обновления. Никогда не храните client_secret в клиентском коде — только на сервере.

Валидируйте входящий event из postMessage:

window.addEventListener('message', (event) => {
    if (event.origin !== 'https://your-portal.bitrix24.ru') return;
    // обработка
});

Типичные сложности

CSP (Content Security Policy) Битрикс24 ограничивает frame-ancestors. Ваш домен приложения должен быть в белом списке, что настраивается автоматически при публикации в Маркете или регистрации локального приложения.

Медленная инициализация BX24.init() — если виджет грузится дольше 3 секунд, пользователи переключаются на другую вкладку. Оптимизация: загружайте bx24.js через CDN, делайте скелетон-лоадер до получения данных.

Кросс-доменные cookies — для сессионной авторизации своего бэкенда используйте SameSite=None; Secure, иначе браузер заблокирует куки внутри iframe.

Сроки разработки

Основное время уходит не на сам виджет, а на настройку OAuth-авторизации, обработку edge-кейсов (истёкший токен, портал в другом датацентре) и тестирование в нескольких браузерах — Битрикс24 поддерживает Chrome, Firefox, Safari и мобильные приложения с разным поведением iframe.