Инструменты и технологии/SmartApp API/

Элементы интерфейса смартапов

Элементы интерфейса из массива items сообщения ANSWER_TO_USER.

Смартапы могут передавать ассистенту следующие элементы интерфейса:

  • bubble — текст;
  • card — карточка.

Ассистент отображает элементы интерфейса в порядке, в котором они расположены в массиве items.

bubble

Пример:

{
    "bubble": {
        "text": "*Привет всем*",
        "markdown": true,
        "expand_policy": "auto_expand"
    }
}

Текст передается в объекте bubble, который может содержать следующие поля:

Поле Описание
text

string

Текст, который отобразит ассистент.

Максимальная длина: не более 250 символов.
markdown

bool

Указывает, что текст содержит маркдаун-разметку, которую необходимо обработать.

Если поле отсутствует, применяется значение false и текст отображается в исходном виде.
expand_policy

string

Поведение шторки ассистента. Параметр актуален при работе с ассистентом на наших устройствах. 

Возможные значения:

  • auto_expand — шторка будет автоматически разворачиваться, если полученный текст не помещается в свёрнутой шторке;
  • force_expand — шторка развернётся независимо от того, помещается полученный текст в свёрнутой шторке или нет;
  • preserve_panel_state — сохраняет текущее состояние шторки независимо от длины текста.

По умолчанию auto_expand.

card

Карточки помогают смартапам организовать сложную информацию на экране ассистента. Внешний вид карточек отличается в зависимости от типа смартапа (Chat App или Canvas App), а так же в зависимости от типа поверхности (SberBox, SberPortal или приложение Сбер Салют).

Карточки бывают следующих типов:

Ниже приводятся JSON-схемы карточек с примерами.

Карточки передаются в объектах card. Следующие поля присутствуют в карточках любого типа:

Поле Описание
paddings

object

Описание отступов карточки.
can_be_disabled

boolean

Указывает что карточка может отображаться как отключённая. По умолчанию false.

type

Обязательное

string

Тип карточки, который определяет наличие различных полей в объекте card.

Возможные значения:

  • gallery_card — горизонтальная галерея;
  • grid_card — карточка с сеткой ячеек.
  • list_card — карточка со списком ячеек.

grid_card

Карточка с сеткой ячеек:

Карточка с сеткой ячеек.

{
    "card": {
        "type": "grid_card",
        "items": [
            {
                "type": "greeting_grid_item",
                "top_text": {
                    "type": "text_cell_view",
                    "text": "СОБЕСЕДНИК",
                    "typeface": "caption",
                    "text_color": "default"
                },
                "bottom_text": {
                    "type": "text_cell_view",
                    "text": "Какая высота Эвереста?",
                    "typeface": "body3",
                    "text_color": "default",
                    "max_lines": 3,
                    "margins": {
                        "top": "4x"
                    }
                },
                "paddings": {
                    "top": "6x",
                    "left": "6x",
                    "right": "6x",
                    "bottom": "6x"
                },
                "actions": [
                    {
                        "text": "Какая высота Эвереста?"
                    }
                ]
            },
            {
                "type": "greeting_grid_item",
                "top_text": {
                    "type": "text_cell_view",
                    "text": "КОШЕЛЕК",
                    "typeface": "caption",
                    "text_color": "default"
                },
                "bottom_text": {
                    "type": "text_cell_view",
                    "text": "Сколько у меня денег?",
                    "typeface": "body3",
                    "text_color": "default",
                    "max_lines": 3,
                    "margins": {
                        "top": "4x"
                    }
                },
                "paddings": {
                    "top": "6x",
                    "left": "6x",
                    "right": "6x",
                    "bottom": "6x"
                },
                "actions": [
                    {
                        "text": "Сколько у меня денег?"
                    }
                ]
            },
            {
                "type": "greeting_grid_item",
                "top_text": {
                    "type": "text_cell_view",
                    "text": "ПОГОДА",
                    "typeface": "caption",
                    "text_color": "default"
                },
                "bottom_text": {
                    "type": "text_cell_view",
                    "text": "Какая погода вечером в Москве?",
                    "typeface": "body3",
                    "text_color": "default",
                    "max_lines": 3,
                    "margins": {
                        "top": "4x"
                    }
                },
                "paddings": {
                    "top": "6x",
                    "left": "6x",
                    "right": "6x",
                    "bottom": "6x"
                },
                "actions": [
                    {
                        "text": "Какая погода вечером в Москве?"
                    }
                ]
            },
            {
                "type": "greeting_grid_item",
                "top_text": {
                    "type": "text_cell_view",
                    "text": "ПЕРЕВОД",
                    "typeface": "caption",
                    "text_color": "default"
                },
                "bottom_text": {
                    "type": "text_cell_view",
                    "text": "Отправь маме 500 рублей",
                    "typeface": "body3",
                    "text_color": "default",
                    "max_lines": 3,
                    "margins": {
                        "top": "4x"
                    }
                },
                "paddings": {
                    "top": "6x",
                    "left": "6x",
                    "right": "6x",
                    "bottom": "6x"
                },
                "actions": [
                    {
                        "text": "Отправь маме 500 рублей"
                    }
                ]
            }
        ],
        "columns": 2,
        "item_width": "small"
    }
}
Поле Описание
columns

