bind

Функция bind предназначена для установки обработчиков.

подсказка

Обработчики — особые функции, которые вызываются на различных этапах обработки запроса или при возникновении внештатных ситуаций в диалоге.

Принцип работы

Рассмотрим, как установить обработчик:

Создайте функцию, которая как аргумент принимает объект $context — текущий контекст обработки запроса. В теле функции производятся любые действия, необходимые по сценарию.
При установке функции через bind:
- Укажите тип обработчика. Тип определяет ситуацию, в которой обработчик будет вызван.
- Укажите путь, к которому будет привязан обработчик в иерархии стейтов сценария. По умолчанию это корневой путь /.
  
  подсказка
  Если контекст бота находится в стейте, путь к которому начинается так же, как путь обработчика, то функция будет вызываться во всех случаях, разрешенных типом обработчика.
  При привязке к корневому пути / обработчик будет вызван при нахождении в любом стейте сценария.
- Укажите, нужно ли выполнять обработчик при переключении контекста. Если диалог перешел в стейт в результате того, что другой бот передал контекст в текущего бота, по умолчанию выполняются все типы обработчиков, кроме preMatch.
Поместите обработчик и вызов функции bind в отдельный файл с расширением .js, который импортируется в сценарий при помощи тега require, или в тело тега init.

Синтаксис

Функция bind принимает аргументы:

Аргумент	Тип	Описание	Обязательный
`type`	Строка	Тип обработчика.	Да
`handler`	Функция	Функция-обработчик.	Да
`path`	Строка	Абсолютный путь для привязки обработчика.	Нет
`name`	Строка	Имя обработчика.	Нет
`allowedInContextSwitch`	Логический	Выполнять обработчик, если диалог перешел в стейт в результате того, что другой бот передал контекст в текущего бота. Аргумент применяется только при первом вызове обработчиков после переключения контекста. По умолчанию для `preMatch` — `false`, для всех остальных обработчиков — `true`.	Нет

Рассмотрим пример вызова функции bind:

bind(
    "postProcess",
    function($context) {
        $context.session.lastState = $context.currentState;
    },
    "/Start",
    "Remember last state",
    false
);

Тип обработчика postProcess, переданный в качестве первого аргумента, означает, что он будет вызываться после основного цикла обработки запроса.
Функция, переданная как второй аргумент, задает целевое действие. В данном случае оно заключается в том, что путь к текущему стейту сохраняется в $session как предыдущий стейт.
Обработчик привязывается к пути /Start. Он будет вызываться в стейте /Start и во всех его дочерних стейтах — например, /Start/Hello, /Start/Hello/1 и т. д.
Имя обработчика — Remember last state.
Путь к текущему стейту не будет сохранен, если диалог перешел в стейт в результате того, что другой бот передал контекст в текущего бота.

Обработчики этапов обработки запроса

Обработчики следующих типов вызываются в ходе общего цикла обработки запроса:

preMatch
selectNLUResult
preProcess
postProcess

preMatch

Обработчик preMatch вызывается перед классификацией запроса. Ниже перечислены основные случаи его использования.

Принудительное изменение текущего стейта

В следующем примере при обработке запроса в стейте /Hello контекст будет переведен в стейт /Start. Это может быть полезно при переименовании стейтов для обратной совместимости версий сценария.

bind(
    "preMatch",
    function($context) {
        $context.temp.targetState = "/Start";
    },
    "/Hello"
);

Изменение текста запроса

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

bind("preMatch", function($context) {
    if ($context.client.hasActiveAuthorization) {
        $context.request.query += " (клиент авторизован)";
    }
});

предупреждение

Чтобы иметь возможность изменить текст запроса, задайте специальную настройку в конфигурационном файле chatbot.yaml:

nlp:
  modifyRequestInPreMatch: true

selectNLUResult

В одном сценарии возможно совместное использование нескольких типов правил активации. По умолчанию правила срабатывают с заранее заданными приоритетами: сначала паттерны, затем интенты.

Если такое поведение нежелательно, с помощью обработчика selectNLUResult можно его изменить. Он вызывается после классификации запроса и переопределяет механизм выбора нужного правила.

подсказка

Подробнее об обработчике selectNLUResult

preProcess

