Skip to content
Yandex.Alice Extas package
PHP
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
.gitignore
README.md
composer.json
extas.json

README.md

alice-extas

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

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

Установка

composer require jeyroik/alice-extas:*

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

Пример использования библиотеки смотрите в репозитории 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 - имя шага, который нужно запустить, если условия подходят.
You can’t perform that action at this time.