@sberdevices/assistant-client

v5.0.2

Published

2 years ago

Модуль взаимодействия с виртуальным ассистентом

Downloads

1,178

0High
0Medium
0Low

turanchoks

sberdevices-frontend

sber assistant smartapp

Assistant Client — это инструмент для локального тестирования и отладки Сanvas App c виртуальным ассистентом. Он реализован в виде JavaScript протокола, который эмулирует среду Android и вызывает нативные методы. Такой подход не требует от разработчика наличия физических устройств и позволяет запустить виртуального ассистента через браузер.

Пример: Todo смартап, который демонстрирует взаимодействие с Assistant Client.

Конфигурация

Аутентификация

Для работы с Assistant Client необходимо:

Завести аккаунт в SmartApp Studio.
Создать смартап типа Сanvas App.
Получить токен. Для этого необходимо перейти в Настройки профиля > пункт Auth Token > опция Скопировать ключ.
Передать полученный токен в методе createSmartappDebugger в параметре token.

Требования к устройствам

Смартапы должны корректно отображаться на разных устройствах (SberBox, SberPortal и др). Для этого необходимо проверять смартап на следующих разрешениях: 559x568, 768x400, 959x400, 1920x1080. Настроить эти разрешения можно на вкладке Devices Chrome.

Установка

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

$ npm i @sberdevices/assistant-client

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

// Функция createSmartappDebugger используется в development среде. В production среде необходимо использовать createAssistant.
import { createAssistant, createSmartappDebugger } from '@sberdevices/assistant-client';

const initialize = (getState, getRecoveryState) => {
    if (process.env.NODE_ENV === 'development') {
        return createSmartappDebugger({
            // Токен из Кабинета разработчика
            token: 'token',
            // Пример фразы для запуска смартапа
            initPhrase: 'Хочу попкорн',
            // Текущее состояние смартапа
            getState,
            // Состояние смартапа, с которым он будет восстановлен при следующем запуске
            getRecoveryState,
            // Необязательные параметры панели, имитирующей панель на реальном устройстве
            nativePanel: {
                // Стартовый текст в поле ввода пользовательского запроса
                defaultText: 'Покажи что-нибудь',
                // Позволяет включить вид панели, максимально приближенный к панели на реальном устройстве
                screenshotMode: false,
                // Атрибут `tabindex` поля ввода пользовательского запроса
                tabIndex: -1,
            },
        });
    }

	  // Только для среды production
    return createAssistant({ getState, getRecoveryState });
}

...

const assistant = initialize(() => state, () => recoveryState);
assistant.on('data', (command) => {
    // Подписка на команды ассистента, в т.ч. команда инициализации смартапа.
    // Ниже представлен пример обработки голосовых команд "ниже"/"выше"
    if (command.navigation) {
        switch(command.navigation.command) {
            case 'UP':
                window.scrollTo(0, 0);
                break;
            case 'DOWN':
                window.scrollTo(0, 1000);
                break;
        }
    }
});

const handleOnClick = () => {
    // Отправка сообщения ассистенту с фронтенд.
    // Структура может меняться на усмотрение разработчика, в зависимости от бэкенд
    assistant.sendData({ action: { type: 'some_action_name', payload: { param: 'some' } } });
};

const handleOnRefreshClick = () => {
    // Отправка сообщения бэкенду с возможностью подписки на ответ.
    // В обработчик assistant.on('data') сообщение не передается
    const unsubscribe = assistant.sendAction(
        { type: 'some_action_name', payload: { param: 'some' } },
        (data: { type: string; payload: Record<string, unknown> }) => {
            // Обработка данных, переданных от бэкенд
            unsubscribe();
        },
        (error: { code: number; description: string }) => {
            // Обработка ошибки, переданной от бэкенд
        });
}

Альтернативное подключение

Assitant Client доступен для подключения через <script>. Версию assistant сlient можно поменять в src. Доступ к API осуществляется через глобальную переменную assistant.

Пример, для разработки и отладки в браузере (в этом случае обязательно подключение react):