integer

Количество столбцов. По умолчанию 1 столбец.
item_width

string

Ширина контента в терминах сеток.

Возможные значения:

  • small;
  • medium;
  • large;
  • resizable.

items

Обязательное

array of objects

Ячейки карточки. Минимум 1 ячейка.

type

Обязательное

string

Тип ячейки.

Возможное значение:

  • greeting_grid_item — элемент карточки приветствия.

top_text

Обязательное

object

Параметры верхнего текста.

bottom_text

Обязательное

object

Параметры нижнего текста.

margins

object

Отступы.

actions

array of objects

Массив объектов, описывающих действия.

Горизонтальная галерея.

Пример отображения вертикальной галереи:

Галерея в вертикальной ориентации экрана

Пример отображения горизонтальной галереи:

Галерея в горизонтальной ориентации экрана

{
    "card": {
        "type": "gallery_card",
        "items": [
            {
                "type": "media_gallery_item",
                "image": {
                    "url": "https://thumbs.dfs.ivi.ru/storage31/contents/8/e/010ea0147875e28b91ef1ff01cd042.jpg",
                    "size": {
                        "width": "medium",
                        "aspect_ratio": 1.42
                    }
                },
                "margins": {
                    "top": "4x",
                    "left": "6x",
                    "right": "6x",
                    "bottom": "5x"
                },
                "bottom_text": {
                    "text": "2019 г. ‧ Комедия/Драма",
                    "typeface": "caption",
                    "text_color": "secondary",
                    "max_lines": 1,
                    "margins": {
                        "top": "2x"
                    }
                },
                "top_text": {
                    "text": "Однажды в Голливуде",
                    "typeface": "footnote1",
                    "text_color": "default",
                    "max_lines": 2
                }
            }
        ]
    }
}

Поле Описание

items

Обязательное

array of objects

Ячейки карточки. Минимум 1 ячейка.

type

Обязательное

string

Тип ячейки.

Возможное значение:

  • media_gallery_item — элемент галереи состоящий из изображения и двух текстовых полей.
  • gallery_more_button_item — Кнопка Все результаты в карточке галереи.

image

object

Параметры изображения.

Поле обязательно для ячеек с типом media_gallery_item.

top_text

object

Параметры текста над изображением.

bottom_text

object

Параметры текста под изображением или под кнопкой Все результаты.

Поле обязательно для ячеек с типом gallery_more_button_item.

icon

object

Иконка кнопки.

Поле обязательно для ячеек с типом gallery_more_button_item.

paddings

object

Отступы.

actions

array of objects

Массив объектов, описывающих действия.

Поле обязательно для ячеек с типом gallery_more_button_item.

list_card

Карточки с вертикальным списком ячеек.

Карточка с вертикальным списком ячеек

{
    "card": {
        "type": "list_card",
        "cells": [
            {
                "type": "text_cell_view",
                "content": {
                    "text": "200 гонконгских долларов 🇭🇰",
                    "typeface": "headline3",
                    "text_color": "default",
                    "max_lines": 0
                },
                "paddings": {
                    "left": "8x",
                    "top": "10x",
                    "right": "8x"
                }
            },
            {
                "type": "text_cell_view",
                "content": {
                    "text": "1 663 ₽",
                    "typeface": "headline1",
                    "text_color": "default",
                    "max_lines": 0
                },
                "paddings": {
                    "left": "8x",
                    "top": "9x",
                    "right": "8x"
                }
            },
            {
                "type": "text_cell_view",
                "content": {
                    "text": "При покупке от 500 до 1 000 HKD\n100 HKD = 6,36 RUB\nСберБанк Онлайн сейчас",
                    "typeface": "footnote1",
                    "text_color": "secondary",
                    "max_lines": 0
                },
                "paddings": {
                    "left": "8x",
                    "top": "10x",
                    "right": "8x"
                }
            },
            {
                "type": "button_cell_view",
                "content": {
                    "text": "Купить",
                    "typeface": "button1",
                    "style": "default",
                    "type": "accept",
                    "actions": [
                        {
                            "type": "text",
                            "text": "Купить"
                        }
                    ],
                    "margins": {
                        "left": "10x",
                        "top": "5x",
                        "right": "10x",
                        "bottom": "5x"
                    }
                },
                "paddings": {
                    "left": "6x",
                    "top": "12x",
                    "right": "6x",
                    "bottom": "8x"
                }
            }
        ]
    }
}

