Невидимый виджет на каждой странице PAGE_BACKGROUND_WORKER

Scope: placement

Вы можете добавить "невидимый" виджет, который будет выводиться на всех страницах Битрикс24. Именно этот виджет позволяет реализовывать сценарий с внешним WebRTC-клиентом в интеграциях с телефониями, однако это не единственный возможный сценарий использования.

Например, с помощью механизма интерактивного взаимодействия backend- и frontend-приложения, можно отправлять "сигнал" в виджет PAGE_BACKGROUND_WORKER, а по получении "сигнала", открывать слайдер приложения с помощью метода openApplication.

Код места встройки виджета указывается в параметре PLACEMENT метода placement.bind.

Встройка не будет отображаться в интерфейсе, пока установка приложения не завершена. Проверьте установку приложения

Особенности регистрации обработчика виджета

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

Поскольку загрузка этого виджета происходит всегда и на всех страницах, обработчик, который грузится дольше 3-5 секунд, может вызывать задержки в формировании пользовательского интерфейса Битрикс24. Если это происходит более 10 раз в течение суток на одном и том же Битрикс24, то обработчик будет автоматически отключен.

Битрикс24 проинформирует приложение об отключении обработчика. Для этого, в методе placement.bind, необходимо указать URL в параметре OPTIONS[errorHandlerUrl]. Битрикс24 будет вызывать этот URL в случае отключения обработчика виджета PAGE_BACKGROUND_WORKER.

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"PLACEMENT":"PAGE_BACKGROUND_WORKER","HANDLER":"http://myapp.com/handler/?type=1","OPTIONS":{"errorHandlerUrl":"http://myapp.com/error/"}}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/placement.bind
        
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"PLACEMENT":"PAGE_BACKGROUND_WORKER","HANDLER":"http://myapp.com/handler/?type=1","OPTIONS":{"errorHandlerUrl":"http://myapp.com/error/"},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/placement.bind
        
try
        {
        	const response = await $b24.callMethod(
        		"placement.bind",
        		{ 
        			PLACEMENT: "PAGE_BACKGROUND_WORKER",
        			HANDLER: "http://myapp.com/handler/?type=1",
        			OPTIONS: {
        				errorHandlerUrl: "http://myapp.com/error/"
        			}
        		}
        	);
        	
        	const result = response.getData().result;
        	if(result.error())
        		console.error(result.error());
        	else
        		console.info(result);
        }
        catch(error)
        {
        	console.error('Error:', error);
        }
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'placement.bind',
                    [
                        'PLACEMENT' => 'PAGE_BACKGROUND_WORKER',
                        'HANDLER'   => 'http://myapp.com/handler/?type=1',
                        'OPTIONS'   => [
                            'errorHandlerUrl' => 'http://myapp.com/error/'
                        ]
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            if ($result->error()) {
                error_log($result->error());
            } else {
                echo 'Success: ' . print_r($result->data(), true);
            }
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error binding placement: ' . $e->getMessage();
        }
        
BX24.callMethod(
            "placement.bind",
            { 
                PLACEMENT: "PAGE_BACKGROUND_WORKER",
                HANDLER: "http://myapp.com/handler/?type=1",
                OPTIONS: {
                    errorHandlerUrl: "http://myapp.com/error/"
                }
            },
            function(result)
            {
                if(result.error())
                    console.error(result.error());
                else
                    console.info(result.data());
            }
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'placement.bind',
            [
                'PLACEMENT' => 'PAGE_BACKGROUND_WORKER',
                'HANDLER' => 'http://myapp.com/handler/?type=1',
                'OPTIONS' => [
                    'errorHandlerUrl' => 'http://myapp.com/error/'
                ]
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';
        

Что получает обработчик

Данные передаются в виде POST-запроса


        Array
        (
            [handler] => 1
            [DOMAIN] => restapi.bitrix24.ru
            [PROTOCOL] => 1
            [LANG] => ru
            [APP_SID] => 588b8a98e848778a4ffb38fbcf70f2b9
            [AUTH_ID] => 4172bb6600705a0700005a4b00000001f0f107c42ca5bd5f61030c5d9c3e4d60d11b5a
            [AUTH_EXPIRES] => 3600
            [REFRESH_ID] => 31f1e26600705a0700005a4b00000001f0f107b1918506d8a2ed9ecf76e8fdac962471
            [member_id] => da45a03b265edd8787f8a258d793cc5d
            [status] => L
            [PLACEMENT] => PAGE_BACKGROUND_WORKER
            [PLACEMENT_OPTIONS] => {"ID":"PAGE_BACKGROUND_WORKER","URI":"\/company\/personal\/user\/1\/blog\/"}
        )
        
        

Обязательные параметры отмечены *

Параметр
тип

Описание

DOMAIN*
string

Адрес Битрикс24, на котором был вызван обрабтчик виджета

PROTOCOL*
string

Защищенный или не защищенный протокол HTTP:

  • 0 - HTTP
  • 1 - HTTPS

LANG*
string

Язык интерфейса пользователя Битрикс24, который вызвал виджет. Вы можете локализовать язык интерфейса в своём виджете, ориентируясь на это значение

APP_SID
string

Строковый идентификатор приложения, зарегистрировавшего обработчик виджета

AUTH_ID
string

Авторизационный токен OAuth 2, выписанный для пользователя, вызвавшего виджет. Можно использовать для вызовов REST API от лица этого пользователя

AUTH_EXPIRES
integer

Время в секундах, после которого авторизационный токен станет неактуальным

REFRESH_ID
string

Refresh-токен OAuth 2, выписанный для пользователя, вызвавшего виджет. Можно использовать для обновления авторизационного токена от лица этого пользователя

member_id*
string

Уникальный строковый идентификатор Битрикс24, на котором был вызван обработчик виджета.

status
string

Тип приложения, зарегистрировавшего обработчик данного виджета. Принимает значения:

PLACEMENT*
string

Код места встройки виджета. Вы можете использовать один и тот же URL обработчика для всех своих виджетов. Значение, которое Битрикс24 будет сообщать в параметре PLACEMENT, поможет определить, из какого именно места встройки виджета был вызван ваш обработчик в каждом конкретном случае

PLACEMENT_OPTIONS
string

Дополнительные данные в виде JSON-строки, определяющие контекст выполнения виджета. Например, это может быть массив, содержащий числовой идентификатор элемента CRM, в карточке которого был вызван обработчик виджета, и т.д. Параметр PLACEMENT_OPTIONS вместе с параметром PLACEMENT позволяет точно определить, для какого именно места встройки виджета и объекта был вызван обработчик виджета.

PLACEMENT_OPTIONS

Значением PLACEMENT_OPTIONS является JSON-строка, содержащая массив из одного и более ключей.

Обязательные параметры отмечены *

Параметр

Описание

ID*
string

Всегда равен PAGE_BACKGROUND_WORKER и используется для внутренних нужд

URI*
string

Экранированный с помощью urlencode адрес текущей страницы, на которой был открыт виджет.

Частые кейсы и сценарии

Продолжите изучение