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

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

Классическая ситуация: CRM уже используется, все сделки ведут менеджеры, но нужно добавить на карточку сделки блок с данными из внешней системы — например, остатки на складе из ERP или статус доставки из транспортной компании. Штатными средствами это не реализовать, нужен виджет через REST API и механизм встраивания UI Extensions. Мы в нашей компании регулярно решаем такие задачи: интеграция ERP, синхронизация статусов доставки, отображение фискальных чеков из ОФД прямо в карточке лида. За годы работы мы выработали чёткий подход к разработке виджетов: от аудита бизнес-процессов до выкатки в маркетплейс. В этой статье делимся практическими наработками.

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

Как выбрать между iframe и UI Extensions?

Какие типы виджетов и места встраивания существуют?

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

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

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

Каждый placement передаёт в виджет контекстную информацию: ID сущности, тип, права доступа. Подробнее о плейсментах читайте в официальной документации.

Как устроен iframe-виджет?

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

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

BX24.init(() => {
    const placement = BX24.placement.info();
    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 быстрее?

В последних версиях портала рекомендуется использовать @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 на клиенте. UI Extensions запускается на 30% быстрее, чем iframe-виджет, за счёт прямой шины событий.

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

Приложение регистрирует плейсменты при установке через хук 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": "Склад"
}

Почему важна безопасность OAuth?

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

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

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

OAuth — ключевой элемент безопасности. Опыт показывает, что большинство ошибок при разработке виджетов связаны с неправильной обработкой токенов. Подробнее об OAuth читайте на Wikipedia.

Типичные ошибки и их решение

• Content Security Policy (CSP) Битрикс24 ограничивает frame-ancestors. Ваш домен приложения должен быть в белом списке, что настраивается автоматически при публикации в Маркете или регистрации локального приложения.
• Медленная инициализация BX24.init() — если виджет грузится дольше 3 секунд, пользователи переключаются на другую вкладку. Оптимизация: загружайте bx24.js через CDN, делайте скелетон-лоадер до получения данных.
• Кросс-доменные cookies — для сессионной авторизации своего бэкенда используйте SameSite=None; Secure, иначе браузер заблокирует куки внутри iframe.

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

Что входит в работу

• Аудит текущей CRM и интеграционных сценариев
• Проектирование архитектуры виджета с учётом безопасности
• Реализация и тестирование в нескольких браузерах (Chrome, Firefox, Safari, мобильные приложения)
• Интеграция с внешними системами (ERP, ОФД, транспортные компании)
• Документация по установке и сопровождению
• Обучение администраторов портала

Мы даём гарантию на все выполненные работы. Поэтому при разработке мы используем только проверенные решения и многолетний опыт.

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

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

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