<script crossorigin src="https://unpkg.com/react@17/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@17/umd/react-dom.production.min.js"></script>
<script src="https://unpkg.com/@sberdevices/[email protected]/umd/assistant.development.min.js"></script>
<script>
  const client = assistant.createSmartappDebugger({
            // Токен из Кабинета разработчика
            token: 'token',
            // Пример фразы для запуска смартапа
            initPhrase: 'Хочу попкорн',
            // Текущее состояние смартапа
            getState: () => ({}),
            // Состояние смартапа, с которым он будет восстановлен при следующем запуске
            getRecoveryState: () => ({}),
        });
</script>

Пример, для использования на устройствах:

<script src="https://unpkg.com/@sberdevices/[email protected]/umd/assistant.production.min.js"></script>
<script>
  const client = assistant.createAssistant({ getState: () => ({}), getRecoveryState: () => ({}), });
</script>

API

`createAssistant`

Создает экземпляр AssistantClient для запуска виртуального ассистента. Используется на устройствах в production среде.

| Параметр | Обязательный | Описание | | :--------------- | :------: | :------------------------------------------------------------------------- | | getState | Да | Функция, которая возвращает актуальное состояние смартапа | | getRecoveryState | Нет | Функция, которая сохраняет состояние смартапа на момент последнего закрытия |

`createSmartappDebugger`

Создает экземпляр AssistantClient и добавляет на экран браузера панель с голосовым ассистентом (подобно устройствам). Панель ассистента находится в нижней части отрисованного экрана и позволяет отправлять виртуальному ассистенту следующие типы сообщений:

текстовые сообщения через текстовое поле ввода;
голосовые сообщения через кнопку «Салют».

createSmartappDebugger используется для локальной отладки и разработки в development среде.

Свойства Settings

Свойства `nativePanel`

Все свойства являются необязательными.

AssistantClient

cancelTts(): void

Опциональный метод. Вызывается со стороны смартапа для остановки озвучивания ответа (pronounceText). Имеет значение undefined, если устройство не поддерживает данную функцию.

close(): void

Вызывается со стороны смартапа для завершения работы.

getInitialData(): AssistantCommands[]

Возвращает данные, полученные при инициализации смартапа. Передает в Assistant Client текущего ассистента, а не ассистента, выставленного по умолчанию. Если при запуске смартапа не вызвать команду getInitialData(), то команды из appInitialData будут отправляться в on('data').

getRecoveryState(): unknown

Возвращает состояние, сохраненное при закрытии смартапа. Устройство запоминает последнее состояние, которое возвращает функция getRecoveryState при инициализации Assistant Client.

on('start', cb: () => void): void

Осуществляет подписку на событие готовности ассистента к работе.

on('data', cb: (data: AssistantCharacterCommand | AssistantNavigationCommand | AssistantInsetsCommand | AssistantThemeCommand | AssistantSmartAppError | AssistantSmartAppCommand) => {}): void

Осуществляет подписку на событие получения данных с бэкенда. Получает команды из appInitialData, если при запуске смартапа не была вызвана команда getInitialData().

sendAction({ type: string; payload: Record<string, unknown> }, params?: { name?: string; requestId?: string }) => void

Передает ошибки и обработчики ответа от бэкенда. sendAction — отправляет server-action и типизирует сообщения data и error. clear() — делает отписку от сообщений бэкенда. Это означает, что сообщения не будут переданы в обработчик assistant.on('data')

Пример:

import { AssistantSmartAppCommand } from '@sberdevices/assistant-client';

interface SomeBackendMessage extends AssistantSmartAppCommand['smart_app_data'] {
  type: 'target_action',
  payload: {
    data: ['some_data'],
  },
}

const unsubscribe = assistant.sendAction<SomeBackendMessage>({ type: 'some_action_name', payload: { someParam: 'some_value' } },
  ({ payload }) => {
    // обработка payload.data
    unsubscribe();
  }, (error) => {});

sendData({ action: AssistantServerAction, requestId?: string }, onData?: data: AssistantCharacterCommand | AssistantNavigationCommand | AssistantSmartAppError | AssistantSmartAppCommand) => void): () => void

