Розробка віджетів для Бітрікс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.