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

Замовте розробку віджета вже сьогодні. Оцінимо ваш проєкт. Зв'яжіться з нами, щоб обговорити деталі.