API SmartRating

Обновлено 19 февраля 2025

SmartRating

Вы можете встроить в ваш смартап запрос оценки у пользователя.

Статистика по оценкам доступна в Studio в разделе Оценки.

Формат запроса

Чтобы запросить у пользователя оценку, настройте в сессии диалога отправку сообщения с "messageName": "CALL_RATING" и обработку ответа.

Метод CALL_RATING позволяет вызывать сервис только по инициативе пользователя — после нажатия на соответствующую кнопку или саджест. Для этого вам нужно добавить в сценарий кнопку или саджест, предлагающие пользователю оценить смартап. Рекомендуемые названия смотрите в разделе Правила использования.

{
  "messageId": 1605196199186625000,
  "sessionId": "0062530b-5521-42cc-90b0-a9d65dea4e98",
  "messageName": "CALL_RATING",
  "uuid": {
    "userId": "ec8a9097-1508-4bec-8d97-67f2329c03e0"
  },
  "payload": {}
}

messageId

number

Идентификатор сообщения

sessionId

uuid4

Идентификатор сессии

messageName

string

По умолчанию: CALL_RATING

Название сообщения. Для обращения к сервису SmartRating используйте значение CALL_RATING.

uuid

object

userId

uuid4

Идентификатор пользователя

payload

object

Пустой объект

Формат ответа

Ответ возвращается в сообщении RATING_RESULT.

{
  "messageId": 1605196199186625000,
  "sessionId": "0062530b-5521-42cc-90b0-a9d65dea4e98",
  "messageName": "RATING_RESULT",
  "payload": {
    "rating": {
      "estimation": 5
    },
    "status_code": {
      "code": 1,
      "description": "SUCCESS"
    }
  },
  "uuid": {
    "userId": "ec8a9097-1508-4bec-8d97-67f2329c03e0"
  }
}

messageId

number

Идентификатор сообщения

sessionId

uuid4

Идентификатор сессии

messageName

string

По умолчанию: RATING_RESULT

Название сообщения. В ответ на сообщение CALL_RATING приходит сообщение RATING_RESULT.

payload

object

Результат оценки

rating

object

Информация об оценке

estimation

number

Пользовательская оценка. От 1 до 5

status_code

object

Описание ответа

code

number

Возможные значения: [1, 101, 104]

Код ответа

description

string

Возможные значения: [SUCCESS, SKIP BY USER, FORBIDDEN]

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

• SUCCESS — Получена оценка от пользователя. Соответствует коду 1
• SKIP BY USER — Пользователь отклонил выставление оценки или закрыл приложение. Соответствует коду 101
• FORBIDDEN — Запрет на вызов сервиса по прочим причинам. Соответствует коду 104

uuid

object

userId

uuid4

Идентификатор пользователя

Примеры встраивания в смартап

Вы можете встроить сервис в сценарий смартапа независимо от того, с помощью каких инструментов он разработан. Для этого отправьте в сессии диалога сообщение CALL_RATING .

Для Code

Вызов оценки

Если вы создали Chat App или Canvas App с помощью Code, то для вызова оценки по методу CALL_RATING добавьте в стейт, который будет обрабатывать действие пользователя, следующий скрипт:

script: $smartRating.callRating();

Чтобы настроить вызов CALL_RATING более детально, используйте следующий код:

script:
    $response.replies = $response.replies || [];
    $response.replies.push({
        'type': "raw",
        'messageName': 'CALL_RATING',
        'body': { }
    });

Обработка ответа

Для обработки ответа RATING_RESULT добавьте в стейт, куда будет возвращен пользователь после оценки или отказа, строку:

event!: RATING_RESULT

Статус запроса

Cтатус запроса оценки можно получить с помощью переменной $request.data.eventData:

$request.data.eventData.status_code.code

Если пользователь оценил смартап, в ответе вернется код 1, если отказался оценивать — коды 101, 102, 103 или 104.

Результат оценки

Если пользователь оценил смартап, то вы можете узнать результат:

# Пользовательская оценка. От 1 до 5
$request.data.eventData.rating.estimation

Для Graph

Если вы создали Chat App с помощью Graph, то при создании экрана выберите действие SmartRating.

Затем добавьте в сценарий обработку следующих вариантов ответа:

