Добавить виджет на Главную страницу: наш вайб landing.repowidget.register

Scope: landing

Кто может выполнять метод: любой пользователь

Метод landing.repowidget.register добавляет виджет для Главной страницы: наш вайб. Возвращает ошибку или идентификатор ID добавленного виджета.

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

Параметры метода

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

Название
тип

Описание

code*
string

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

fields*
object

Значения полей для создания виджета

Параметр fields

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

Название
тип

Описание

NAME
string

Название виджета

PREVIEW
string

URL картинки-обложки виджета для слайдера выбора виджетов

DESCRIPTION
string

Описание виджета

CONTENT
string

Верстка виджета с использованием конструкций Vue

SECTIONS
string

Код раздела, в который будет добавлен виджет. Список доступных разделов:

  • widgets_company_life — Жизнь компании
  • widgets_new_employees — Новым сотрудникам
  • widgets_team — Команда
  • widgets_automation — Автоматизация
  • widgets_events — Встречи и события
  • widgets_profile — Профиль сотрудника
  • widgets_tasks — Задачи и проекты
  • widgets_sales — Продажи и клиенты
  • widgets_hr — HR
  • widgets_other — Другое
  • widgets_separators — Переходы и разделители
  • widgets_text — Текст
  • widgets_image — Картинки
  • widgets_video — Видео

WIDGET_PARAMS
object

Параметры для vue-шаблонизатора. Если их нет, то блок останется обычным html-кодом с {{}}

ACTIVE
char

Активность виджета. Принимает значения:

  • Y - виджет активен и доступен
  • N - виджет неактивен и недоступен

SITE_TEMPLATE_ID
string

Привязка виджета к определенному шаблону сайта. Только для коробочного Битрикс24!

Параметр WIDGET_PARAMS

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

Название
тип

Описание

rootNode*
string

Селектор корневого элемента в верстке, который будет превращен во vue-component. Корневой элемент должен быть единственным элементом в передаваемом шаблоне, вся остальная разметка будет очищена

lang
string

Массив языковых фраз, использующихся в конструкциях {{$Bitrix.Loc.getMessage('W_EMPTY')}}

handler*
string

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

Важно: Обработчик должен быть доступен из внешней сети! Проверяйте доступность обработчика специальными сервисами

style
string

Адрес стилей для виджета. Стили также могут быть заданы инлайново в разметке через привязку :style="{borderBottom: '1px solid red'}"

demoData*
object

Демо-данные для виджета, которые будут использованы для демонстрации виджета в шаблонах Вайба в Битрикс24 Маркетплейс.

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

Однако, если вы готовите тиражное решение с виджетом, уделите демонстрационным данным максимальное внимание — именно они будут отображаться в слайдере предварительного просмотра шаблона Вайба! Очевидно, что структура демо-данных должна соответствовать той, которую вернул бы ваш обработчик handler в обычном режиме использования виджета

Примеры кода

Как использовать примеры в документации

try
        {
        	const response = await $b24.callMethod(
        		'landing.repowidget.register',
        		data
        	);
        	
        	const result = response.getData().result;
        	
        	if (result.error())
        	{
        		console.error(result.error());
        		return;
        	}
        	
        	console.info(result);
        }
        catch( error )
        {
        	console.error('Error:', error);
        }
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'landing.repowidget.register',
                    [
                        'code'    => 'my_widget',
                        'fields'  => [
                            'NAME'         => 'My widget',
                            'PREVIEW'      => 'https://my-app.com/vibe_preview.jpg',
                            'CONTENT'      => $content,
                            'SECTIONS'     => 'widgets_company_life',
                            'WIDGET_PARAMS' => [
                                'rootNode' => '.my-app-w-container',
                                'lang'     => [
                                    'ru' => [
                                        'W_TITLE' => 'Люди и их возраст',
                                        'W_EMPTY' => 'Нет людей',
                                    ],
                                    'en' => [
                                        'W_TITLE' => 'People and their ages',
                                        'W_EMPTY' => 'Empty',
                                    ],
                                ],
                                'handler'   => 'https://my-app.com/vibe.php',
                                'style'     => 'https://my-app.com/vibe.css',
                                'demoData'  => [
                                    'desc'    => 'Just a test widget',
                                    'count'   => 420,
                                    'persons' => [
                                        ['name' => 'Person 1', 'age' => 21],
                                        ['name' => 'Person 2', 'age' => 42],
                                        ['name' => 'Person 3', 'age' => 123],
                                    ],
                                ],
                            ],
                        ],
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
            // Нужная вам логика обработки данных
            processData($result);
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error registering repowidget: ' . $e->getMessage();
        }
        
