Перейти к основному контенту

Плагины

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

Плагины МетаботMetabot –— это JavaScript библиотеки, скрипты которых доступны для повторного использования в различных скриптах ботов.

Существует два вида плагинов:

  • плагиныПлагины бизнеса
—
Этоэто собственные JavaScript библиотеки, созданные вами и доступные в любом боте вашего бизнеса. Другим бизнесам эти библиотеки не доступны;

  • общиеОбщие (предопределенные) плагины
—
Этоэто JavaScript библиотеки доступные в любом бизнесе, любого бота. Разработкой таких библиотек занимается команда Метабот.
Metabot.

Другими словами, Вывы можете создать свои собственные JavaScript библиотеки или использовать предопределенные, готовые библиотеки.

Список общих плагинов

  • Наименование Подключение Пример Дополнительно
moment 
Подключается только через require() 

let moment = require('moment');



    moment-with-locales

    Подключается только через require() 

    let moment = require('moment-with-locales');


    Это OpenSource библиотека для работы с датами, https://momentjs.com/

    Версия библиотеки moment.js: 2.29.3


      Common.Bot.Commands;Commands

      Подключаетсяrequire() через requre или через| snippet() 

      require('Common.Bot.Commands'); или| snippet('Common.Bot.Commands');



      Если для вашей ситуации доступно подключение через require – то это более предпочтительный с точки зрения производительности вариант, используйте именно его. Если подключение с помощью require() недоступно или не приемлемо, то используйте подключение через snippet().


      На данный момент подключение собственных библиотек бизнеса доступно только через snippet().


      Интерфейс и логика настройки плагинов


      image.png

      Интерфейс плагинов на платформе МетаботMetabot24 состоит из двух уровней:
      • Плагины
      —
      Вв данном разделе настраивается общее описание библиотеки и пространство имен для скриптов вложенных в плагин. Название плагина похоже на название директории в которой хранится Вашаваша библиотека.
      библиотека;

      image.png

      • Скрипты плагинов
      —
      Этоэто сами скрипты которые вы можете использовать в своих ботах. Название соответствует названию файла к которому вы обращаетесь.

      image.png

      Полное имя библиотеки «клеится» из трех составляющих:
      • уровеньУровень доступа (Common или Business);
      • названиеНазвание плагина;
      • названиеНазвание скрипта плагина.

      При подключении библиотеки «составляющие» разделяются точкой, а при обращении к методам библиотеки из JS «составляющие клеятся» вместе, т.е. пишутся слитно, без точки.

      Сниппеты

      Перед тем как разобрать пример использования собственного плагина, необходимо понять принцип действий сниппетов. Работа сниппетов аналогична макросам, т.е. это просто текст, который подставляется вместо указанного макроса.

      Доступны два варианта подключения сниппета:


      snippet("your_snippet_name")
