@sberdevices/assistant-client

Sberdevices Assistant Client

Assistant Client - это инструмент для встраивания Виртуального Ассистента (ВА) на различные поверхности.

Технически Assistant Client представляет собой интегрируемый в WebView JS-код, который связан биндингами с нативным кодом операционной системы. В режиме разработки используется реализация протокола на javascript (эмулирует среду Android), что позволяет запускать ассистент в браузере.

Установка:

$ npm install @sberdevices/assistant-client

Quickstart

import { createAssistant, createAssistantDev, AssistantAction, AssistantServerAction, AssistantCharacterCommand, AssistantNavigationCommand, AssistantSmartAppCommand, AssistantAppState } from '@sberdevices/assistant-client';

const initialize = (getState: AssistantAppState): {
    getInitialData: () => AssistantCommands[];
    on: ('start' || 'data', cb: (data?: AssistantCharacterCommand | AssistantNavigationCommand | AssistantSmartAppCommand) => void) => void;
    sendData: (data: AssistantAction | AssistantServerAction) => void;
    setGetState: (getState: () => AssistantAppState) => void;
} => {
    if (process.env.NODE_ENV === 'development') {
        return createAssistantDev({
            url: 'wss://...', // стенд
            surface: '...', // поверхность
            channel: '...', // канал
            getState,
            initPhrase: 'Хочу попкорн', // фраза для запуска аппа
            nativePanel: {
                defaultText: 'Кутузовский д.32', // текст в панели
            },
        });
    }

    return createAssistant({ getState });
}

...

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

const handleOnClick = () => {
    // отправка ServerAction
    assistant.sendData({ action_id: 'some_action_name' });
};

API

createAssistant

Создает экземпляр AssistantClient, обязательный параметр getState - функция, которая возвращает актуальное состояние смартаппа при каждом обращении к бэкенду.

createAssistantDev

Создает экземпляр AssistantClient, добавляет на экран браузера панель с голосовым ассистентом, подобно устройствам. Панель позволяет вводить команды с клавиатуры и голосом. Также активируется озвучка ассистента.

Параметр	Dev only	Описание
getState*	[]	Функция, которая возвращает актуальное состояние смартаппа.
url*	[x]	Стенд.
userChannel*	[x]	Канал.
surface*	[x]	Поверхность.
initPhrase*	[x]	Текст команды для запуска смартаппа (закажи попкорн и т.п).
nativePanel	[x]	Конфигурация панели ассистента.
userId	[x]	Идентификатор пользователя.
token	[x]	Токен.
enableRecord	[x]	Флаг активации функции записи диалога (true/false).

Панель ассистента

По-умолчанию, в режиме разработки, панель отрисовывается. Чтобы выключить панель ассистента в режиме разработки, необходимо установить значение null, соответствующему параметру.

import { createAssistantDev } from '@sberdevices/assistant-client';
 
const assistant = createAssistantDev({ ..., nativePanel: null });

Первоначальный текст в панели ассистента конфигурируется установкой параметра defaultText.

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

const assistant = createAssistantDev({ ..., nativePanel: { defaultText: 'Покажи 1' } });

Логирование диалога с ассистентом

В режиме разработке, в целях отладки и тестирования, есть возможность получить файл с записью разговора ассистента. По-умолчанию, эта возможность деактирована, для активаци необходимо установить значение параметра enableRecord: true. В результате, на экране будут отрисованы кнопки управления записью диалога (start/stop/save).

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

createAssistantDev({
    getState,
    ...
    enableRecord: true
});

createRecordPlayer - возвращает RecordPlayer, предоставляет возможность воспроизведения диалога. Принимает два необязательных параметра - запись и объект window (для взаимодействия с assistant-client).

interface RecordPlayer {
    /* проиграть следующую реплику, возвращает флаг наличия следующей реплики */
    continue: () => boolean;
    /* проиграть весь диалог до конца */
    play: () => void;
    /* Установить запись */
    setRecord: (record: AssistantRecord) => void;
}

Пример интеграции с cypress:

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

describe('Тест', () => {
    it('Запуск аппа', () => {
        cy.fixture('app_start.json').then((record) => {
            cy.window().then((win) => {
                const player = createRecordPlayer(record, win);
                player.play();
            });
        });
    });
);

AssistantClient

getInitialData(): AssistantCommands[]

Возвращает данные, полученные при инициализации смартаппа

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

Подписка на событие готовности ассистента к работе

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

Подписка на событие получения данных от бэкенда

sendData(data: AssistantAction | AssistantServerAction): void

Отправляет сервер-экшен, который будет передан бэкенду

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

Подменяет колбек, возвращаюший актуальное состояние приложения

Формат объекта AssistantAppState

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

Каждый раз, когда пользователь начинает говорить, Assistant Client вызывает коллбек getState, чтобы получить и передать бэкенду состояние экрана пользователя.

interface AssistantAppState {
    /* Любые данные, которые могут потребоваться Backend'у для принятия решений */
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    [key: string]: any;
    item_selector?: {
        ignored_words?: string[];
        /* Список соответствий голосовых команд действиям в веб-приложении */
        items: AssistantViewItem[];
    };
}

interface AssistantViewItem {
    /* Порядковый номер элемента, назначается смартаппом, уникален в рамках items */
    number?: number;
    /* Уникальный id элемента */
    id?: string;
    /* Ключевая фраза, которая должна приводить к данному действию */
    title?: string;
    /* Фразы-синонимы, которые должны быть расценены как данное действие */
    aliases?: string[];
    /* Сервер экшен, проксирует action обратно на бекэнд. */
    server_action?: AssistantServerAction,
    /* Экшен, выполяет действие от имени пользователя */
    action?: AssistantAction;
    /* Дополнительные данные для бэкенда */
    [key: string]: any;
}

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

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

Формат объекта AssistantAction

AssistantAction - это действие, которое выполнит SDK от имени пользоваля: откроет ссылку или отправит сообщение в чат.

type AssistantAction = AssistantDeepLinkAction | AssistantTextAction;

interface AssistantTextAction {
    type: 'text';
    /* Строка из поля text будет отправлена в чат от имени пользователя */
    text: string;
    /* default = true, true если сообщение нужно отобразить в чате и отправить в бекэнд, false если сообщение нужно только отобразить в чате, и не отправлять на бекэнд */
    should_send_to_backend?: boolean;
}

interface AssistantDeepLinkAction {
    type: 'deep_link';
    /* https ссылки будут открыты в браузере, а android-app://ru.sberbankmoblie/... - будут открыты в приложении */
    deep_link: string;
}

Формат объекта AssistantServerAction

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

interface AssistantServerAction {
    /* Тип сервер-экшена */
    action_id: string;
    /* любые параметры */
    parameters?: Record<string, any>;
}

Формат объекта AssistantCharacterCommand

AssistantCharacterCommand - информирует смартапп о текущем ассистенте.

interface AssistantCharacterCommand {
    type: 'character';
    character: {
        id: 'sber' | 'eva' | 'joy';
    };
}

Формат объекта AssistantNavigationCommand

AssistantNavigationCommand - команда навигации пользователя по смартаппу. Большая часть навигационных команд может быть выполнена стандартным средствами Assistant Client. В платформе виртуального ассистента есть стандартные фразы, которые обрабатываются единым образом. Они обрабатываются и приходят одинаково для всех смартапов.

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

Формат объекта AssistantSmartAppCommand

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

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

Разрешения устройств

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