rososmotr / websdk
CI/CD
Реестр контейнеров и пакетов
iVanSh
Readme updated
4 месяца назад История
readme.md

Оглавление

Установка

Вариант 1 (показан в example.html):

npm install git+https://gitflic.ru/project/rososmotr/websdk.git

import { VaConstructor, App as VaApp } from 'rososmotr-web-sdk';

VaConstructor(VaApp);

Вариант 2 (показан в example2.html):

<script src="rososmotr-web-sdk.umd.js"></script>
<script>
   RososmotrWebSDK.VaConstructor(RososmotrWebSDK.App);
</script>

В обоих вариантах нужно также подключить стили:

<link rel="stylesheet" href="style.css">

и создать контейнер (id строго “VaApp”)

<div id="VaApp"></div>

Общий принцип использования на хост-странице

Основные договорённости и принципы решения:

  1. SDK кэширует данные в локальной БД. Получает данные от сервера, сохраняет, добавляет к ним то, что пользователь отредактировал или осмотрел.

  2. SDK выдаёт данные host-странице и строит свои экраны всегда по локальной БД. Даже при наличии интернета, запросы к серверу НЕ синхронные.

  3. Методы обращения к данным, доступные host-странице, всегда отдают наиболее свежие данные непосредственно, однако реализован механизм подписки на события изменения данных.

  4. Host-приложение должно проектироваться таким образом, чтобы обрабатывать изменения данных, на которые подписывается. Не единожды, а до тех пор, пока подписка не будет отменена. К примеру, метод eventBus.on('inspectionsList', listener) единожды вызванный, организует подписку и будет вызывать указанный listener каждый раз, когда данные будут меняться.

Инициализация и логин

const myApp = window.va_app_instance.VAWebSDK();

Возвращает объект WebSDK для последующего использования в host-приложении.

myApp.init({ token: 'someToken', userId: 123, serverUri: 'someURI', apikey: 'myKey' });
  • token – (string) токен открытой сессии текущего пользователя, например "904822.ffb34b6110abca4df25f63fd9ba333fc";
  • userId – (int) идентификатор текущего пользователя из БД viewapp, например 904822;
  • serverUri – (string) адрес сервера для обмена данными, который будет использоваться как префикc для всех запросов, например "https://web.rososmotr.ru". Адрес должен быть без завершающего слэша.
  • apikey – (string) ключ копии SDK, по которому определяется принадлежность к компании (должен быть выдан вам Рососмотром), например "sdk.cmp15";

Метод принимает токен, идентификатор авторизованного пользователя и вспомогательные параметры для связи с серверами. Идентификатор пользователя определяет локальную БД, поэтому важно, чтобы userId был задан корректно.

Получить токен и идентификатор пользователя необходимо через серверное взаимодействие методом /sdk/sdk_login.

Прервать сессию пользователя в дельнейшем можно методом /sdk/sdk_logout.

Для пробного запуска приложения без логина и без связи с сервером можно использовать

myApp.testInit({ token: 'someToken', userId: 123, serverUri: 'someURI', apikey: 'myKey' });

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

События и подписка на них

Для работы с подписками используется шина событий:

myApp.eventBus.on('eventName', listener); // добавление постоянной подписки
myApp.eventBus.once('eventName', listener); // добавление разовой подписки (использовать с осторожностью)
myApp.eventBus.off('eventName', listener); // удаление подписки

События и что они возвращают:

  • sending: true, если отправка данных началась, false если закончилась
  • receiving: true, если получение данных началось, false если закончилось
  • inspectionListChanged: возвращает массив осмотров. Срабатывает если массив изменился по данным от сервера, структура аналогична методу.
  • inspectionChanged: возвращает детальные данные осмотра. Срабатывает если осмотр изменился по данным от сервера, структура аналогична методу.
  • inspectionChangedByUser: возвращает детальные данные осмотра. Срабатывает если осмотр был изменён пользователем, структура аналогична методу.
  • userChanged: возвращает данные пользователя. Срабатывает если осмотр изменился по данным от сервера, структура аналогична методу.
  • routeChanged: возвращает внутреннее навание страницы, куда перешёл пользователь внутри WebSDK. Может быть полезно для взаимодействия с кнопками “назад”-“вперёд” как браузерными, так хост-страницы.
  • error: возвращает уровень возникшей ошибки (error или warning), её код и описание.

Методы получения данных

myApp.getUser(): возвращает пользователя текущей сессии

// UserModel
{
   "id": 17901,
   "lastName": "Иванов",
   "firstName": "Иван",
   "middleName": "Иванович",
   "phone": "+71234567890",
   "role": "agent",
   "language": "ru"
}

myApp.getInspectionList(): возвращает массив доступных осмотров. Если список пуст – возвращается пустой массив, если список по причине того, что данные с сервреа ещё не приехали, а локально ничего сохранённого нет – возвращает null.

// InspectionInListModel
{
   "id": 142369,
   "objectName": "Полное наименование объекта",
   "serviceName": "Наименование схемы осмотра",
   "image": "https://",
   "status": {
      "alias": "contract",
      "name": "Заявление принято",
      "message": "Проверка фотографий прошла успешно",
      "date": "2021-10-12 18:53:17"
   }
}

