README

Библиотека для создания навыков для голосового помощника Алисы от компании Яндекс.

Данная библиотека поддерживает сценарии (см. руководство ниже).

Установка

composer require jeyroik/extas-alice:1.*

Использование

Пример использования библиотеки смотрите в репозитории alice-extas-example

Реализация навыка

• Регистрируем навык в Яндекс.Диалогах (https://dialogs.yandex.ru/developer/).
• Получаем идентификатор навыка (skill_id).
• Добавялем запись о навыке в extas.json в секцию skills:

"skills": [
  {
    "id": "идентификатор навыка, полученный в Яндекс.Диалогах",
    "name": "алиас навыка, по нему будет организовываться связка со сценариями",
    "description": "описание навыка, нигде не используется, заполняется только для понимания"
  }
]

• Добавляем в extas.json шаги, которые потребуются для навыка:

"steps": [
  {
    "name": "Имя шага, по нему будут запускаться плагины (см. ниже)",
    "title": "Название шага, используется только для понимания",
    "description": "Описание шага, используется для понимания"
  }
]

• Добавляем в extas.json сценарии навыка:

"scenarios": [
  {
    "name": "Имя сценария, используется для запуска плагинов",
    "title": "Название сценария, используется для понимания",
    "description": "Описание сценария, используется для понимания",
    "skill_name": "алиас навыка - см. skills:name",
    "schema": {
      "message_1": [{
        "condition": "имя класса для проверки условия, оставить пустым для обязателнього запуска данной реакции",
        "step": "имя шага, см. steps:name"
      }],
      "message_x": [{
        "condition": "",
        "step": "demo.help"
      }, {
        "condition": "extas\\components\\yandex\\skills\\conditions\\ConditionTest",
        "step": "demo.test"
      }]
    }
  }
]

- В схеме доступны два варианта идентификаторов сообщения: 
    - N, где N - целое число, идентификатор сообщения (см. детали https://yandex.ru/dev/dialogs/alice/doc/protocol-docpage/ описание по message_id)
        - Пример: message_1, message_2
    - x - для реакции на все сообщения пользователя;
        - Пример: message_x

• При необходимости можно также заранее прописать карточки и кнопки (см. extas.json для примера).
• Устанавливаем навык: alice-extas# vendor/bin/extas i
• Запускаем навык: alice-extas# php -S 0.0.0.0:8080 -t resources
  • См. resources/index.php для примера запуска.

Использование сценария

• Сценарий состоит из реакций.
• Реакция состоит из проверки условий и имени шага.
• Шаг состоит из имени и описания.

Шаги можно установить предварительно.

Установка шагов

{
    "steps": [
        {
          "name": "demo.help",
          "title": "Помощь",
          "description": "Пользователь запросил помощь"
        },
        {
          "name": "demo.start",
          "title": "Начало использования",
          "description": "На этом шаге приветствуем пользователя"
        }
      ]
}

Как видно, шаги не зависят от сценария и могут переиспользоваться. По каждому шагу запускается следующие стадии (события):

• step.<name шага>
• <name сценария>.step.<name шага>
• <name навыка>.<name сценария>.step.<name шага>

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

Установка сценария

"scenarios": [
    {
      "name": "demo",
      "title": "Демонстрационный сценарий",
      "description": "Это демонстрационный сценарий",
      "skill_name": "test",
      "schema": {
        "message_1": [{
          "condition": "",
          "step": "demo.start"
        }],
        "message_x": [{
          "condition": "",
          "step": "demo.help"
        }]
      }
    }
  ]

Схема сценария может содержать следующие секции:

• message_N, где N - любое целое число, представляющее идентификатор сообщения (см. документацию по навыкам). Данная секция содержит реакции на конкретное по порядку сообщение.
• message_x - данная секция содержит реакции для вариативных по порядку сообщений.

Каждая реакция состоит из

• condition - проверка условия. Если данная реакция должна применяться всегда, поле оставляется пустым, в противном случае здесь указывается имя класса. Класс реакции должен реализовывать метод __invoke(IAliceCall $call) и возвращать bool (true или false). Если true, то будет запущен соответствующий реакции шаг.
• step - имя шага, который нужно запустить, если условия подходят.