Отправляет события с фронтенда на бэкенд через ассистента. Первый параметр (обязательный) принимает данные для отправки. Второй параметр (опциональный) принимает обработчик ответа (на переданные первым параметром данные). В этом случае в on('data') ответ не приходит. Возвращает функцию, вызов которой отменяет обработчик ответа.

Пример с обработкой ответа:

...

const unsubscribe = assistant.sendData({ action: { type: 'some_action_name' } }, (data: command) => {
  if (data.type === 'smart_app_data' && data.smart_app_data.type === 'target_action') {
    unsubsribe();
    ... // обработка команды
  }
});

setGetState(nextGetState: () => AssistantAppState): void

Подменяет callback, который возвращает актуальное состояние смартапа.

setGetRecoveryState(nextGetRecoveryState: () => unknown)

Подменяет callback, который возвращает объект, доступный только при следующем запуске смартапа. Данные приходят при вызове getRecoveryState.

Форматы объектов

`AssistantAppState`

Объект AssistantAppState — текущее состояние смартапа, которое не хранится в платформе или сценарии. Каждый раз, когда пользователь начинает говорить, Assistant Client вызывает getState, чтобы получить и передать в бэкенд состояние экрана пользователя. То, что происходит на экране у пользователя и как он взаимодействует со смартапом в конкретный момент времени — ответственность смартапа. Assistant Client в данном случае — это буфер, который только передает состояние платформе или сценарию.

interface AssistantAppState {
  // Любые данные, которые могут потребоваться в бэкенде для принятия решений
  [key: string]: unknown;
  item_selector?: {
    ignored_words?: string[];
    // Список соответствий между голосовыми командами и действиями в приложении
    items: AssistantViewItem[];
  };
}

interface AssistantViewItem {
  // Уникальный (в рамках items) порядковый номер элемента, который назначается смартапом
  number?: number;
  // Уникальный id элемента
  id?: string;
  // Ключевая фраза, которая должна приводить к данному действию
  title?: string;
  // Фразы-синонимы, которые должны приводить к данному действию
  aliases?: string[];
  // Проксирование action обратно на бэкенд
  server_action?: AssistantServerAction;
  // Выполнение действия от имени пользователя
  action?: Action | { type: string };
  // Дополнительные данные для бэкенд
  [key: string]: unknown;
}

Например, когда пользователь говорит «Покажи 1», бэкенд должен понимать, что скрывается за единицей (то есть, какой элемент у пользователя пронумерован этой цифрой). Ниже пример состояния, который позволяет понять бэкенду, что, называя «1», пользователь хочет чипсы.

{
  item_selector: {
    ignored_words: ["покажи"],
    items: [
      { title: 'Сладкий попкорн' },
      { title: 'Соленый попкорн' },
      { title: 'Чипсы', number: 1 },
      { title: 'Начос', number: 2 },
      { title: 'Кола', number: 3 }
    ]
  }
}

`AssistantServerAction`

Объект AssistantServerAction — это любое сообщение, которое отправляется с фронтенда на бэкенд. Оно может быть привязано к ui-элементу и приходить с бэкенд, или формироваться самостоятельно фронтовой частью при обработке событий внутри WebView смартапа.

interface AssistantServerAction {
  // Тип Server Action
  type: string;
  // Любые параметры
  payload?: Record<string, unknown>;
}

`AssistantCharacterCommand`

Объект AssistantCharacterCommand — информирует смартап о текущем персонаже (Сбер, Афина или Джой). Персонаж может быть изменен в любой момент по инициативе пользователя. Поэтому разработчик может дополнительно добавить обработку таких изменений.

interface AssistantCharacterCommand {
  type: "character";
  character: {
    id: "sber" | "eva" | "joy";
  };
  sdk_meta: {
    requestId: string;
  };
}

`AssistantNavigationCommand`

Объект AssistantNavigationCommand — команда навигации пользователя по смартапу (вперед, назад, дальше и т. д.). В платформе виртуального ассистента есть стандартные фразы, которые приходят и обрабатываются одинаково для всех смартапов.