myApp.getInspection(inspectionId): возвращает данные осмотра для детального экрана

// InspectionDetailsModel
{
   "id": 142369,
   "objectName": "KASKO Lexus UX I",
   "serviceName": "Automobile loss settlement",
    
   "status": {
      "alias": "draft",
      "name": "The inspection is incomplete",
      "message": "You have not completed the inspection...",
      "date": "2021-03-23 21:37:42"
   },
   "statusList": [
      {
         "alias": "draft",
         "ord": 1,
         "short": "осмотр не завершён",
         "description": "Вы не завершили осмотр или...",
         "datetime": "2019-06-03 06:04:16",
         "isPassed": false,
         "isCurrent": true
      },
      {
         "alias": "expertise",
         "ord": 3,
         "short": "экспертиза",
         "description": "Сделанные вами фотографии переданы на проверку",
         "datetime": null,
         "isPassed": false,
         "isCurrent": false
      }
   ],
   
   "isChecklist": false,

   "stages": [ // InspectionStageModel
      {
         "type": "multiShooting",
         "key": "1903",
         "ord": 4,
         "icon": "https://",
         "title": "Equipment",
         "subTitle": "Repeat shooting",
         "state": "todo"
      },
      {
         "type": "repeatShooting",
         "key": "1902",
         "ord": 3,
         "icon": "https://",
         "title": "Tools",
         "subTitle": "Multi shooting",
         "state": "todo"
      }
   ],

   "allowedActions": [
      "sendToReview",
      "makeAgreement"
   ],

   "extraButtons": [
      {
         "isDoc": true,
         "icon": "https://web.rososmotr.ru/img/extra_buttons/pdf.png",
         "text": "Акт об осмотре",
         "subText": "PDF",
         "size": "0,73 Мб",
         "url": "https://web.rososmotr.ru/pdf/inspection_test_4222b902d.pdf",
         "ord": 1
      }
   ]
}

  • Статусы: поля status и statusList связаны между собой: status – текущий статус осмотра по данным из локальной БД; statusList – список статусов, через которые осмотр проходил или будет проходить — помогает добавить наглядности для пользователя.

    • statusList.isPassed – (bool) флаг: считается ли данный статус пройденным для текущего осмотра;
    • statusList.isCurrent – (bool) флаг: является ли данный статус текущим статусом осмотра.

    Один и тот же статус может многократно повторяться в осмотре, так как предусмотрен возврат на доработку и повторная экспертиза (можно много раз).

  • extraButtons – массив дополнительных материалов или действий — в него, в том числе, выдаётся ссылка на документ до и после подписания (файл НЕ кэшируется SDK и должен быть загружен host-приложением, при необходимости).

  • InspectionStageModel - поле с изображением icon в текущей версии SDK выдаёт ссылку на файл в интернете, либо пустую строку, когда изображения нет (кэшировать картинку в текущий момент host-приложению необходимо самостоятельно);

  • state – состояние готовности этапа, может иметь один из вариантов заполнения:

    • "todo" – этап ещё не заполнялся, пользователь начнёт делать его впервые;
    • "alarm" – пользователь начинал выполнять этап, но не завершил; или эксперты вернули этап на доработку;
    • "done" – минимально необходимые, но достаточные операции по этапу выполнены.

Синхронизация

myApp.forceSync(); : заставляет WebSDK попробовать синхронизироваться с сервером прямо сейчас.

myApp.getReceivingStatus(); : возращает объект с информацией о том, ожидается ли получение (или идёт сейчас) каких-либо данных с сервера.

// возможно будет расширен
{
    haveDataToReceive: false,
    receivingNow: false
}

myApp.getSendingStatus(); : возращает объект с информацией о том, ожидается ли отправка (или идёт сейчас) каких-либо данных на сервер.

// возможно будет расширен
{
    haveDataToSend: false,
    sendingNow: false
}

Навигация

myApp.setRoute(route, force);: заставляет WebSDK осуществить переход к указанной странице. Если параметр force равен true, то WebSDK перейдёт на страницу даже тогда, когда уходить с текущей страницы нельзя или не предусмотрен прямой штатный переход к странице route.

Отправка отладочной информации

Для решения внештатных ситуаций, пользователю необходимо предоставить возможность отправлять запросы в техническую поддержку. Необходимо, чтобы была проинициализирована сессия пользователя.

myApp.sendSupportRequest(textMessage, additionalObject)

Метод может вызвать любой вид ошибок, включая сетевые!

Метод синхронно отправит сообщение в техническую поддержку, и добавит к обращению файлы локальной БД. Это даст возможность внимательно изучить, с чем столкнулся пользователь, и помочь ему.

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

Завершение работы

myApp.close();: завершает работу объекта WebSDK, для повторной работы необходимо начинать с

const myApp = window.va_app_instance.VAWebSDK();
Описание

РОСОСМОТР // SDK для WEB

JavaScript
Readme
0 Форки
1 Звезд
0 Наблюдатели
Конвейеры
0 успешных
0 с ошибкой