const content = `
            <div class="my-app-w-container">
                <h2 class="w-title" :style="{borderBottom: '1px solid red'}">
                    {{$Bitrix.Loc.getMessage('W_TITLE')}}
                </h2>
                
                <h3>Description: {{desc}}</h3>
                
                <div v-for="(value) in persons">
                    <p>
                        <span class="w-name">{{value.name}}</span>:
                        <span class="w-age">{{value.age}}</span>
                    </p>
                </div>
                
                <div v-if="persons == null">
                    {{$Bitrix.Loc.getMessage('W_EMPTY')}}
                </div>
                
                <h4>Just a number {{count}}</h4>
                
                <div class="w-buttons">
                    <button @click="fetch">Получить данные (без параметров)</button>
                    <button @click="fetch({param: 'a'})">Данные для параметра 'a'</button>
                    <button @click="fetch({param: 'b'})">Данные для параметра 'b'</button>
                    <button @click="openApplication({param1: '1', param2: 'false'})">Открыть приложение</button>
                    <button @click="openPath('/crm')">Открыть локальный адрес в слайдере</button>
                </div>
            </div>
        `;
        
        const data = {
            code: 'my_widget',
            fields: {
                NAME: 'My widget',
                PREVIEW: 'https://my-app.com/vibe_preview.jpg',
                CONTENT: content,
                SECTIONS: 'widgets_company_life',
                WIDGET_PARAMS: {
                    rootNode: '.my-app-w-container',
                    lang: {
                        ru: {
                            W_TITLE: 'Люди и их возраст',
                            W_EMPTY: 'Нет людей',
                        },
                        en: {
                            W_TITLE: 'People and their ages',
                            W_EMPTY: 'Empty',
                        },
                    },
                    handler: 'https://my-app.com/vibe.php',
                    style: 'https://my-app.com/vibe.css',
                    demoData: {
                        desc: 'Just a test widget',
                        count: 420,
                        persons: [
                            {'name': 'Person 1', 'age': 21},
                            {'name': 'Person 2', 'age': 42},
                            {'name': 'Person 3', 'age': 123},
                        ],
                    },
                },
            },
        };
        
        BX24.callMethod(
            'landing.repowidget.register',
            data,
            (result) =>
            {
                if (result.error())
                {
                    console.error(result.error());
        
                    return;
                }
        
                console.info(result.data());
            },
        );
        