interface AssistantNavigationCommand {
  // Тип команды
  type: "navigation";
  // Навигационная команда (направление навигации)
  navigation: { command: "UP" | "DOWN" | "LEFT" | "RIGHT" | "FORWARD" };
  sdk_meta: {
    requestId: string;
  };
}

`AssistantInsetsCommand`

Объект AssistantInsetsCommand — команда, которая сообщает смартапу о том, что поверх него будет отображен нативный UI и его размеры. В insets передаются отступы от краев экрана. Их нужно соблюдать, чтобы не было наложения нативных UI элементов и контента смартапа.

interface AssistantInsetsCommand {
  type: 'insets';
  insets: {
    left: number;    //px
    top: number;     //px
    right: number;   //px
    bottom: number;  //px
  };
}

`AssistantThemeCommand`

Объект AssistantInsetsCommand - команда, которая сообщает смартапу текущую тему платформы — тёмная или светлая. По умолчанию нужно использовать тёмную тему.

interface AssistantThemeCommand {
   type: 'theme';
   theme: {
      name: 'dark' | 'light'
   }
}

`AssistantSmartAppError`

Объект AssistantSmartAppError — это уведомление об ошибке.

interface AssistantSmartAppError {
  type: 'smart_app_error';
  smart_app_error: {
    code: number;
    description: string;
  };
}

`AssistantSmartAppCommand`

Объект AssistantSmartAppCommand — это команда передачи смартапу любых данных с бэкенда.

interface AssistantSmartAppCommand {
  // Тип команды
  type: "smart_app_data";
  smart_app_data: {
    type: string;
    // Любые данные, которые нужны смартапу
    payload: Record<string, unknown>;
  };
  sdk_meta: {
    requestId: string;
  };
}

Пульт

Нажатие кнопок на пульте

Для получения и обработки нажатия кнопок на пульте от SberBox необходимо подписаться на события нажатия клавиш клавиатуры. Пример ниже:

window.addEventListener('keydown', (event) => {
  switch(event.code) {
    case 'ArrowDown':
      // вниз
      break;
     case 'ArrowUp':
      // вверх
      break;
     case 'ArrowLeft':
      // влево
      break;
     case 'ArrowRight':
      // вправо
      break;
     case 'Enter':
      // ок
     break;
  }
});

Навигация по страницам смартапа

Для корректной обработки кнопки back и навигации по страницам смартапа необходимо построить историю переходов, используя History API. Например, подписываемся на window.onpopstate и реализуем изменение страницы в обработчике этого события. Когда хотим выполнить изменение страницы, вызываем window.history.pushState:


const [page, setPage] = useState<string>('previous');

const handleNext = () => {
  window.history.pushState({ page: 'next' }, ''); // инициируем переход на следующую страницу
}

useEffect(() => {
  window.history.replaceState({ page: 'previous' }, ''); // устанавливаем текущую страницу
  window.onpopstate = ({ state }) => {
    setPage(state.page); // выполняем переход на заданную страницу: next - по вызову handleNext или previous - по нажатию кнопки back
  }
}, []);

Утилиты для тестирования

Имитация команд ассистента

Для имитации команд от ассистента используйте утилиту createAssistantHostMock. Ниже приведен пример использования. Полный пример доступен по ссылке.

import { createAssistantHostMock } from '@sberdevices/assistant-client';

const ITEMS = [
  {
    id: 1,
    title: 'Купить молоко',
    number: 1,
  },
  {
    id: 2,
    title: 'Купить хлеб',
    number: 2,
  },
];

