Не все места встройки видны в интерфейсе приложения

Суть проблемы

В интерфейсе добавления встройки могут отображаться не все места, которые доступны через REST. Из-за этого кажется, что нужный вариант нельзя подключить к приложению.

Коротко

У Bitrix24 есть отдельный механизм виджетов и мест встройки. Конкретное место задаётся кодом в параметре PLACEMENT.

Если нужного варианта нет в визуальном интерфейсе настройки приложения, можно проверить код места в документации и зарегистрировать его методом placement.bind.

Типовая ситуация выглядит так:

нужно добавить виджет в конкретное место интерфейса Bitrix24;
в настройках приложения нужного пункта нет;
в документации у места встройки есть код PLACEMENT;
обработчик регистрируется вручную через placement.bind;
после установки приложения виджет появляется в нужном месте.

Где встречается

Такое может встретиться при работе с локальными приложениями и виджетами:

в CRM-карточках;
в списках CRM;
в задачах;
в мессенджере;
в открытых линиях;
в контакт-центре;
в фоновых или универсальных виджетах.

Главное — сначала найти точный код места встройки. Название в интерфейсе и технический код PLACEMENT — это разные вещи.

Решение

Нужное место встройки можно добавить вручную через REST-метод placement.bind.

Зарегистрировать место вручную

Для регистрации обычно нужны:

код места встройки в параметре PLACEMENT;
URL обработчика в параметре HANDLER;
название пункта, вкладки или кнопки в параметре TITLE;
нужные права приложения, включая placement и scope конкретного раздела;
завершённая установка приложения.

Чаще всего такие вызовы удобно делать во время установки приложения. Тогда после установки приложение уже имеет все нужные встройки.

Пример placement.bind

Пример ниже регистрирует вкладку в карточке сделки. Код места встройки нужно заменить на тот, который нужен в конкретной задаче.

BX24.callMethod(
    'placement.bind',
    {
        PLACEMENT: 'CRM_DEAL_DETAIL_TAB',
        HANDLER: 'https://example.com/local/apps/deal-tab/',
        TITLE: 'Моя вкладка',
        LANG_ALL: {
            ru: {
                TITLE: 'Моя вкладка',
            },
            en: {
                TITLE: 'My tab',
            },
        },
    },
    function (result) {
        if (result.error()) {
            console.error(result.error());

            return;
        }

        console.log('Встройка зарегистрирована');
    }
);

После регистрации нужно проверить не только успешный ответ метода, но и то, завершена ли установка приложения. Иначе виджет может быть зарегистрирован, но не отображаться обычным пользователям.

Что проверить

Если виджет не появился, не стоит сразу менять обработчик. Сначала нужно проверить место встройки, права и состояние установки приложения.

Список доступных мест

Метод placement.list помогает посмотреть, какие места встраивания доступны приложению.

BX24.callMethod(
    'placement.list',
    {
        SCOPE: 'crm',
    },
    function (result) {
        if (result.error()) {
            console.error(result.error());

            return;
        }

        console.log(result.data());
    }
);

Если нужного места нет в результате, нужно проверить scope приложения. Для разных разделов Bitrix24 могут требоваться разные права.

Список зарегистрированных обработчиков

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

BX24.callMethod(
    'placement.get',
    {},
    function (result) {
        if (result.error()) {
            console.error(result.error());

            return;
        }

        console.log(result.data());
    }
);

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

Что важно помнить

Визуальный интерфейс настройки приложения не всегда удобен как полный справочник всех мест встройки.

Если нужного пункта нет в интерфейсе, сначала проверьте документацию по местам встройки.
Для ручной регистрации нужен точный код PLACEMENT.
Метод placement.bind должен вызываться от администратора или в подходящем контексте установки приложения.
Для некоторых мест нужны дополнительные scope приложения.
Если установка приложения не завершена, виджет может не отображаться, даже если регистрация прошла успешно.
Один и тот же тип встройки может поддерживать несколько обработчиков, если само место встройки это позволяет.