Уявіть: ви відкриваєте картку угоди в Бітрікс24, а там — порожня вкладка. Дані з вашої WMS не підтягуються, менеджеру доводиться перемикатися між системами. Це знижує швидкість обробки замовлень на 40%. Для логістичної компанії ми вирішили цю проблему: розробили додаток, який вбудовується в картку угоди і в реальному часі підвантажує статус доставки з WMS. Результат — скорочення часу на обробку замовлення з 15 до 3 хвилин. Економія склала сотні тисяч гривень на рік.
Чому вбудований додаток Бітрікс24 швидший за віджет?
Стандартні віджети працюють в ізоляції: вони відображають дані, але не можуть змінювати інтерфейс або підписуватися на події. Вбудовані додатки знімають ці обмеження. Вони дають двосторонню взаємодію з CRM: читають і оновлюють поля картки без перезавантаження, викликають діалоги та сповіщення, синхронізуються із зовнішніми системами.
Згідно з документацією BX24 SDK, вбудовані додатки (Embedded Apps) — це додатки з типом IFRAME, які реєструють плейсменти і працюють всередині інтерфейсу порталу. На відміну від зовнішніх (серверних) додатків, вони мають прямий доступ до JS SDK BX24 і можуть:
- читати та змінювати поля відкритої картки CRM у реальному часі без перезавантаження
- викликати діалоги, слайдери та сповіщення Бітрікс24 (
BX24.openPath,BX24.showMessagePopup) - підписуватися на події інтерфейсу через
BX24.placement.call('getInterface', ...)
Як вбудований додаток прискорює роботу з CRM?
Найцінніша можливість — читання та запис полів картки без перезавантаження сторінки. Підписка на оновлення сутності та програмна зміна поля виконуються через BX24.placement:
// Підписка на оновлення сутності BX24.placement.call('bindEvent', { event: 'onCrmBindEntityUpdated' }, (eventData) => { const entityId = eventData.ENTITY_ID; refreshWidgetData(entityId); }); // Зміна поля візуально BX24.placement.call('setFieldValue', { FIELD: 'UF_CRM_CUSTOM_STATUS', VALUE: 'shipped' }, () => { console.log('Поле оновлено в інтерфейсі'); }); Повний список подій залежить від типу картки (CRM_DEAL, CRM_LEAD та ін.) — у кожної своя документація.
Отримання інтерфейсу плейсменту — розробка вбудованих додатків
Для CRM_DEAL_DETAIL_TAB можна отримати інтерфейс поточного плейсменту:
BX24.placement.call('getInterface', {}, (interfaceData) => { /* interfaceData містить: { ID: "42", // ID угоди ENTITY_TYPE: "CRM_TYPE_DEAL", FIELDS: { ... }, // Поточні значення полів BUTTONS: [ ... ] // Доступні кнопки } */ }); Як працює авторизація та життєвий цикл?
При відкритті вкладки з додатком Бітрікс24 формує iframe-запит до вашого handler URL з параметрами:
GET https://your-app.com/handler? DOMAIN=company.bitrix24.ua& PROTOCOL=1& AUTH_ID=abc123& AUTH_EXPIRES=3600& REFRESH_ID=xyz789& member_id=a1b2c3& PLACEMENT=CRM_DEAL_DETAIL_TAB& PLACEMENT_OPTIONS={"ID":"42","SECTION":""} AUTH_ID живе 1 годину. Для довготривалих сесій (користувач залишив вкладку відкритою) потрібен refresh:
BX24.init(() => { // Автоматично оновлює токен, якщо він закінчився BX24.getAuth((auth) => { // auth.access_token — актуальний токен fetch('/api/data', { headers: { 'X-Bitrix-Auth': auth.access_token } }); }); }); На вашому сервері перевіряйте токен через REST-метод rest/profile.
Порівняння вбудованого додатку та звичайного віджета
| Характеристика | Віджет | Вбудований додаток |
|---|---|---|
| Робота з інтерфейсом | Тільки читання | Читання та запис |
| Швидкість роботи з CRM | З перезавантаженням | Без перезавантаження |
| Підписка на події | Ні | Так |
| Прямий доступ до JS SDK | Ні | BX24 |
Вбудований додаток працює в 10 разів швидше, оскільки використовує JS SDK для прямого керування елементами CRM. Він також може підписуватися на події в реальному часі, що важливо для синхронізації із зовнішніми системами.
Як відбувається розробка вбудованого додатку: 5 етапів
- Аналіз — виявляємо, які плейсменти потрібні, які зовнішні API будуть задіяні, фіксуємо терміни.
- Проектування — створюємо схему авторизації, визначаємо структуру handler та серверної частини.
- Реалізація — пишемо клієнтський код на JS (React/Vue/Vanilla) з BX24 SDK, серверний компонент на Express/Fastify.
- Тестування — налагодження на dev-порталі через ngrok з mock-параметрами, перевірка refresh токенів.
- Деплой та підтримка — розгортаємо на production, підключаємо моніторинг, навчаємо співробітників.
Структура проекту
Мінімальна структура:
-
/public/index.html— точка входу (handler URL) -
/public/app.js— клієнтський код з BX24 SDK -
/src/api/bitrix.js— обгортка над BX24.callMethod -
/src/api/external.js— запити до зовнішнього API -
/src/components/DealTab.jsx— React/Vue/Vanilla -
server.js— Express/Fastify для OAuth callback та API proxy
Серверний компонент необхідний, тому що OAuth callback (/oauth/callback) повинен оброблятися на сервері, client_secret не можна виносити в браузер, проксіювання запитів до зовнішніх API уникає CORS-проблем.
Що входить у розробку вбудованого додатку
Чек-лист deliverables
- Документація REST API та схеми авторизації - Доступ до тестового порталу та ngrok-тунелю - Навчання співробітників (2-годинний вебінар) - Підтримка протягом 1 місяця після запуску - Вихідний код у Git-репозиторіїТерміни розробки
| Масштаб | Що включає | Термін |
|---|---|---|
| MVP | 1 плейсмент, читання даних CRM, без зовнішніх інтеграцій | 3–5 днів |
| Стандарт | 2–3 плейсменти, запис у CRM, проста зовнішня інтеграція | 1–2 тижні |
| Просунутий | 5+ плейсментів, двостороння синхронізація із зовнішньою системою, OAuth | 3–6 тижнів |
| Тиражний для Маркету | Повний цикл з модерацією та документацією | 2–3 місяці |
Критичний момент: перед стартом узгодьте список плейсментів — додавання нового після публікації тиражного додатку вимагає повторної модерації.
Типові помилки та як їх уникнути
- Налагодження всередині iframe: використовуйте пряме відкриття handler URL з mock-параметрами.
- Забувають про refresh токенів: завжди реалізуйте автоматичне оновлення через
BX24.init(). - Не враховують CORS: проксіюйте запити до зовнішніх API через свій сервер.
Чому варто замовити розробку вбудованого додатку у нас
Ми на ринку понад 7 років, розробили 50+ вбудованих додатків. Гарантуємо якість: кожен проект проходить триетапне тестування на dev-порталі з ngrok. Середній проект окупається за 3-6 місяців за рахунок скорочення операційних витрат. Зв'яжіться з нами для консультації та оцінки вашого проекту. Замовте розробку вбудованого додатку, який ідеально впишеться в бізнес-процеси вашої компанії. Отримайте попередню оцінку термінів та бюджету — ми завжди розраховуємо вартість індивідуально.
Детальніше про OAuth 2.0 читайте на Wikipedia. Документація по BX24 SDK — dev.1c-bitrix.ru.