describe('Мой список дел', () => {
  it('По клику на чекбокс - ожидаем экшен "done" c заголовком выбранного элемента', (done) => {
    cy.visit('/')
      .window()
      .then((window) => {
        const mock = createAssistantHostMock({ context: window });
        const selected = ITEMS[1];
        mock.onReady(() => {
          // эмулируем инициализационную команду от бэкенда со списком задач
          mock.receiveCommand({
            type: 'smart_app_data',
            action: {
              type: 'init',
              notes: [...ITEMS],
            },
          })
          .then(() =>
            // ожидаем вызов assistantClient.sendData
            mock.waitAction(() =>
                // эмулируем отметку выполнения пользователем, который должен вызвать sendData({ action: { type: 'done } })
                window.document.getElementById(`checkbox-note-${selected.id}`).click(),
            ),
          )
          .then(({ action, state }) => {
            expect(action.type).to.equal('done'); // ожидаем экшен data_note
            expect(action.payload?.title).to.equal(selected.title); // ожидаем в параметрах title экшена
            expect(state?.item_selector.items).to.deep.equal(ITEMS); // ожидаем отправку списка в стейте
            done();
          });
        });
      });
  });
});

createAssistantHostMock можно вызывать только при использовании createAssistant. Например, при использовании cypress функция инициализации ассистента может выглядеть следующим образом:

import { createAssistant, createSmartappDebugger } from '@sberdevices/assistant-client';

const initializeAssistant = (getState: AssistantAppState) => {
    if (process.env.NODE_ENV === 'development' && window.Cypress == null) {
        return createSmartappDebugger({
            token: process.env.REACT_APP_TOKEN ?? '',
            initPhrase: `Запусти ${process.env.REACT_APP_SMARTAPP}`,
            getState,
        });
    }

    if (window.cypress) {
      window.appInitialData = [];
    }

    return createAssistant({ getState });
};

addActionHandler(actionType: string, handler: (action: AssistantServerAction) => void): void

Подписка на экшены фронтенда с определенным type, который передается первым параметром.

removeActionHandler(actionType: string): void

Отмена подписки от экшенов фронтенда.

receiveCommand(command: AssistantClientCommand): Promise

Эмуляция команды, полученной от бэкенда. Команда приходит подписчикам AssistantClient.onData.

waitAction(onAction?: () => void): Promise<{ state: AssistantAppState; action: AssistantServerAction; name?: string; requestId?: string; }>

Получение promise, который будет разрезолвлен при следующем вызове AssistantClient.sendData

onReady(cb: () => void): void

Подписка на события готовности утилиты. Параметр cb будет вызван по готовности к работе.

Запись лога сообщений

В режиме разработки есть возможность записать и скачать лог сообщений. Управление записью осуществляется кнопками start и stop. Кнопка save сохранит файл с логом в загрузки браузера. Пример активации панели управления записью лога:

import { createSmartappDebugger } from '@sberdevices/assistant-client';

const assistant = createSmartappDebugger({
    token: process.env.REACT_APP_TOKEN ?? '',
    initPhrase: `Запусти ${process.env.REACT_APP_SMARTAPP}`,
    getState,
    enableRecord: true, // активируем функцию записи лога
    recordParams: {
      defaultActive: true, // включать запись при старте приложения (по-умолчанию = true)
    }
  });

Воспроизведение лога сообщений

Пример пошагового воспроизведения лога сообщений. Входящие сообщения от ассистента будут последовательно переданы подписчикам AssistantClient.on('data').

import { createRecordPlayer } from '@sberdevices/assistant-client';
import assistantLog from './assistant-log.json';

const player = createRecordPlayer(assistantLog);
let end = false;

while(!end) {
  end = !player.continue();
}

continue(): boolean

Передает следующее сообщение от ассистента в AssistantClient (может содержать несколько команд). Возвращает флаг наличия в логе следующих сообщений от ассистента.

play(): void

Последовательно передает все сообщения лога от ассистента в AssistantClient.

getNextAction: { action: AssistantServerAction; name?: string; requestId?: string; }

Возвращает следующее сообщение от AssistantClient (вызов sendData) в ассистент. Можно использовать для сравнения эталонного сообщения (из лога) и текущего в тесте.

setRecord(record: AssistantRecord): void

Загружает указанную запись в плеер.

FAQ

Не работает озвучка и/или микрофон в браузере

Нужно перейти в настройки сайта и разрешить доступ к звуку и микрофону.