Розробка вбудовуваних програм Бітрікс24

Розробка вбудованих застосунків Bitrix24

Вбудовані застосунки — це не просто «вікно в iframe». Коли менеджер працює в картці угоди та бачить вкладку з історією відвантажень з вашої WMS, маючи можливість прямо там створити новий замовлення — це результат правильно побудованого вбудованого застосунку. Відмінність від звичайного віджету в тому, що вбудований застосунок має двосторонню взаємодію з інтерфейсом Bitrix24 і може керувати його станом.

Що таке вбудований застосунок у термінології Bitrix24

У документації Bitrix24 вбудовані застосунки (Embedded Apps) — це застосунки з типом IFRAME, які реєструють плейсменти та працюють усередині інтерфейсу порталу. На відміну від зовнішніх (серверних) застосунків, вони мають прямий доступ до JS SDK BX24 і можуть:

• читати та змінювати поля відкритої картки CRM у реальному часі без перезавантаження сторінки
• викликати діалоги, слайдери та сповіщення Bitrix24 (BX24.openPath, BX24.showMessagePopup)
• підписуватися на події інтерфейсу через BX24.placement.call('getInterface', ...)

Життєвий цикл та авторизація

При відкритті вкладки із застосунком Bitrix24 формує iframe-запит до вашого handler URL із параметрами:

GET https://your-app.com/handler?
    DOMAIN=company.bitrix24.ru&
    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 }
        });
    });
});

На вашому сервері перевіряйте токен через:

GET https://company.bitrix24.ru/rest/profile?auth=ACCESS_TOKEN

Взаємодія з CRM-карткою в реальному часі

Найцінніша можливість вбудованих застосунків — читання та запис полів картки без перезавантаження сторінки.

Підписка на зміну поля в картці:

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('Поле оновлено в інтерфейсі');
});

Повний список подій і методів placement залежить від типу картки (CRM_DEAL, CRM_LEAD, CRM_CONTACT, CRM_COMPANY) — у кожної своя документація.

Структура проєкту вбудованого застосунку

Мінімальна структура:

/app
  /public
    index.html        # Точка входу (handler URL)
    app.js            # Клієнтський код із BX24 SDK
  /src
    /api
      bitrix.js       # Обгортка над BX24.callMethod
      external.js     # Запити до зовнішнього API
    /components
      DealTab.jsx     # React/Vue/Vanilla — що завгодно
  server.js           # Express/Fastify для OAuth callback та API proxy

Чому потрібен серверний компонент навіть для «клієнтського» застосунку: OAuth callback (/oauth/callback) повинен оброблятися на сервері, client_secret не можна виносити в браузер, проксування запитів до зовнішніх API уникає CORS-проблем.

Робота з подіями через BX24.placement

Різні плейсменти надають різний набір методів. Для CRM_DEAL_DETAIL_TAB:

// Отримати інтерфейс поточного плейсменту
BX24.placement.call('getInterface', {}, (interfaceData) => {
    /*
    interfaceData містить:
    {
        ID: "42",           // ID угоди
        ENTITY_TYPE: "CRM_TYPE_DEAL",
        FIELDS: { ... },   // Поточні значення полів
        BUTTONS: [ ... ]   // Доступні кнопки
    }
    */
});

Публікація та встановлення

Вбудовані застосунки можуть бути:

1. Локальними — доступні тільки на одному порталі, встановлюються через налаштування розробника
2. Тиражними — публікуються в Bitrix24 Market, проходять модерацію

Для локального встановлення достатньо зареєструвати застосунок у /devops/ та вказати handler URL. Для тиражного — потрібен SSL, коректний manifest.json і проходження ревю Bitrix.

Тестування

Найпоширеніша проблема при розробці — налагодження всередині iframe. Браузерні DevTools не відкриваються в контексті iframe Bitrix24 напряму. Рішення:

• Відкривайте handler URL напряму в браузері з mock-параметрами для налагодження UI
• Використовуйте ngrok або localtunnel для локального сервера з HTTPS (Bitrix24 вимагає HTTPS навіть на dev)
• Логуйте через BX24.console.log() — повідомлення з'являться в консолі батьківського вікна

Терміни розробки

Критичний момент: перед початком розробки узгодьте із замовником список плейсментів — додавання нового плейсменту після публікації тиражного застосунку вимагає повторного проходження модерації.