require_once('crest.php');
        
        $content = <<<'HTML'
            <div class="my-app-w-container">
                <h2 class="w-title" :style="{borderBottom: '1px solid red'}">
                    {{$Bitrix.Loc.getMessage('W_TITLE')}}
                </h2>
                
                <h3>Description: {{desc}}</h3>
                
                <div v-for="(value) in persons">
                    <p>
                        <span class="w-name">{{value.name}}</span>: 
                        <span class="w-age">{{value.age}}</span>
                    </p>
                </div>
                
                <div v-if="persons == null">
                    {{$Bitrix.Loc.getMessage('W_EMPTY')}}
                </div>
                
                <h4>Just a number {{count}}</h4>
                
                <div class="w-buttons">
                    <button @click="fetch">Получить данные (без параметров)</button>
                    <button @click="fetch({param: 'a'})">Данные для параметра 'a'</button>
                    <button @click="fetch({param: 'b'})">Данные для параметра 'b'</button>
                    <button @click="openApplication({param1: '1', param2: 'false'})">Открыть приложение</button>
                    <button @click="openPath('/crm')">Открыть локальный адрес в слайдере</button>
                </div>
            </div>
        HTML;
        
        $data = [
            'code' => 'my_widget',
            'fields' => [
                'NAME' => 'My widget', 
                'PREVIEW' => 'https://my-app.com/vibe_preview.jpg', 
                'CONTENT' => $content,  // Vue-разметка вынесена в отдельную переменную для удобства
                'SECTIONS' => 'widgets_company_life', 
                'WIDGET_PARAMS' => [
                    'rootNode' => '.my-app-w-container',
                    'lang' => [
                        'ru' => [
                            'W_TITLE' => 'Люди и их возраст',
                            'W_EMPTY' => 'Нет людей',
                        ],
                        'en' => [
                            'W_TITLE' => 'People and their ages',
                            'W_EMPTY' => 'Empty!',
                        ],
                    ],
                    'handler' => 'https://my-app.com/vibe.php',
                    'style' => 'https://my-app.com/vibe.css',
                    'demoData' => [
                        'desc' => 'Just a test widget',
                        'count' => 420,
                        'persons' => [
                            [
                                'name' => 'Person 1',
                                'age' => 21,
                            ],
                            [
                                'name' => 'Person 2',
                                'age' => 42,
                            ],
                            [
                                'name' => 'Person 3',
                                'age' => 123,
                            ],
                        ],
                    ],
                ],
            ],
        ];
        
        $result = CRest::call(
            'landing.repowidget.register',
            $data
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

Обработка ответа

HTTP-статус: 200

{
            "result": 10,
            "time": {
                "start": 1713949410.036288,
                "finish": 1713949411.632775,
                "duration": 1.596487045288086,
                "processing": 0.6458539962768555,
                "date_start": "2024-04-24T11:03:30+02:00",
                "date_finish": "2024-04-24T11:03:31+02:00",
                "operating": 0
            }
        }

Возвращаемые данные

Название
тип

Описание

result
integer

Идентификатор добавленного виджета

time
time

Информация о времени выполнения запроса

Обработка ошибок

Статусы и коды системных ошибок

HTTP-статус: 20x, 40x, 50x

Описанные ниже ошибки могут возникнуть при вызове любого метода

Статус

Код
Текст ошибки

Описание

500

INTERNAL_SERVER_ERROR
Internal server error

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

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

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

503

QUERY_LIMIT_EXCEEDED
Too many requests

Превышен лимит на интенсивность запросов

405

ERROR_BATCH_METHOD_NOT_ALLOWED
Method is not allowed for batch usage

Текущий метод не разрешен для вызова с помощью batch

400

ERROR_BATCH_LENGTH_EXCEEDED
Max batch length exceeded

Превышена максимальная длина параметров, переданных в метод batch

401

NO_AUTH_FOUND
Wrong authorization data

Неверный access-токен или код вебхука

400

INVALID_REQUEST
Https required

Для вызовов методов требуется использовать протокол HTTPS

503

OVERLOAD_LIMIT
REST API is blocked due to overload

REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка, для снятия необходимо обращаться в техническую поддержку Битрикс24

403

ACCESS_DENIED
REST API is available only on commercial plans

REST API доступен только на коммерческих планах

403

INVALID_CREDENTIALS
Invalid request credentials

У пользователя, с чьим access-токеном или вебхуком был вызван метод, не хватает прав

404

ERROR_MANIFEST_IS_NOT_AVAILABLE
Manifest is not available

Манифест недоступен

403

insufficient_scope
The request requires higher privileges than provided by the webhook token

Запрос требует более высоких привилегий, чем предоставляет токен вебхука

401

expired_token
The access token provided has expired

Предоставленный access-токен доступа истек

403

user_access_error
The user does not have access to the application

Пользователь не имеет доступа к приложению. Это означает, что приложение установлено, но администратор портала разрешил доступ к этому приложению только конкретным пользователям

500

PORTAL_DELETED
Portal was deleted

Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

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

Предыдущая
Вайб и виджеты
Следующая
Удалить виджет