@sberdevices/assistant-client - npm Package Compare versions

Comparing version 1.1.0-canary.28.0039888976b7c4d0699434907891c4e88b639e7e.0 to 1.1.0-canary.28.13b9cb7b0ded987d2540334b42c530f888514d74.0

dist/index.js

@@ -29,4 +29,5 @@ import { createNanoEvents } from './nanoevents';
             if ((_a = window.AssistantHost) === null || _a === void 0 ? void 0 : _a.sendDataContainer) {
+                (_b = window.AssistantHost) === null || _b === void 0 ? void 0 : _b.sendDataContainer(
                 /* eslint-disable-next-line @typescript-eslint/camelcase */
-                (_b = window.AssistantHost) === null || _b === void 0 ? void 0 : _b.sendDataContainer(JSON.stringify({ data: action, message_name: name || null, requestId }));
+                JSON.stringify({ data: action, message_name: name || null, requestId }));
             }
@@ -33,0 +34,0 @@ else {

package.json

 {
     "name": "@sberdevices/assistant-client",
-    "version": "1.1.0-canary.28.0039888976b7c4d0699434907891c4e88b639e7e.0",
+    "version": "1.1.0-canary.28.13b9cb7b0ded987d2540334b42c530f888514d74.0",
     "description": "Модуль взаимодействия с виртуальным ассистентом",
@@ -26,3 +26,3 @@ "main": "dist/index.js",
     ],
-    "author": "SberDevices Frontend Team",
+    "author": "SberDevices Frontend Team <[e-mail]>",
     "license": "Sber Public License at-nc-sa v.2",
@@ -29,0 +29,0 @@ "dependencies": {

README.md

 <img src="https://user-images.githubusercontent.com/982072/97004635-0888a900-1546-11eb-8f25-283a0693608e.png" height="150px" width="150px">
 
 
-# SberDevices Assistant Client
+Assistant Client - это инструмент для локального тестирования и отладки [Сanvas App](https://smartapp-code.sberdevices.ru/documentation/#/docs/ru/methodology/research/canvasapp) c виртуальным ассистентом. Он реализован в виде JavaScript протокола, который эмулирует среду Android и вызывает нативные методы. Такой подход не требует от разработчика наличия физических устройств и позволяет запустить виртуального ассистента через браузер. 
 
-Assistant Client - это инструмент для тестирования и отладки СanvasApps c Виртуальным Ассистентом (ВА).
 
-Assistant Client интегрирует в WebView JS-код, который предоставляет биндинги к нативным методам на устройствах. В режиме локальной отладки и разработки Assistant Client эмулирует нативные методы, что позволяет запускать ВА в браузере.
+## Оглавление
+   * [Конфигурация](#Конфигурация)
+     * [Аутентификация](#Аутентификация)
+     * [Установка](#Установка)
+     * [Использование](#Пример)
+   * [API](#API)
+     * [createAssistant](#createAssistant)
+     * [createSmartappDebugger](#createSmartappDebugger)
+     * [getInitialData](#getInitialData) 
+     * [getRecoveryState](#getRecoveryState)
+   * [Форматы объектов](#Форматы)
+     * [AssistantAppState](#AssistantAppState)
+     * [AssistantServerAction](#AssistantServerAction)
+     * [AssistantCharacterCommand](#AssistantCharacterCommand)
+     * [AssistantNavigationCommand](#AssistantNavigationCommand)
+     * [AssistantSmartAppCommand](#AssistantSmartAppCommand)     
+   * [Требования](#Требования)
 
-Установка:
+____
 
+## Конфигурация
+
+### Аутентификация
+
+Для работы с Assistant Client необходимо:
+
+1. Завести аккаунт в [SmartApp Studio](https://smartapp-studio.sberdevices.ru/).
+2. Создать приложение с типом [Сanvas App](https://smartapp-code.sberdevices.ru/documentation/#/docs/ru/methodology/research/canvasapp). 
+3. Получить токен в Кабинете разработчика и передать его в запросе.  
+
+Для получения токена необходимо авторизоваться в [SmartApp Studio](https://smartapp-studio.sberdevices.ru/login) и в рамках Кабинета разработчика перейти в *Настройки профиля* > пункт *Auth Token* > опция *Скопировать ключ*. Полученный токен необходимо передавать в методе `createSmartappDebugger` в параметре `token`.  
+
+
+### Установка
+
+Для установки Assistant Client выполните следующую команду:
+
 ```sh
@@ -16,5 +48,7 @@ $ npm i @sberdevices/assistant-client
 
-## Quickstart
 
+### Пример использования
+
 ```typescript
+// Функция createSmartappDebugger используется в development среде. В production среде необходимо использовать createAssistant.
 import { createAssistant, createSmartappDebugger } from '@sberdevices/assistant-client';
@@ -25,10 +59,15 @@
         return createSmartappDebugger({
-            token: 'токен разработчика из Smartapp Studio', // Токен,
-            initPhrase: 'Хочу попкорн', // фраза для запуска аппа
-            getState,
-            getRecoveryState,
+            // Токен из Кабинета разработчика
+            token: 'token', 
+            // Пример фразы для запуска приложения
+            initPhrase: 'Хочу попкорн', 
+            // Функция, которая возвращает текущее состояние приложения
+            getState, 
+            // Функция, возвращающая состояние приложения, с которым приложение будет восстановлено при следующем запуске
+            getRecoveryState, 
         });
     }
 
-    return createAssistant({ getState, getRecoveryState });
+	  // Только для среды production
+    return createAssistant({ getState, getRecoveryState }); 
 }
@@ -40,3 +79,4 @@
 assistant.on('data', (command) => {
-    // подписка на команды ассистента, в т.ч. команда инициализации смартапа
+    // Подписка на команды ассистента, в т.ч. команда инициализации смартапа. 
+    // Ниже представлен пример обработки голосовых команд "ниже"/"выше" 
     if (command.navigation) {
@@ -55,3 +95,4 @@ switch(command.navigation.command) {
 const handleOnClick = () => {
-    // отправка ServerAction
+    // Отправка сообщения ассистенту с фронтенд. 
+    // Структура может меняться на усмотрение разработчика, в зависимости от бэкенд
     assistant.sendData({ action: { action_id: 'some_action_name' } });
@@ -61,2 +102,5 @@ };
 
+____
+
+
 ## API
@@ -66,64 +110,72 @@
 
-Создает экземпляр [`AssistantClient`](#AssistantClient), обязательный параметр `getState` - функция, которая возвращает актуальное состояние смартапа при каждом обращении к бэкенду. Используется в production среде на девайсах.
+Создает экземпляр [`AssistantClient`](#AssistantClient) для запуска виртуального ассистента. Используется на устройствах в production среде.
 
-### `createSmartappDebugger`
+| Параметр         | Обязательный | Описание                                                                   |
+| :--------------- | :------: | :------------------------------------------------------------------------- |
+| getState         | Да           |  Функция, которая возвращает актуальное состояние смартапа                 |
+| getRecoveryState | Нет          |  Функция, которая сохраняет состояние смартапа на момент последнего закрытия |
 
-Создает экземпляр [`AssistantClient`](#AssistantClient), добавляет на экран браузера панель с голосовым ассистентом, подобно устройствам. Панель позволяет вводить команды с клавиатуры и голосом. Также активируется озвучка ассистента. Используется в development среде для локальной отладки и разработки.
 
-| Параметр         | Dev only | Описание                                                                   |
-| :--------------- | :------: | :------------------------------------------------------------------------- |
-| getState\*       |    []    | Функция, которая возвращает актуальное состояние смартапа.                 |
-| token\*          |   [x]    | Токен.                                                                     |
-| initPhrase\*     |   [x]    | Фраза, которая запускает ваше приложение.                                  |
-| getRecoveryState |    []    | Функция, которая возвращает состояние смартаппа перед последним закрытием. |
 
-#### Панель ассистента
+### `createSmartappDebugger`
 
-<a name="AssistantPanel"></a>
+Создает экземпляр [`AssistantClient`](#AssistantClient) и добавляет на экран браузера панель с голосовым ассистентом (подобно устройствам). Панель ассистента находится в нижней части отрисованного экрана и позволяет отправлять виртуальному ассистенту следующие типы сообщений:
+* текстовые сообщения через текстовое поле ввода; 
+* голосовые сообщения через кнопку "Салют". 
 
-По-умолчанию, в режиме разработки, панель отрисовывается. Вы можете посылать ВА сообщения, используя текстовое поле ввода в нижней панели. Чтобы отправить голосовое сообщение, нажмите на иконку салюта.
+`createSmartappDebugger` используется для локальной отладки и разработки в development среде (Dev).
 
-### AssistantClient
+| Параметр         | Обязательный | Описание                                                                   |
+| :--------------- | :------: | :------------------------------------------------------------------------- |
+| token            | Да           |  Токен из Кабинета Разработчика                                             |
+| initPhrase       | Да           |  Фраза, которая запускает приложение                                |
+| getState         | Да           |  Функция, которая возвращает актуальное состояние смартапа                 |
+| getRecoveryState | Нет          |  Функция, которая сохраняет состояние смартапа на момент последнего закрытия |
 
-<a name="AssistantClient"></a>
 
-#### getInitialData(): [AssistantCommands](#AssistantCommands)[]
 
+### getInitialData(): [AssistantCommands](#AssistantCommands)[]
+
 Возвращает данные, полученные при инициализации смартапа.
 
+
 ### getRecoveryState(): any
 
-Возвращает данные, сохраненные при последнем закрытии аппа на устройстве. Данные сохраняются при помощи вызова getRecoveryState, в момент закрытия аппа.
+Возвращает состояние, сохраненное при закрытии приложения. Устройство запоминает последнее состояние, которое возвращает функция getRecoveryState при инициализации Assistant Client.
 
 #### on('start', cb: () => void): void
 
-Подписка на событие готовности ассистента к работе.
+Осуществляет подписку на событие готовности ассистента к работе.
 
 #### on('data', cb: (data: [AssistantCharacterCommand](#AssistantCharacterCommand) | [AssistantNavigationCommand](#AssistantNavigationCommand) | [AssistantSmartAppCommand](#AssistantSmartAppCommand)) => {}): void
 
-Подписка на событие получения данных от бэкенда.
+Осуществляет подписку на событие получения данных с бэкенд.
 
 #### sendData({ action: [AssistantServerAction](#AssistantServerAction) }): void
 
-Отправляет сервер-экшен, который будет передан бэкенду.
+Отправляет события с фронтенд на бэкенд через ассистента.
 
 #### setGetState(nextGetState: () => [AssistantAppState](#AssistantAppState)): void
 
-Подменяет колбек, возвращаюший актуальное состояние приложения.
+Подменяет callback, который возвращает актуальное состояние приложения.
 
 #### setGetRecoveryState(nextGetRecoveryState: () => any)
 
-Подменяет колбек, возвращающий объект, который будет доступен при следующем запуске приложения. Данные можно получить при вызове getRecoveryState.
+Подменяет callback, который возвращает объект, доступный только при следующем запуске приложения. Данные приходят при вызове getRecoveryState.
 
-#### Формат объекта `AssistantAppState`
 
-<a name="AssistantAppState"></a>
+____
 
-Объект `AssistantAppState` — текущее состояние смартапа, которое не хранится в платформе или сценарии. То, что происходит на экране у пользователя и как пользователь может взамодействовать с смартапа в конкретный момент времени - ответственность смартапа. Assistant Client, в данном случае, некий буфер, который хранит состояние и предоставляет его платформе и сценарию смартапа.
 
-Каждый раз, когда пользователь начинает говорить, Assistant Client вызывает коллбек getState, чтобы получить и передать бэкенду состояние экрана пользователя.
+## Форматы объектов 
 
+### `AssistantAppState`
+
+Объект `AssistantAppState` — текущее состояние смартапа, которое не хранится в платформе или сценарии. Каждый раз, когда пользователь начинает говорить, Assistant Client вызывает getState, чтобы получить и передать в бэкенд состояние экрана пользователя. 
+То, что происходит на экране у пользователя и как он взаимодействует со смартапом в конкретный момент времени - ответственность смартапа. Assistant Client в данном случае - это буфер, который только передает состояние платформе или сценарию.
+
+
 ```typescript
 interface AssistantAppState {
-  /* Любые данные, которые могут потребоваться Backend'у для принятия решений */
+  // Любые данные, которые могут потребоваться в бэкенд для принятия решений
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -133,3 +185,3 @@ [key: string]: any;
     ignored_words?: string[];
-    /* Список соответствий голосовых команд действиям в веб-приложении */
+    // Список соответствий между голосовыми командами и действиями в приложении
     items: AssistantViewItem[];
@@ -140,15 +192,15 @@ };
 interface AssistantViewItem {
-  /* Порядковый номер элемента, назначается смартапом, уникален в рамках items */
+  // Уникальный (в рамках items) порядковый номер элемента, который назначается смартапом 
   number?: number;
-  /* Уникальный id элемента */
+  // Уникальный id элемента
   id?: string;
-  /* Ключевая фраза, которая должна приводить к данному действию */
+  // Ключевая фраза, которая должна приводить к данному действию
   title?: string;
-  /* Фразы-синонимы, которые должны быть расценены как данное действие */
+  // Фразы-синонимы, которые должны приводить к данному действию
   aliases?: string[];
-  /* Сервер экшен, проксирует action обратно на бекэнд. */
+  // Проксирование action обратно на бэкенд
   server_action?: AssistantServerAction;
-  /* Экшен, выполяет действие от имени пользователя */
+  // Выполнение действия от имени пользователя
   action?: AssistantAction | { type: string };
-  /* Дополнительные данные для бэкенда */
+  // Дополнительные данные для бэкенд
   [key: string]: any;
@@ -158,3 +210,3 @@ }
 
-Например, когда пользователь говорит "Покажи 1", бэкенду нужно понимать что скрывается за единицей (какой элемент у пользователя пронумерован единицей). Ниже пример стейта, который позволяет понять бэкенду, что пользователь хочет чипсы.
+Например, когда пользователь говорит "Покажи 1", бэкенд должен понимать, что скрывается за единицей (то есть, какой элемент у пользователя пронумерован этой цифрой). Ниже пример состояния, который позволяет понять бэкенду, что, называя "1", пользователь хочет чипсы.
 
@@ -166,3 +218,2 @@ ```js
     items: [
-      { title: 'Кола' },
       { title: 'Сладкий попкорн' },
@@ -172,3 +223,3 @@ { title: 'Соленый попкорн' },
       { title: 'Начос', number: 2 },
-      { title: 'Пиво', number: 3 }
+      { title: 'Кола', number: 3 }
     ]
@@ -179,13 +230,11 @@ }
 
-#### Формат объекта `AssistantServerAction`
+### `AssistantServerAction`
 
-<a name="AssistantServerAction"></a>
+Объект `AssistantServerAction` - это любое сообщение, которое отправляется с фронтенда на бэкенд. Оно может быть привязано к ui-элементу и приходить с бэкенд, или формироваться самостоятельно фронтовой частью приложения при обработке событий внутри WebView смартапа.
 
-`AssistantServerAction` - это любое сообщение, отправляемое от клиентской части приложения в бэкенд. Оно может быть как привязано к ui-элементу и приходить с бэка (в основном, для message-based аппов), так и формироваться самостоятельно фронтовой частью аппа при обработке событий внутри веб-вью аппа..
-
 ```typescript
 interface AssistantServerAction {
-  /* Тип сервер-экшена */
+  // Тип Server Action
   action_id: string;
-  /* любые параметры */
+  // Любые параметры
   parameters?: Record<string, any>;
@@ -195,8 +244,6 @@ }
 
-#### Формат объекта `AssistantCharacterCommand`
+### `AssistantCharacterCommand`
 
-<a name="AssistantCharacterCommand"></a>
+Объект `AssistantCharacterCommand` - информирует смартап о текущем персонаже (Сбер, Афина или Джой). Персонаж может быть изменен в любой момент по инициативе пользователя. Поэтому разработчик может дополнительно добавить обработку таких изменений. 
 
-`AssistantCharacterCommand` - информирует смартап о текущем ассистенте.
-
 ```typescript
@@ -214,13 +261,11 @@ interface AssistantCharacterCommand {
 
-#### Формат объекта `AssistantNavigationCommand`
+### `AssistantNavigationCommand`
 
-<a name="AssistantNavigationCommand"></a>
+Объект `AssistantNavigationCommand` - команда навигации пользователя по смартапу (например, "вперед, назад, дальше" и т.д.). В платформе виртуального ассистента есть стандартные фразы, которые приходят и обрабатываются одинаково для всех смартапов.
 
-`AssistantNavigationCommand` - команда навигации пользователя по смартапу. Большая часть навигационных команд может быть выполнена стандартным средствами Assistant Client. В платформе виртуального ассистента есть стандартные фразы, которые обрабатываются единым образом. Они обрабатываются и приходят одинаково для всех смартапов.
-
 ```typescript
 interface AssistantNavigationCommand {
-  /* Тип команды */
+  // Тип команды
   type: "navigation";
-  /* Навигационная команда (направление навигации) */
+  // Навигационная команда (направление навигации)
   navigation: { command: "UP" | "DOWN" | "LEFT" | "RIGHT" | "FORWARD" | "BACK" };
@@ -233,13 +278,11 @@ sdkMeta: {
 
-#### Формат объекта `AssistantSmartAppCommand`
+### `AssistantSmartAppCommand`
 
-<a name="AssistantSmartAppCommand"></a>
+Объект `AssistantSmartAppCommand` - это команда передачи смартапу любых данных с бэкенд.
 
-`AssistantSmartAppCommand` - это команда для передачи смартапу любых данных с бэкенда.
-
 ```typescript
 interface AssistantSmartAppCommand {
-  /* Тип команды */
+  // Тип команды 
   type: "smart_app_data";
-  /* Любые данные, которые нужны смартапу */
+  // Любые данные, которые нужны смартапу
   smart_app_data: Record<string, any>;
@@ -252,8 +295,7 @@ sdkMeta: {
 
-## Разрешения устройств
+____
 
-Смартапы должны корректно отображаться на разных устройствах (SberBox, SberPortal и др). Для этого, необходимо проверять смартап на следующих разрешениях: 559x568, 768x400, 959x400, 1920x1080. Рекомендуется настроить эти разрешения на [вкладке Devices Chrome](https://developers.google.com/web/tools/chrome-devtools/device-mode#custom).
 
-## FAQ
-### Как получить токен?
-Заведите аккаунт в [SmartApp Studio](https://smartapp-studio.sberdevices.ru/) и создайте приложение типа CanvasApp. Токен доступен во вкладке «Настройка профиля» в секции «Auth Token».
+## Требования к устройствам
+
+Смартапы должны корректно отображаться на разных устройствах (SberBox, SberPortal и др). Для этого необходимо проверять смартап на следующих разрешениях: 559x568, 768x400, 959x400, 1920x1080. Настроить эти разрешения можно на [вкладке Devices Chrome](https://developers.google.com/web/tools/chrome-devtools/device-mode#custom).

No alert changes

Improved metrics

Total package byte prevSize

628699

increased by0.46%

Lines of code

10994

increased by0.01%

Number of lines in readme file

286

increased by17.21%

No dependency changes