Обработчик preProcess вызывается после классификации запроса и определения целевого стейта, но перед выполнением действий, заданных в стейте. Например, он может быть использован для инициализации каких-либо данных или проверки предварительных условий для перехода в другие стейты.

В следующем примере предполагается, что в $session хранится параметр громкости устройства. Если громкость не задана, для нее устанавливается значение по умолчанию.

var DEFAULT_VOLUME = 40;

bind("preProcess", function($context) {
    if (!$context.session.volume) {
        $context.session.volume = DEFAULT_VOLUME;
    }
});

postProcess

Обработчик postProcess выполняется после завершения обработки запроса и может быть использован, например, для добавления в ответ дополнительных полей или записи статистических данных.

В приведенном примере обработчик добавляет во все ответы бота в канале Telegram поле, которое указывает, что к ним применена разметка Markdown.

bind("postProcess", function($context) {
    if ($context.response.channelType === "telegram") {
        $context.response.replies = $context.response.replies.map(function(reply) {
            if (reply.type === "text") {
                reply.markup = "markdown";
            }
            return reply;
        });
    }
});

подсказка

Из postProcess также возможно использовать метод $reactions.transition для перехода обратно в сценарий и принудительного продолжения обработки запроса.

Обработчики ошибок

Обработчики ошибок служат для обработки внештатных ситуаций в ходе работы бота:

onScriptError
onDialogError
onAnyError

подсказка

В теле обработчиков ошибок в поле $context.exception.message содержатся сообщения возникших ошибок.

onScriptError

Обработчик onScriptError вызывается при возникновении необработанного исключения в коде на JavaScript. Также его можно использовать для настройки поведения при генерации собственных исключений при помощи инструкции throw.

Рассмотрим следующий пример использования обработчика для записи сообщения об ошибке в отчет по сессиям через метод $analytics.setSessionData.

bind("onScriptError", function($context) {
    $analytics.setSessionData("Ошибка", $context.exception.message);
});

подсказка

После onScriptError может быть выполнен обработчик postProcess, а также переход в другой стейт при помощи $reactions.transition.

onDialogError

Обработчик onDialogError вызывается при возникновении ошибок сценария, не связанных с исключениями на JavaScript. Примеры таких ошибок:

Ошибка	Сообщение об ошибке
Для запроса клиента не определен целевой стейт.	No target state was determined for query
Сделан переход в несуществующий стейт.	State not found for path <path>
Бот попал в бесконечный цикл переходов по стейтам.	Infinite loop was detected for state <state> in postProcess transition

bind("onDialogError", function($context) {
    if ($context.exception.message
            && $context.exception.message === "No target state was determined for query") {
        $reactions.answer(
            "Для запроса «" + $context.request.query + "» не найден стейт!"
        );
    }
});

подсказка

После onDialogError может быть выполнен обработчик postProcess, а также переход в другой стейт при помощи $reactions.transition.

onAnyError

Обработчик onAnyError выполняется в нескольких случаях:

В коде сценария возникло исключение, для которого не предусмотрен обработчик onScriptError.
В ходе диалога возникла ошибка, для которой не предусмотрен обработчик onDialogError.
Возникла непредвиденная ошибка сервера, не связанная с логикой сценария.

bind("onAnyError", function($context) {
    var answers = [
        "Что-то пошло не так.",
        "Произошла ошибка. Пожалуйста, повторите запрос позже.",
        "Все сломалось. Попробуйте еще раз."
    ];
    var randomAnswer = answers[$reactions.random(answers.length)];
    $reactions.answer(randomAnswer);
});

предупреждение

После onAnyError обработчик postProcess не выполняется. Переход в другой стейт при помощи $reactions.transition невозможен.

Принцип работы​

Синтаксис​

Обработчики этапов обработки запроса​

preMatch​

Принудительное изменение текущего стейта​

Изменение текста запроса​

selectNLUResult​

preProcess​

postProcess​

Обработчики ошибок​

onScriptError​

onDialogError​

onAnyError​

Принцип работы

Синтаксис

Обработчики этапов обработки запроса

preMatch

Принудительное изменение текущего стейта

Изменение текста запроса

selectNLUResult

preProcess

postProcess

Обработчики ошибок

onScriptError

onDialogError

onAnyError