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

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