Оновлення програми в маркетплейсі Бітрікс24

Оновлення додатка в маркетплейсі Bitrix24

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

Типи оновлень й їх складність

Не всі оновлення однаково трудомісткі. Важливо одразу класифікувати, що саме змінюється:

Патч (bugfix, дрібні правки UI) — код оновлюється на сервері, у особистому кабінеті партнера інкрементується номер версії, модерація проходить за 3–5 днів. Якщо не змінюються скоупи, placement-точки й монетизація — це найпростіший сценарій.

Мінорне оновлення (нові функції, не вимагаючи нові скоупи) — код + опис у карточці маркетплейсу + скриншоти. Модерація 5–10 днів. Потрібно оновити changelog версії у карточці додатка — перевіряючий читає його при ревю.

Мажорне оновлення — додавання нових скоупів OAuth, зміна моделі монетизації, нові placement-точки. Вимагає повного циклу модерації (7–14 днів). При додаванні нових скоупів існуючі інсталяції не отримують їх автоматично — користувачі мають переустановити додаток або явно підтвердити розширення прав.

Критичні зміни з міграцією даних — зміна схеми БД додатка, зміна формату зберігання даних. Вимагає написання й тестування міграцій, які коректно відпрацюють для тисяч member_id.

Проблема розширення OAuth-скоупів

Це технічна особливість, про яку важливо знати заранее. Коли ви додаєте новий скоуп у параметрах додатка, існуючі токени у встановивших користувачів не включають цей скоуп. Виклик методу, що вимагає новий скоуп, повертає {"error":"ACCESS_DENIED"}.

Варіанти рішення:

1. Примусова переустановка. При відкритті додатка перевіряємо список скоупів у поточному токені (scope поле у відповіді app.info). Якщо потрібний скоуп відсутня — показуємо UI з поясненням й кнопкою «Переустановити додаток».

2. Інкрементальне розширення. Додатковий OAuth-флоу з запитом тільки нового скоупу. Користувач натискає кнопку у додатку → редирект на OAuth-сторінку Bitrix24 → confirm → новий токен зберігається.

3. Проектування наперед. При первинній розробці запрошувати усі скоупи, які можуть знадобитися у майбутніх версіях. Зайві скоупи — ризик на етапі модерації, але краще обговорити їх призначення в описі.

Міграції даних при оновленні

Якщо додаток зберігає дані у власній БД й схема змінюється — потрібна міграційна стратегія.

Схема, яка працює для multi-tenant додатка:

1. Усі міграції нумеруються послідовно й зберігаються в коді
2. У БД є таблиця schema_migrations з номерами застосованих міграцій
3. При деплої запускається мігратор: застосовує усі непримінені міграції
4. Міграції пишуться з backward compatibility — нові nullable колонки, не видалення старих

Специфіка multi-tenant: якщо міграція змінює структуру даних конкретної інсталяції (наприклад, конвертує формат зберігання), потрібна поетапна міграція з батчингом — не намагайтесь обробити одразу 50 000 рядків в одній транзакції.

Оновлення placement'ів й обробників подій

При зміні списку placement-точок або URL обробників подій (event.bind) у вже установлених порталів старі реєстрації залишаються в силі. Нові placement'и й handlers потрібно реєструвати програмно для кожного активного member_id.

Підхід: при оновленні версії запускається job, який для кожного активного member_id викликає відповідні методи реєстрації. Це робиться у фоновому воркері з rate limiting (не більше 2 запитів/сек на портальне).

# Псевдокод оновлення placements для всіх інсталяцій
for installation in get_active_installations():
    api_client = BitrixClient(installation.member_id)
    api_client.call('placement.bind', {
        'PLACEMENT': 'NEW_PLACEMENT_POINT',
        'HANDLER': 'https://app.example.com/iframe/new-feature',
        'TITLE': 'Нова функція'
    })
    time.sleep(0.5)  # Rate limit

Версіонування у особистому кабінеті партнера

У partner.bitrix24.ru при оновленні додатка:

• Номер версії: рекомендується semver (1.2.3), але технічно це просто строка
• Опис змін версії (changelog): заповнювати обов'язково — це читає модератор
• Мінімальна версія Bitrix24: якщо нова функція вимагає API методів, що з'явилися у конкретній версії Б24, указати це обмеження

Після одобрення модерацією нова версія публікується. Користувачі, у яких уже встановлено додаток, не отримують сповіщення про оновлення автоматично — сповіщення про нову версію з'являється тільки в інтерфейсі Bitrix24 у розділі управління додатками. Важливу інформацію про оновлення краще показувати безпосередньо в інтерфейсі додатка при відкритті.

Строки оновлення