Проект состоит из серверной части (так называемого сценария, доступного по адресу http://localhost:3000/api/hook) и фронтенда (доступного по адресу http://localhost:3000/).
- Установить зависимости (
npm ci
) - Заполнить
NEXT_PUBLIC_SMARTAPP_TOKEN
в.env.development
(можно получить личный токен тут) - Запустить локальный сервер (
npm run dev
) - Создать туннель до локального сервера (например установив ngrok и выполнив команду
ngrok http 3000
) - Создать новый проект с типом
SmartApp -> Canvas App
в SmartMarket Studio - В параметрах проекта указать
- Тип проекта -> SmartApp API
- Внешняя ссылка ->
<https ссылка туннеля>/api/hook
- Хостинг фронтенда ->
<https ссылка туннеля>
К стандартным девайсам доступным для отладки в Google Chrome можно добавить SberBox (см. скриншот) или другое устройство и зайти на http://localhost:3000/ в браузере.
Для отладки на реальном устройстве нужно войти на устройство под тем же SberId, что и в SmartMarket Studio и сказать голосовому ассистенту активационную фразу NEXT_PUBLIC_SMARTAPP_INIT_PHRASE
из .env.development
(например Запусти туду тест
). Если туннель (см. выше) активен, то этого достаточно, если нет, то вначале надо настроить туннелинг.
npm run build
npm start
Шаблон основан на nextjs
Все данные для Canvas App поступают из сценария от AssistantClient. То есть любой запрос за данными попадает в AssistantClient и только потом в серверную часть приложения (сценарий). При этом у сценария ровно одна точка входа - /api/hook
. В примере такие запросы делаются при помощи хуков-оберток над useQuery/useMutation
из библиотеки react-query.
При этом какие-то запросы могут бы инициированы голосовой командой пользователя, а какие-то взаимодействием пользователя с интерфейсом. Некоторые команды могут быть инициированы обоими способами (например doneNote
). Во всех случаях полученные от AssistantClient данные записывают в кеш react-query
.
В примере есть поддержка статической генерации страниц. Для разных поверхностей в момент сборки проекта будет сгенерирован статический html для моментальной отдачи пользователю при запросе (без необходимости как клиентского так и серверного рендеринга). При этом nextjs
поддерживает и другие способы доставки страниц до пользователя.
В урл будут добавлены суффиксы поверхности и персонажа, например: /joy/@mobile/
Под поверхностью подразумевается группа устройства, на котором будет работать Canvas App. В данной примере 3 поверхности: мобильное устройство, SberBox и SberPortal.
Для каждой поверхности могут быть разные React компоненты, которые нужны на одной поверхности и не нужны на другой. То есть JS-бандл должен содержать только нужные для текущей поверхности компоненты. Для этого все компоненты (а точнее страницы) поделены на папки (@mobile
, @portal
, @sberbox
), которые соответствуют урлам в nextjs
. Благодаря этому nextjs
делает код-сплиттинг по поверхностям (урлам), и компоненты для @sberbox
не окажутся в JS-бандле для @mobile
.
Каждая страница в такой директории будет импортировать только необходимые для данной платформы компоненты, избегая импорта, а значит и загрузки, компонентов других поверхностей.
В пример уникальных для поверхности файлов нет, но в реальных проектах они могут появится.
Персонаж выбирается пользователем и может быть одним из трех заданных (eva
, sber
, joy
). Так как подразумевается, что разделение стилей для персонажей не требуется, используется динамический роутинг, вместо статического.