Пример карточки с ячейками типа left_right_cell_view.

Карточка с ячейками типа `left_right_cell_view` Карточка с ячейками типа `left_right_cell_view`

{
    "card": {
        "type": "list_card",
        "cells": [
            {
                "type": "left_right_cell_view",
                "paddings": {
                    "left": "8x",
                    "top": "16x",
                    "right": "4x",
                    "bottom": "16x"
                },
                "left": {
                    "type": "simple_left_view",
                    "icon": {
                        "address": {
                            "type": "url",
                            "url": "https://cdn.sberdevices.ru/VA/icons/first_session/balance.png"
                        },
                        "size": {
                            "width": "medium",
                            "height": "medium"
                        },
                        "margins": {
                            "right": "6x"
                        }
                    },
                    "icon_vertical_gravity": "top",
                    "texts": {
                        "title": {
                            "text": "Покажи баланс моей карты",
                            "typeface": "headline2",
                            "text_color": "default",
                            "max_lines": 0
                        }
                    }
                },
                "right": {
                    "type": "detail_right_view",
                    "info_and_icon": {
                        "icon": {
                            "address": {
                                "type": "url",
                                "url": "https://cdn.sberdevices.ru/VA/icons/first_session/balance.png"
                            },
                            "size": {
                                "width": "xlarge",
                                "height": "xlarge"
                            },
                            "margins": {
                                "left": "8x",
                                "right": "12x"
                            }
                        }
                    }
                },
                "actions": [
                    {
                        "type": "text",
                        "text": "Вы нажали на карточку"
                    }
                ]
            }
        ]
    }
}
Поле Описание

cells

Обязательное

array of objects

Список ячеек карточки.

type

Обязательное

string

Тип ячейки, от которого зависит её наполнение.

Возможное значение:

  • left_right_cell_view;
  • text_cell_view;
  • button_cell_view;
  • image_cell_view;
  • details_cell_view;
  • weather_cell_view.

left

object

Левый элемент ячейки.

Содержит следующие поля:

  • type — Тип левого элемента ячейки, который определяет содержимое ячейки. Обязательное поле. Возможные значения:
    • simple_left_view
    • fast_answer_left_view — Вертикальный упорядоченный список. Включает поля состоит из label, icon_and_value и margins.
  • icon — Только для ячеек с типом simple_left_view.
  • texts — Только для ячеек с типом simple_left_view.
  • icon_vertical_gravity — Только для ячеек с типом simple_left_view.
  • label — Только для ячеек с типом fast_answer_left_view.
  • icon_and_value — Объект, который описывает горизонтальный упорядоченный список, содержащий поля icon и value (обязательное). Только для ячеек с типом fast_answer_left_view.
  • margins — Только для ячеек с типом fast_answer_left_view.

right

object

Правый элемент ячейки.

Содержит следующие поля:

  • type — тип элемента. Тип string. Обязательное поле. Возможные значения: disclosure_right_view (правая угловая скобка) и detail_right_view.
  • margins — отступы элемента.

Если элемент ячейки задан как detail_right_view, поля объекта будут аналогичны полям объектов массива details (см. ниже).

paddings

object

Описание отступов ячеек.


content

Обязательное

object

Содержимое ячейки, которое зависит от её типа:

Поле присутствует только в приведённых в списке ячейках.


divider

object

Разделитель — тонкая полоска, разделяющая ячейки. Применяется только в ячейках типа left_right_cell_view.

Содержит следующие поля:

  • style — Стиль разделителя. Обязательное поле. Тип string. Возможные значения default и read_only.

  • size — Размеры разделителя. Обязательное поле. Тип string. Возможные значения:

    • d1
    • d2
    • d3
    • d4
    • d5

actions

array of objects

Массив объектов, описывающих действия. Применяется только в ячейках типа left_right_cell_view.

details

Обязательное

array of objects

Поле актуально только для ячеек с типом details_cell_view.

Содержит массив объектов, каждый из которых описывает вертикальный упорядоченный блок. Минимальное количество элементов в массиве — 1.

Объекты массива содержат следующие поля:

  • type — тип правого элемента ячейки.
  • detail — текстовый элемент.
  • info_and_icon — горизонтальный упорядоченный блок, который содержит поля info, icon и margins.
  • margins — поля ячейки.
  • vertical_gravity — вертикальное притяжение ячейки. Тип string. Возможные значения: top, center, bottom
  • detail_position — расположение объекта detail относительно info_and_icon. Тип string. Возможные значения top (по умолчанию) и bottom.

Параметры карточек

Текст

Поле Описание

text

Обязательное

string