1. Получена оценка.
2. Отклонено пользователем.
3. Запрещено.

Для SaluteJS

Если вы создали Chat App или Canvas App с помощью SaluteJS, то для вызова оценки используйте хендлер:

export const CallRatingHandler: SaluteHandler = ({res, req}) => {
    // @ts-ignore
    res.message.messageName = 'CALL_RATING'
}

Обработка ответа:

export const RatingResultHandler: SaluteHandler = ({res, req}) => {
}

Сценарий для обработки текста или триггера для вызова оценки и обработки события RATING_RESULT:

callRating: {
        match: text('Оценить приложение'),
        handle: CallRatingHandler
    },
resultRating: {
        match: action('RATING_RESULT'),
        handle: RatingResultHandler
    }

Для HTML5-игр

Если вы портировали HTML5-игру, используя базовый сценарий обработки голосом в качестве вебхука, то для отображения саджеста, который вызовет оценку, отправьте action SHOW_RATING_SUGGEST.

// Перед вызом предложения об оценке
// Подключите и инициализируйте ассистента
<script src="https://unpkg.com/@salutejs/client@1.0.0/umd/assistant.production.min.js"></script>
<script>
  const client = assistant.createAssistant({ getState: () => ({}), getRecoveryState: () => ({}), });
</script>

//...

const handleOnClick = () => {
// Отправка сообщения ассистенту с фронтенда.
// Структура может меняться на усмотрение разработчика, в зависимости от логики бэкенда
client.sendData({ action: { action_id: 'SHOW_RATING_SUGGEST'} });
};

Для Native App

Подключение и настройка сценария

Чтобы встроить в Native App запрос оценки пользователя:

1. В пространстве, где находится проект NativeApp, создайте проект Code для SmartApp.
2. В созданном проекте перейдите в раздел Сценарии.
3. Откройте файл main.sc и добавьте в него код:

theme: /

    state: Start
        q!: $regex</start>
        script:
            $response.replies = $response.replies || [];
            $response.replies.push({
                    "type": "raw",
                    "body": {
                        "items": [
                            {
                                "command": {
                                    "type": "smart_app_data",
                                    "smart_app_data": { }
                                }
                            }
                        ]
                    },
                    "messageName":"ANSWER_TO_USER"
                });
            $jsapi.log("[START]");

    state: RatingResult
        event!: RATING_RESULT
        script: $jsapi.log("[RATING_RESULT]");

    state: Каталог
        q!: * оцен* *
        script:
            $jsapi.log("[CALL_RATING]");
            $smartRating.callRating();

    state: nothing_found
        event!: noMatch
        script:
            $jsapi.log("[NOTHING_FOUND]");
            $response.replies = $response.replies || [];
            $response.replies.push({
                type: 'raw',
                messageName: 'NOTHING_FOUND',
                body: {},
            });

4. Нажмите Сохранить, затем — Собрать.
5. Перейдите в раздел Настройки проекта и на вкладке Дополнительно включите параметр Отправлять команду /start на запуск голосом.
6. Перейдите в проект NativeApp, в раздел Параметры, на вкладку Основные настройки.
7. В поле Тип сценария выберите Code.
8. В поле Сценарий выберите созданный проект Code.
9. В поле Версия выберите последнюю версию.
10. Нажмите Сохранить.

Теперь если внутри приложения пользователь скажет любую фразу, содержащую слово «оценка», «оценку», «оценить» и т. д., то откроется оценка смартапа.

Также вы можете предложить пользователю оценить приложение, для этого добавьте в сценарий саджест.

Настройка фраз вызова оценки

Вы можете самостоятельно добавлять или удалять фразы вызова оценки. Для этого в проекте Code в файле main.sc добавьте необходимую фразу через тег q!:. Например:

    state: Каталог
        q!: оценить
        q!: мне нравится

Также при добавлении фраз вызова оценки вы можете использовать Паттерны, например:

        q!: * оцен* *

Звездочка, отделенная пробелом, перед и после слова означает любое слово или ничего. Звездочка, не отделенная пробелом, в конце слова означает, что у слова может быть любое окончание.

Пример выше подходит для вызова оценки приложения с помощью фраз: «хочу оценить», «поставить оценку», «оценка приложения» и т. д.