Перейти к содержанию

WidgetSDK

Концепция виджетов

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

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

  • адаптивностью вёрстки в широких пределах (обязательно);
  • UX/UI (необязательно: использование библиотеки VK People Hub UI);
  • способом организации бизнес-логики для реализации сквозных пользовательских сценариев (необязательно: использование WidgetSDK).

Функциональные возможности виджетов

  • Виджеты функционируют независимо от фреймворка разработки.
  • Виджеты могут быть (не обязательно) написаны с использованием JS/TS библиотеки WidgetSDK.
  • Виджеты реализуются в виде iframe – iframe-style.
  • Виджеты обладают возможностью процессной коммуникации (event bus) с front-end VK People Hub посредством WidgetSDK.
  • Виджеты доступны для размещения в рамках лейаут-менеджера на главной странице. В дальнейшем виджеты можно будет размещать на главной странице и на страницах сервиса «Конструктор сайтов».

О технологии WidgetSDK

WidgetSDK – JS-инструментарий для взаимодействия с front-end VK People Hub. Технология WidgetSDK опубликована впервые в рамках мажорного квартального релиза за 2 квартал 2024 года в MVP-версии, дальнейшее развитие и дополнение технологии планируется в 2024-2025 годах.

WidgetSDK представляет собой клиентскую библиотеку (работает на стороне виджета).

Каждый виджет состоит из двух обязательных элементов, которые загружаются на этапе создания виджета в отдельную административную панель, предназначенную для администрирования виджетов:

  • инсталляция веб-приложения, функционирующего, как виджет (URL);
  • файл-манифест (manifest.json).

WidgetSDK распространяется через публичный продуктовый NPM-репозиторий (пакет включает в себя TypeScript typings .d.ts и общую техническую документацию).

Возможности аутентификации

Платформа VK People Hub выделяет для экземпляра виджета уникальный подписанный токен доступа (widget-access-token) в формате JWT. Разработчик виджета может использовать этот токен для идентификации и аутентификации субъекта доступа (собственно данного экземпляра виджета и пользователя), если это требуется в рамках бизнес-логики собственной предметной области виджета.

Описание: Характеризует конкретный экземпляр виджета, используемый конкретным пользователем.

Способ получения:

WidgetSDK.getAuthToken()

Гарантии обратной совместимости WidgetSDK

  • Поддержка устаревшей версии WidgetSDK в течение двух квартальных релизов.
  • Презентация новых версий WidgetSDK осуществляется на ежеквартальных демо продукта VK People Hub.
  • Внесение в документацию сроков вывода устаревших версий WidgetSDK.

Использование библиотеки WidgetSDK

Установка

Предварительная настройка доступов

  • Добавьте в настройки дополнительный NPM реестр.
npm config set @vkph:registry https://npm.people-hub.ru/repository/npm/
  • Запросите токен на основе логина и пароля, которые должны быть получены от представителей VK People Hub.
    Где user и pass ваши логин и пароль.
echo -n "user:pass" | openssl base64
  • Добавьте полученный токен авторизации в конфигурацию NPM.
    Где token это значение токена полученное из предыдущей команды.
npm config set //npm.people-hub.ru:_auth="token"

Установка библиотеки

Для установки выполните команду:

npm install @vkph/widget-sdk

Или установите указав конкретную версию, где 0.1.0 это номер версии:

npm install @vkph/widget-sdk@0.1.0

Подключение

Подключение происходит при инициализации функций подписки на события обмена сообщениями:

import { VKPHWidgetSDK } from 'widget-sdk';

const widgetSDK = new VKPHWidgetSDK();

widgetSDK.init();

Авторизация

Авторизация происходит автоматически в фоновом режиме. При запросе используется токен авторизации текущего пользователя портала VH People Hub и персональный токен виджета, который получается на основе токена пользователя и uuid виджета.

Если выполнить запрос из экземпляра класса VKPHWidgetSDK, к примеру, данных пользователей, то достаточно вызвать функцию getCurrentUser. Производить явный процесс авторизации не потребуется.

API

На низком уровне взаимодействие WidgetSDK и VK People Hub организовано с использованием pubsub-like подсистемы.
WidgetSDK предоставляет низкоуровневый интерфейс работы с pubsub, а также верхнеуровневый интерфейс вызова конечных API, несущих бизнес-ценность.
Использование низкоуровневого интерфейса необязательно для решения типовых задач.

