Интерфейсные события placement

Встройка (placement) работает в iframe, но не изолирована: через BX24 JS SDK она читает контекст, подписывается на события интерфейса и отправляет ему команды. Это превращает статичную вставку в живую часть карточки.

Модель взаимодействия placement и интерфейса

Приложение встраивается в интерфейс Битрикс24 как iframe в заранее объявленном месте (placement). Прямого доступа к DOM портала у него нет из-за политики безопасности, поэтому весь обмен идёт через postMessage, обёрнутый в методы BX24.placement.*.

Обмен двусторонний:

• Контекст — приложение узнаёт, в каком месте и над какой сущностью оно открыто;
• События — интерфейс уведомляет приложение об изменениях;
• Команды — приложение просит интерфейс что-то сделать: перезагрузить данные, открыть окно, отметить дело.

Чтение контекста: placement.info

Первое, что делает встройка, — узнаёт свой контекст. Метод BX24.placement.info() синхронно возвращает объект с кодом места и параметрами.

var info = BX24.placement.info();
// { placement: "CRM_DEAL_DETAIL_TAB",
//  options: { ID: "142", ENTITY_ID: "142" } }

Поле placement сообщает, где именно открыто приложение, а options несёт данные контекста — чаще всего ID сущности. По нему приложение дозапрашивает подробности через REST, например crm.item.get. Один и тот же обработчик стоит писать так, чтобы он корректно вёл себя в разных placement, опираясь на это поле.

Что доступно: placement.getInterface

Набор событий и команд зависит от места встройки. Не гадайте — спросите платформу. Метод BX24.placement.getInterface(callback) вернёт список доступных команд и событий для текущего placement.

BX24.placement.getInterface(function(res){
  console.log(res.command); // доступные команды
  console.log(res.event);   // доступные события
});

Подписка на события: placement.bindEvent

Чтобы встройка реагировала на действия пользователя в карточке, она подписывается на события интерфейса методом BX24.placement.bindEvent(eventName, callback).

BX24.placement.bindEvent('onCrmEntityUpdate', function(data){
  // пользователь сохранил карточку — обновляем виджет
  reloadWidget();
});

Типовые сценарии подписки:

• Пользователь сохранил сущность — пересчитать показатели во встройке;
• Сменилась стадия сделки — обновить рекомендацию;
• Изменился контекст вкладки — перезагрузить данные.

Команды интерфейсу: placement.call

Обратное направление — приложение управляет интерфейсом. Метод BX24.placement.call(command, params, callback) отправляет интерфейсу команду из доступного набора.

Что обычно умеет placement в карточке CRM:

• Перезагрузить данные сущности после изменения через приложение;
• Открыть карточку другой сущности или всплывающее окно приложения;
• Инициировать действие в таймлайне или закрыть слайдер.

BX24.placement.call('reloadData', {}, function(){
  console.log('карточка обновлена');
});

Список конкретных команд снова берётся из getInterface — он зависит от места встройки и версии портала. Такой подход держит приложение совместимым при обновлениях Битрикс24.

Отладка и типичные ошибки

Обмен через iframe и postMessage чувствителен к деталям окружения. Вот что чаще всего ломает интерфейсные события.

Логируйте placement.info() и результат getInterface при старте — это первый шаг диагностики почти любой проблемы со встройкой.

Отдельно проверяйте, что обработчик отдаёт корректные заголовки для встраивания в iframe: политика X-Frame-Options и Content-Security-Policy не должны запрещать фрейминг доменом Битрикс24. Если страница открывается напрямую, но пустует внутри портала, причина почти всегда в этих заголовках или в отсутствии валидного HTTPS-сертификата.

Сценарий: живой виджет в карточке сделки

Соберём полную картину на примере встройки во вкладку карточки сделки, которая показывает сводку из внешнего сервиса и обновляется при изменениях. Это классический случай, где задействованы все четыре механизма.

1. После BX24.init вызываем placement.info и получаем ID сделки;
2. Запрашиваем данные через crm.item.get и рисуем сводку;
3. Через getInterface убеждаемся, что доступно нужное событие и команда;
4. Подписываемся bindEvent на изменение сущности и перерисовываем виджет;
5. По кнопке в виджете отправляем placement.call для перезагрузки карточки.

Такой виджет ощущается как родная часть интерфейса: пользователь меняет стадию, карточка сохраняется, интерфейс шлёт событие, а встройка мгновенно пересчитывает показатели без ручного обновления страницы.

Итог

Интерфейсные события placement превращают iframe в полноценный элемент интерфейса Битрикс24. Схема простая: info даёт контекст, getInterface — доступные команды и события, bindEvent подписывает на изменения, call управляет интерфейсом. Главное — не путать их с серверными REST-событиями и всегда инициализировать SDK.

Мы разрабатываем встройки, которые живо реагируют на действия пользователя в карточках CRM и корректно управляют интерфейсом. Если вам нужен placement с двусторонним обменом и устойчивостью к обновлениям портала, поможем спроектировать и реализовать его без хрупких привязок.