или
[[:your_snippet_name:]]

      Оба варианта работают как макрос, т.е.указанный вариант обьявления сниппета в JavaScript коде будет заменен на код, который указан в скрипте плагина, к которому мы обращаемся.

      В содержимом скрипта плагина можно указывать любой JavaScript код, главное чтобы ваш код, в котором выполняется макроподстановка сниппета был валиден после замены

      Рассмотрим сначала простой пример указания значения переменной, вместо JavaScript.
      Вместо JavaScript кода сниппета можно указать любую комбинацию, напримернапример:

      let text = snippet("mysnippet");

      А в самом сниппете указать любое значение (число, текст, булево и т.п.), например, если в
      сниппете мы указали кодкод:

      "Hello World!"

      то,То, запускаемый JS интерпретатором код примет следующий вид:

      let text = "Hello World!"

      Обратите внимание, что символ точка с запятой является частью определения макроса, и может
      указываться после snippet, а может не указываться. Если вам необходимо чтобы «конечный исходный
      код», после замены содержал точку с запятой, то укажите ее в самом JavaScript коде сниппета (скрипта
      плагина), т.е.:

      "Hello World!";

      тогда,Тогда, запускаемый JS интерпритатором код примет следующий вид:

      let text = "Hello World!";

      Сниппет идентичен макроподстановке. Макроподстановка выполняется до запуска скрипта и не является командой интерпретатора JavaScript, поэтому если вы закомментируете объявление сниппета, то он все равно будет подставлен в исходный код ! Чтобы закомментировать сниппет нужно закомментировать его и нарушить синтаксис его обьявления,объявления, чтобы система не нашла макрос со сниппетом и не выполнила макроподстановку, например написать:
      //s!nippet("your_snippet_name")      .

      Пример 1№1: Общий плагин (скрипт общего плагина).

      Полное имя библиотеки «клеится» из трех составляющих:

      • Общий плагин (Common);
      • Название плагина «Bot»;
      • Скрипт «Commands».

      Подключается такая библиотеки с помощью кода


      кода: 
      require('Common.Bot.Commands');

      После подключения, в JavaScript автоматически будет доступна переменная


      CommonBotCommands. 
      CommonBotCommands


      К методам CommonBotCommands можно обращаться, например для отправки сообщения

      в мессенджер из JavaScript:

      CommonBotCommands.SendText('Текст отправленный из V8');

      Полный список команд каждой библиотеки выходит за рамки данной документации и может

      постоянно дополняться, для этого смотрите отдельную документацию

      дополняться.

      В данном примере речь идет именно об общей библиотеке (Common), внутри которой уже описан специальный объект, который можно использовать с помощью методов, чтобы добиться такого же варианта использования вы должны самостоятельно описать свой объект на JavaScript. Оформление в виде JavaScript обьекта при создании вашего собственного плагана бизнеса не является обязательным, за счет того что ваши скрипты будут подключаться в виде сниппетов. Вы можете просто описать любые переменные и функции в вашей библиотеке и обращаться к ним по имени.

      ДЛЯДля БИБЛИОТЕКбиблиотек УРОВНЯуровня БИЗНЕСАбизнеса автоматически создаваемые переменные-объекты не доступны (или доступны только в тех библиотеках которые для вас создаст команда Метабот);Metabot).

      Отметим, что существуют другие библиотеки, например, такие как moment.js. Подключение и

      использование таких библиотек отличается от использования библиотек созданных на платформе.
      Например, для moment.js, не нужно указывать три «состявляющие» названия скрипта (уровень доступа,
      плагин и скрипт). Для moment.js мы явно объявляем переменную и «экспортируем в нее библиотеку»

      : 
      let moment = require('moment');

      Подключение различных библиотек может отличаться и зависит от реализации самой

      библиотеки. Но, в основном как подключать и будет ли доступна автоматически переменная-объект
      понятно из названия библиотеки (если при подключении нет указания уровня доступа, то скорее всего
      это OpenSource библиотека)


      .

      Если вы подключаете к одному скрипту несколько сниппетов, то переменные обьявленые внутри каждого из сниппетов не должны пересекаться между собой по имени, а также переменные объявленные в сниппете и вашем скрипте, к которому вы подключаете сниппет не должны пересекаться;пересекаться.


      Пример 2№2: Плагин бизнеса (скрипт вашего плагина).

      Создадим новый плагин для формирования текста, который мы будет отправлять

      пользователю с помощью атрибутов бота.

      image.pngimage.png

      image.pngЗаполним все необходимые поля.


      image.png

      Далее, перейдем в скрипты плагинаплагина.

      и

      image.png

      И создадим новый скрипт.


      image.png

      Заполним в открывшемся окне необходимые поля.

      image.png

      image.png

      image.pngimage.png

      Укажем в исходном коде скрипта:

      const greetMsg = 'Привет, ' + lead.getData('name') + '!';
memory.setAttr("greet", greetMsg);

      Здесь мы сохраняем текст приветствия в memory (временном атрибуте бота).

      Полное имя библиотеки «клеится» из трех составляющих:

      • Плагин бизнеса (Business);
      • Название плагина «Notifications»;
      • Скрипт «HelloLead».

      Подключается с помощью кода


      кода: 
      snippet('Business.Notifications.HelloLead');
      image.png

      image.png

      Для проверки работы плагина, в скрипт бота необходимо добавить две команды:
      • Выполнить JavaScript,JavaScript с— следующимздесь содержимым:мы подключаем сниппет, для заполнения атрибута(макропеременной) во временной памяти бота:

      snippet('Business.Notifications.HelloLead');

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

      • Отправить текст,текст c— следующимв содержимым:содержимом использована макропеременная, текст который будет отправлен в
        мессенджер:

      {{ &$greet }}

      В содержимом использована макропеременная, текст который будет отправлен в
      мессенджер.
      image.png

      image.png

      Результат работы скрипта в телеграм:

      image.png

      Пример 3№3: Использование общего плагина в плагине бизнеса.

      бизнеса

      Модифицируем пример 2 так, чтобы текст отправлялся не с помощью команды Отправить

      текст,текст, а прям из JS кода плагина.

      image.pngimage.png

      В исходном коде скрипта укажем:

      require('Common.Bot.Commands');
const greetMsg = 'Привет, ' + lead.getData('name') + '!';
CommonBotCommands.sendText(greetMsg);

      image.png

      Удалим команду Отправить текст,текст, команду Выполнить JavaScript оставляем без изменений

      image.pngизменений.

      image.png

      Результат работы данного скрипта будет идентичным примеру 2:

      image.png