Текст, который необходимо отобразить. Минимальная длина текста 1 символ.

typeface

Обязательное

string

Стиль текста.

Возможные значения:

  • headline1;
  • headline2;
  • headline3;
  • title1;
  • title2;
  • body1;
  • body2;
  • body3;
  • text1;
  • paragraphText1;
  • paragraphText2;
  • footnote1;
  • footnote2;
  • button1;
  • button2;
  • caption.

text_color

Обязательное

string

Цвет текста.

Возможные значения:

  • default;
  • secondary;
  • tertiary;
  • inverse;
  • brand;
  • warning;
  • critical;
  • link.
margins

object

Отступы.
max_lines

integer

Максимальное количество строк. По умолчанию 1.

Значение 0 указывает на неограниченное количество строк.
actions

array of objects

Массив объектов, описывающих действия.

Отступы

Поле Описание
left

string

Размер отступа.

Возможные значения:

  • 0x;
  • 1x;
  • 2x;
  • 4x;
  • 5x;
  • 6x;
  • 8x;
  • 9x;
  • 10x;
  • 12x;
  • 16x.

Значение по умолчанию 0x.
top

string

Размер отступа.

Возможные значения:

  • 0x;
  • 1x;
  • 2x;
  • 4x;
  • 5x;
  • 6x;
  • 8x;
  • 9x;
  • 10x;
  • 12x;
  • 16x.

Значение по умолчанию 0x.
right

string

Размер отступа.

Возможные значения:

  • 0x;
  • 1x;
  • 2x;
  • 4x;
  • 5x;
  • 6x;
  • 8x;
  • 9x;
  • 10x;
  • 12x;
  • 16x.

Значение по умолчанию 0x.
bottom

string

Размер отступа.

Возможные значения:

  • 0x;
  • 1x;
  • 2x;
  • 4x;
  • 5x;
  • 6x;
  • 8x;
  • 9x;
  • 10x;
  • 12x;
  • 16x.

Значение по умолчанию 0x.

Изображение

Поле Описание

url

Обязательное

string

Адрес изображения.
hash

string

Хэш изображения.
placeholder

string

Заглушка, которая отображается, если изображения нет или оно невалидно.
scale_mode

string

Режим растягивания содержимого.

Возможные значения:

  • scale_aspect_fill;
  • scale_aspect_fit;
  • center;
  • top;
  • bottom;
  • left;
  • right;
  • top_left;
  • top_right;
  • bottom_left;
  • bottom_right.
height

integer

Высота контейнера изображения, выраженная в независящих от платформы единицах.

Поле игнорируется, если присутствует поле size.

По умолчанию 192.
placeholder_color

string

Цвет фона.

Возможные значения:

  • solid_black;
  • solid_white;
  • solid_transparent;
  • solid_disabled;
  • solid_brand;
  • solid_warning;
  • solid_critical;
  • solid_action;
  • liquid_60;
  • liquid_50;
  • liquid_40;
  • liquid_30;
  • liquid_20;
  • liquid_10.
actions

array of objects

Массив объектов, описывающих действия.
size

object

Размер изображения.

width

Обязательное

string

Ширина содержимого в терминах сеток.

Возможные значения:

  • small;
  • medium;
  • large;
  • resizable.

aspect_ratio

Обязательное

number

Отношение высоты содержимого к ширине.

Погодные данные

Пример массива content ячейки weather_cell_view:

{
    "type": "weather_cell_view",
    "content": [
        {
            "weekday": "Понедельник",
            "date": "15 сентября",
            "day": "+5°",
            "night": "-5°",
            "icon": {
                "address": {
                    "type": "url",
                    "url": "https://example.ru/example.png"
                },
                "size": {
                    "width": "small",
                    "height": "small"
                }
            }
        },
        {
            "weekday": "Вторник",
            "date": "16 сентября",
            "day": "+23°",
            "night": "+12°",
            "icon": {
                "address": {
                    "type": "url",
                    "url": "https://example.ru/example.png"
                },
                "size": {
                    "width": "small",
                    "height": "small"
                }
            }
        }
    ],
    "paddings": {
        "top": "8x"
    }
}
Поле Описание

weekday

Обязательное

string

День недели

date

Обязательное

string

Дата

day

Обязательное

string

Погода днем

night

Обязательное

string

Погода ночью

icon

Обязательное

object

Параметры иконки

    address

    Обязательное

object

Путь к иконке

    size

    Обязательное

object

Размер иконки

        width

        Обязательное

string

Ширина иконки.
Возможные значения:

  • xsmall
  • small
  • medium
  • large
  • xlarge

        height

        Обязательное

string

Высота иконки.
Возможные значения:

  • xsmall
  • small
  • medium
  • large
  • xlarge
Назад
SmartApp API
Дальше
Команды