Взаимодействие через функции

Пример использования:

const widgetSDK = new VKPHWidgetSDK();

// Запрос асинхронных данных
const getWidgetToken = async () => {
  try {
    const auth = await widgetSDK.getAuthToken();
    return auth;
  } catch (error) {
    console.error('Ошибка при получении токена:', error);
    throw error;
  }
};

// Запрос синхронных данных
const getWidgetUuid = () => {
  try {
    const auth = widgetSDK.getUuid();
    return auth;
  } catch (error) {
    console.error('Ошибка при получении UUID:', error);
    throw error;
  }
};
Имя Асинхронность Описание
getAuthToken Да Возвращает авторизационные данные для виджета
getColorScheme Да Возвращает объект с информацией о цветах текущей темы VK People Hub
getCurrentUser Да Возвращает информацию о текущем пользователе
getUuid Нет Возвращает uuid данного экземпляра виджета

Взаимодействие по средствам подписок

Пример использования:

const printTokenData = (response) => console.log(response);
widgetSDK.on('authToken', printTokenData);
Имя Описание
authToken Событие на авторизационные данные для виджета
colorScheme Событие на объект с информацией о цветах текущей темы VK People Hub
currentUser Событие на информацию о текущем пользователе

Сервис Widgets

Административная панель сервиса Widgets

Административная панель размещается по адресу https://<ваш домен>/api/widgets/admin/login

Логин и пароль пользователя - администратора Widgets задается переменными окружения DJANGO_SUPERUSER_PASSWORD, DJANGO_SUPERUSER_USERNAME сервиса WIDGETS.

Административная панель содержит следующие вкладки:

  • AdminPanelUsers,
  • Users,
  • Widgets,
  • Widget Instances (раздел находится на доработке).

AdminPanelUsers

В разделе AdminPanelUsers содержится информация об учетной записи администратора Widgets. Через раздел можно просмотреть логин и пароль администратора Widgets, а также выгрузить в формате .csv.

Не рекомендуется изменять и удалять администратора через данный раздел.

Users

В разделе Users содержится информация о всех пользователях портала, которая загружается из Keycloak. Добавление новых пользователей, редактирование или удаление существующих пользователей через административную панель Widgets невозможно. Доступна выгрузка пользователей в формате .csv.

Users

Рисунок. Раздел Users административной панели Widgets

Widgets

В разделе Widgets содержится информация о тех виджетах, которые созданы на портале.

Widget

Рисунок. Раздел Widgets административной панели Widgets

Структура манифеста

Манифест является json объектом и загружается в панели администратора, имеет следующую структуру:

{
  /** Компания-производитель виджета */
  manufacturer: string;
  /** Контакт разработчика */
  authorName: string;
  /** Контакт разработчика */
  authorEmail: string;
  /** Лицензия на распространение/использование */
  license: string;
  /** Имя виджета */
  name: string;
  /** Описание виджета */
  description: string;
  /** Версия виджета в формате semver 2.0 */
  version: string;
  /** Совместимая версия VKPH */
  compatibleVersionVKPeopleHub: string;
};

Получить шаблон манифеста в виде файла можно по ссылке.

Структура настроек виджета

Структура настроек виджета заполняется строкой:

{"data": {}, "name": "widget-2", "path": "", "types": ["column"], "description": "Widget 2", "is_external": true, "default_data": {}, "file_storage_image": null}
Доступные параметры для изменения:

  • "name": "<можно указать название виджета, которое будет отображаться при перемещении виджета на главную страницу>"
  • "types": ["<можно указать значения: header, navbar, breadcrumb, central, content, column, footer>"]
  • "description": "<можно указать описание виджета, которое будет отображаться в горизонтальной панели виджетов перед перемещением его на главную страницу>"

Остальные параметры необходимо оставлять неизменными.

Пример отображения виджетов при заполненной строке:

{"data": {}, "name": "widget-2", "path": "", "types": ["column"], "description": "Widget 2", "is_external": true, "default_data": {}, "file_storage_image": null}

Widget2.png

Рисунок. Параметры description, widgetId и types в окне выбора доступных виджетов для размещения на главной странице

widget-2

Рисунок. Параметры name и types на добавленном на главную страницу виджете

Widget Instances

Раздел находится на доработке.