Placement — это механизм, который позволяет приложению встраивать свои страницы прямо в интерфейс Битрикс24: в карточки CRM, меню, панели инструментов и всплывающие окна. Разберём, как привязать встройку, какие бывают точки встраивания и как обработчик получает контекст текущего объекта.
Что такое placement
Каждая точка встраивания в Битрикс24 имеет символьный код — например, CRM_DEAL_DETAIL_TAB (вкладка в карточке сделки) или LEFT_MENU (пункт левого меню). Приложение регистрирует по этому коду свою страницу, и портал показывает её в соответствующем месте интерфейса.
Встройка работает через iframe: портал открывает URL вашего обработчика внутри своего интерфейса и передаёт ему авторизацию и контекст. Внутри фрейма вы используете BX24.js для взаимодействия с порталом.
placement. Без него методы placement.* вернут ошибку доступа.Привязка встройки: placement.bind
Встройка регистрируется методом placement.bind. Минимальный набор — код места, URL обработчика и заголовок:
BX24.callMethod('placement.bind', { PLACEMENT: 'CRM_DEAL_DETAIL_TAB', HANDLER: 'https://app.example.ru/deal-tab', TITLE: 'Аналитика' });
Основные методы управления встройками:
| Метод | Назначение |
|---|---|
placement.bind | Привязать обработчик к точке встраивания |
placement.unbind | Удалить привязку |
placement.list | Список доступных мест встраивания |
placement.get | Список текущих привязок приложения |
Привязку обычно делают на этапе установки, чтобы встройки появились сразу после подключения.
Популярные точки встраивания
Мест встраивания десятки, и их набор зависит от установленных на портале модулей. Наиболее востребованные:
CRM_DEAL_DETAIL_TAB,CRM_LEAD_DETAIL_TAB,CRM_CONTACT_DETAIL_TAB— вкладки в карточках сущностей CRM.CRM_DEAL_DETAIL_TOOLBAR— кнопка на панели инструментов карточки.CRM_DEAL_LIST_MENU,CRM_DEAL_LIST_TOOLBAR— действия в списке сделок.CRM_DEAL_DETAIL_ACTIVITY— блок в таймлайне карточки.LEFT_MENU— пункт в левом меню портала.CALL_CARD— панель в карточке звонка телефонии.TASK_VIEW_TAB— вкладка в задаче.
Актуальный перечень для конкретного портала всегда получайте методом placement.list — не полагайтесь на «зашитый» список кодов.
Контекст встройки и BX24.placement
Когда портал открывает обработчик, он передаёт контекст: какой объект открыт, какой пользователь смотрит, какие опции заданы. В JS контекст доступен через BX24.placement.info():
var p = BX24.placement.info(); // p.placement, p.options
Например, во вкладке карточки сделки в p.options.ID придёт идентификатор сделки — по нему вы запросите данные через crm.deal.get. Часть мест поддерживает обратный вызов: метод BX24.placement.call('...') позволяет из встройки управлять интерфейсом портала — обновить таймлайн или открыть карточку.
placement.info() приходят в браузер и могут быть подменены. Прежде чем показывать данные, валидируйте права пользователя и принадлежность объекта на своём бэкенде.Управление окном встройки
Встройка живёт в iframe фиксированных размеров, поэтому важно управлять его габаритами. Библиотека даёт несколько методов:
BX24.fitWindow()— подогнать высоту фрейма под содержимое.BX24.resizeWindow(width, height)— задать размеры вручную.BX24.openApplication()— открыть приложение в модальном слайдере поверх интерфейса.BX24.closeApplication()— закрыть слайдер приложения.BX24.openPath(path)— перевести пользователя на страницу портала.
Для компактных встроек (кнопка на тулбаре, пункт меню) удобно открывать основную логику в слайдере через openApplication, а саму встройку держать минимальной.
Практические нюансы
Несколько вещей, которые экономят время на реальных проектах:
- Один обработчик может обслуживать несколько мест — различайте их по
p.placementиз контекста и ветвите логику. - При обновлении приложения меняйте привязки аккуратно: лишние
bindбезunbindприводят к дублям встроек. - Заголовок и локализацию задавайте через параметры
TITLEиLANG_ALLдля мультиязычных порталов. - Учитывайте, что не на всех тарифах доступны все места — тестируйте на нужной редакции.
Итог
Placement превращает внешний веб-сервис в органичную часть интерфейса Битрикс24: вкладки в карточках CRM, кнопки на панелях, пункты меню и панели звонков. Ключевые инструменты — метод placement.bind для привязки, placement.list для актуального перечня мест и BX24.placement.info() для получения контекста. Не забывайте валидировать контекст на сервере и управлять размерами окна.
Если нужно встроить внешнюю логику или аналитику прямо в рабочие места менеджеров, мы в B2Bsite спроектируем встройки так, чтобы они были удобными, безопасными и совместимыми с обновлениями платформы.
Частые вопросы
Какое право нужно для встроек?
Право placement. Без него методы группы placement.* вернут ошибку доступа, а встройки не появятся.
Как узнать список доступных мест на портале?
Вызвать метод placement.list — он вернёт актуальные коды точек встраивания для конкретного портала с учётом установленных модулей и тарифа.
Где брать ID открытого объекта?
В контексте встройки через BX24.placement.info(): в options приходят параметры, например ID сделки для вкладки карточки.
Можно ли из встройки управлять интерфейсом портала?
Да, для ряда мест доступен BX24.placement.call — им можно, например, обновить таймлайн или инициировать действие в карточке.
Как подогнать размер окна встройки?
Использовать BX24.fitWindow для автоподгонки высоты под контент или BX24.resizeWindow для явного задания размеров.
Почему появились дубли встроек?
Обычно из-за повторных вызовов placement.bind без предварительного unbind при обновлении приложения. Управляйте привязками идемпотентно.
Безопасен ли контекст из placement.info?
Он приходит в браузер и может быть подменён, поэтому все проверки прав и принадлежности объекта нужно дублировать на своём сервере.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.