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

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

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

Типы обновлений и их сложность

Не все обновления одинаково трудоёмки. Важно сразу классифицировать, что именно меняется:

Патч (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-страницу Битрикс24 → 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): заполнять обязательно — это читает модератор
• Минимальная версия Битрикс24: если новая функция требует API методов, появившихся в конкретной версии Б24, указать это ограничение

После одобрения модерацией новая версия публикуется. Пользователи, у которых уже установлено приложение, не получают уведомление об обновлении автоматически — уведомление о новой версии появляется только в интерфейсе Битрикс24 в разделе управления приложениями. Важную информацию об обновлениях лучше показывать непосредственно в интерфейсе приложения при открытии.

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