Типы Action-ов в @MenuBuilderBot
MegaHubTelegram
Конструктор @MenuBuilderBot позволяет настроить любую кнопку в вашем боте на выполнение практически неограниченного количества действий при её нажатии пользователем.
Функционал Action-ов обширен и гибок в своем применении — поэтому описание всех нюансов работы с ним — это огромный и довольно нудный документ, с которым, тем не менее, необходимо ознакомиться. Если это первый раз когда вы знакомитесь с ним — просто прочтите его весь целиком. В дальнейшем, для уточнения деталей, можно обращаться к его отдельным частям как к справочнику. В этом же документе мы подробно поговорим о типах Action-ов.
📜 Перевод представленных материалов на ваш родной язык может быть автоматически осуществлен при помощи переводчика Google. Перейдите по ссылке и выберите нужный язык в заголовке:
https://translate.googleusercontent.com/translate_c?depth=1&sl=ru&tl=es&u=https://telegra.ph/Actions-Types-in-MenuBuilderBot-RU-03-01
⬛ Содержание
⬛ Action Чисел
«Action Чисел» позволяет проводить операции с данными переменных. Вычитать, прибавлять и проводить прочие математические действия. Для более сложных вычислений применяются «Выражения» (Руководство по Выражениям смотри в разделе «Дополнительная Информация» в конце документа).
Как мы уже обозначили выше Action-ы добавляются в кнопки и выполняются по порядку (от верхнего к нижнему) при её нажатии.
Выберите «Action Чисел»
Далее укажите переменную с которой будет работать создаваемый вами Action.
Выберите один из Типов Операций.
Для удобства работы с данными при срабатывании Actioin-а, вам будет предложено использовать один из двух видов действий:
1. «Изменить Значение» - при этом указанное вами значение будет добавлено (или вычтено при отрицательном значении) к существующему значению переменной.
2. «Задать Значение» (Установить) в этом случае значение переменной будет установлено равным указанному вами значению, вне зависимости от ее исходного значения (существовавшие в ней до этого данные при этом будут затерты).
В качестве указанного значения могут служить следующие данные:
1. Обычное чисто (Любое натуральное число, а также десятичное или отрицательное)
2. Макрос переменной (другой или этой же). Для этого в боте должен быть приобретен соответствующий плагин — смотри раздел «Дополнительная Информация»
3. Выражение, содержащее Числа и (или) макросы. Для этого в боте должен быть приобретен соответствующий плагин — смотри раздел «Дополнительная Информация»
4. Макрос или Выражение, содержащее Макросы и Функции «Времени» Ссылка на руководство по переменным времени будет в разделе «Дополнительная Информация» в конце документа.
В этом режиме Action Чисел может работать с переменными Даты и Времени. при помощи выражений или функций этим переменным могут присваиваться значения, в том числе можно и "добавлять" время к уже установленному в переменной.
Например выражение:
вычислит и установит дату на 3 месяца больше существующей в переменной tvariable.
Подробнее о переменных Даты и Времени читай в руководстве.
После этого (если в вашем боте приобретен плагин «Условия для Кнопок»), вам будет предложено ввести условие при котором сработает данный Action. Также можно задать соответствующие сообщения для случая невыполнения данного условия. «Условием» всегда служит «Выражение». Подробнее о «Выражениях» читай в соответствующем руководстве.
Если введенное тут индивидуальное условие Action-а не выполняется - это не ошибка, просто данный конкретный Action не сработает. Цепочка выполнения Action-ов не будет прервана и продолжит выполнение дальше.
Само Условие и его сообщения вводить не обязательно — нажмите «Задать Пустым» если они вам не нужны в данном случае.
Далее вам будет предложено ввести сообщение для случая если Условие не выполнено. Сообщение об успехе выполнения вводить не обязательно — нажмите «Задать Пустым» если оно вам не нужно в данном случае.
Далее можно ввести сообщение которое будет показано юзеру в случае успешного выполнения Action-а.
В данном сообщении доступны специальные макросы для показа изменений которые Action вносит в переменную. Особенно полезно, при использовании случайных или непостоянных сумм начисления. Для этого используется комбинированный макрос:
где «varname» - это имя переменной, которая была изменена и сумму изменения которой вы хотите отобразить.
Обращаем ваше внимание что Данные макросы можно использовать и в «Выражениях» самого Action-а.
Приведем пример (хоть использование выражений и не является темой данного руководства).
Скажем у вас есть 2 Action-а:
Action 1. balance = {-1 * randi(10, 200)}
Action 2. invest = {1 * %balance_v%}
в результате в invest будет добавлено столько, НА СКОЛЬКО изменился balance.
Также данные макросы можно использовать и в ОБЩИХ сообщениях об успехе или неудаче срабатывания всей цепочки Action-ов.
Сообщение об успехе выполнения вводить не обязательно — нажмите «Задать Пустым» если оно вам не нужно в данном случае.
После этого новый Action будет создан и его данные появятся в качестве сообщения с инлайн кнопками управления в чате с ботом.
⬛ Action Условий
«Action Условий», в отличие от индивидуальных условий каждого Action-а, позволяет прерывать дальнейшее выполнение всей цепочки Action-ов, если его условие не соблюдено.
Обратите внимание, что от того в каком именно месте цепочки Action-ов размещен «Action Условия», будет зависеть и момент её возможного прерывания. Все предыдущие Action-ы будут выполнены, все последующие — нет.
Создание данного Action-а происходит аналогично - вас попросят добавить само Условие которое нужно проверить. «Условием», как и в предыдущем случае, всегда служит «Выражение».
Затем необходимо ввести сообщение которое будет показано в случае если Условие Action-а не выполнено (Сообщение об ошибке). Это сообщение вводить его не обязательно — нажмите «Задать Пустым» если оно вам не нужно в данном случае.
Иногда, при добавлении Условия а этот Action возникают затруднения с пониманием механики его работы, что не позволяет четко предсказать в какой именно момент сработает данный Action. В "Руководстве по Условиям" есть небольшой раздел, который возможно облегчит понимание, кроме того там можно узнать все нюансы работы с Условиями.
Кнопка в которую добавляются Action-ы, в подавляющем большинстве случаев, будет содержать свои собственные сообщения — ту информацию ради которой кнопка обычно и создается. В связи с этим, необходимо определить поведение самой кнопки в случае невыполнения условия.
Тут у вас будет два варианта:
1. Можно позволить кнопке показать юзеру добавленные в нее сообщения — не взирая на невыполнение Условия.
2. Или запретить ей показывать свои сообщения в случае невыполнения Условия.
Для каждого из вариантов найдется масса применений.
⬛ Action Рефералов
«Action Рефералов», предназначен для начислений Реферальным Родителям юзера нажавшего кнопку с данным Action-ом. Начисление (вознаграждений) происходит на указанную вами переменную в процентах от указанного вами числа (так же можно использовать макрос переменной если у вас приобретен соответствующий плагин - о плагинах смотри «Дополнительная информация» в конце документа). Проценты можно указать для каждого уровня реферальной системы. По умолчанию доступен один уровень, но при помощи расширений этот показатель можно увеличивать до нужных размеров создавая многоуровневые реферальные системы.
Создание данного Action-а происходит аналогично двум предыдущим.
Вы указываете переменную, в которую для каждого уровня должно быть начислено вознаграждение, затем само число - процент от которого должен быть начислен вверх по реферальной системе.
Обращаем ваше внимание на то что само указанное число указанное вами как «точка отсчёта» никому начислено не будет - оно только служит точкой отсчета для начисления.
Следующим шагом вам предложат указать количество вознаграждения для каждого уровня.
Вознаграждение указывается в столбик, для каждого уровня с новой строки. каждое число это количество процентов от заданного вами исходного числа. Чтобы распределение вознаграждения имело естественный вид — размер вознаграждения должен уменьшаться с каждым новым уровнем. Хотя в отдельных случаях могут быть и исключения.
Например:
20
10
5
Выше предствалена настройка для трёхуровневой реферальной системы где вознаграждение 20%,10% и 5% для каждого уровня соответственно.
На картинке ниже насторйки для начислений 10%, 1%, 0.1%. Обратите внимание что для отделения десятичных значений используется "." (точка):
То количество реферальных уровней для которого указывается начисление может быть меньше чем фактические количество реферальных уровней в вашей системе. Однако первое число всегда будет соответствовать первому уровню, второе - второму и так далее.
Обратите внимание что количество "Срабатываний" для такого Action-а считается по количеству фактических действий начисления и потому на прямую связана с количеством реферальных родителей юзера для которого происходит начисление.
Если в вашем боте приобретен плагин «Условия для Кнопок», далее вам будет предложено ввести условие при котором сработает данный Action. Также можно задать соответствующие сообщения для случая невыполнения данного условия. Напоминаем, что «Условием» всегда служит «Выражение». Подробнее о «Выражениях» читай в соответствующем руководстве.
Если введенное тут индивидуальное условие Action-а не выполняется - это не ошибка, просто данный конкретный Action не сработает. Цепочка выполнения Action-ов не будет прервана и продолжит выполнение дальше.
Само Условие и его сообщения вводить не обязательно — нажмите «Задать Пустым» если они вам не нужны в данном случае.
⬛ Action Инициализации
«Action Инициализации» позволяет задать первоначальное значение любой переменной. Переменная при этом должна быть или новой и ни разу не использованной юзером, либо пустой - очищенной до первоначального состояния.
ИНФО: Например можно использовать для Переменной Времени. Дело в том что новая переменная времени всегда будет показывать текущее время, что иногда приводит к непредсказуемым результатам в выражениях. Так вот, чтобы задать какое-либо конкретное значение этой переменной — инициализировать - как раз и используется данная функция. Кроме того её можно использовать для первоначальных начислений какой-либо суммы юзеру. При добавлении в кнопку, данный Action сработает только один раз и произведет только одно начисление в переменную - после чего, для данного юзера, он больше срабатывать не будет.
1. При создании данного Action-а, сначала вас попросят указать переменную, которую он в дальнейшем будет "инициализировать" - то есть одноразово изменять.
2. Затем естественно нужно указать значение которое фактически будет присвоено переменной.
3. После этого вы сможете указать сообщение которое будет показано юзеру при условии что данный action сработал. Указывать сообщение не обязательно, можно оставить его пустым если вы не хотите информировать юзера или давать ему знать что какие-то данные были изменены.
На этом создание данного экшена завершено.
Нюансы работы с Action-ом Инициализации.
● Данный Action с работает только если переменная которую он должен изменить абсолютно пуста. То есть она либо только что создана и в ней по этой причине нет никакого значения, либо очищена командами типа
/varclearall и /vardel и пуста по этой причине (подробнее об этих командах смотри в руководстве по переменным). После очистки переменных данными командами Action инициализации снова сработает.
● Для цифровых переменных, ноль это тоже значение и Action не сработает. Так что заставить Action сработать присвоив 0 (ноль) цифровой переменной - не получится.
● Данный Action работает с Цифровыми, Текстовыми переменными и переменными Времени. С Глобальными НЕ работает.
⬛ Action Команд
Данный Action позволяет обращаться к любой кнопке по её команде, со всеми соответствующими последствиями. В том числе и переносить юзера в нужное меню - если команда самой кнопки настроена соответствующим образом. Подробнее о работе с командами можно почитать в руководстве по командам.
Может использоваться для нелинейных переходов по меню. В том числе и при необходимости создать у юзеров впечатление динамически изменяющегося меню, когда при нажатии одной и той же кнопки юзер получает разный результат. Данная механика описана для inline кнопок в "LifeHack #4" (смотрите данный гайд по ссылке), однако теперь может использоваться и для обычных кнопок.
1. При создании данного Action-а сначала необходимо ввести ту команду которую Action должен отправлять. Данная команда принадлежит той кнопке к функционалу которой вы хотите обратиться при помощи данного Action-а.
ИНФО: Обратите внимание что если вам нужно перенести и юзера в меню кнопки к которой вы обращаетесь, то данное действие настраивается внутри самой кнопки при добавлении команды. То есть кнопка сама определяет нужно ли переносить туда юзера. Action - только обращается к данной кнопке по её команде.
2. После добавления команды, вам будет предложено ввести Условие для срабатывания данного Action-а. Это действие не обязательно и зависит от конкретной ситуации.
3. Как и во всех предыдущих случаях, после добавления Условия, вам будет предложено ввести сообщение на случай если Условие не выполнено - сообщение об ошибке.
4.1. Далее вам нужно определить, будет ли переход по команде прерывать дальнейшее выполнение оставшихся Action-ов ниже по списку. По умолчанию выполнение будет прервано. Если поменять эту настройку и позволить выполнение, то после перехода и окончания всех возможных действий в кнопке назначения, бот вернется к выполнению оставшихся Action-ов.
4.2. Кроме прерывания выполнения нижеследующих Action-ов, на этом же этапе можно указать боту стоит ли после выполнения всех действий связанных с переходом по команде показать еще и сообщение самой кнопки из которой осуществляется переход.
На этом создание «Action-а Команд» завершено.
Нюансы работы с Action-ом команд:
Максимальное количество последовательных автоматических переходов по команде — 5 (пять).
⬛ Action Транзакций
Данный Action позволяет вашим юзерам вносить изменения увеличивая либо уменьшая значения переменных друг у друга. В узком смысле, Action позволит юзерам совершать переводы неких цифровых активов внутри бота. Простыми словами - переводить друг другу денежные средства либо токены которые есть, например, у них на балансе. Однако денежные переводы это лишь малая часть спектра возможных способов применения данного функционала.
При создании функции с участием данного Action-а юзеру можно предоставить выбор суммы, а можно её жёстко задать. Будут, при этом, средства добавлены или отняты - определяет админ при настройке данного Action-а. Юзер НЕ может выбирать знак (+/-) того числа которое он отправляет.
ИНФО: Независимо от того какое число он укажет для транзакции, знак будет определяться админом при составлении данного Action-а, а отправленное юзером число, положительное или отрицательное всегда будет превращено в положительное прежде чем быть добавленным в формулу заданную админом или обработанным ею.
Юзеру можно предоставить выбор адресата, а можно также его жестко задать. Всё будет зависеть от конкретных обстоятельств и задач.
1. При создании, первым делом, необходимо указать переменную которую будет изменять данные Action. Это переменная на стороне адресата, то есть вы указываете переменную получателя которую нужно будет изменить.
2. После этого бот попросит вас указать сумму для изменения.
В зависимости от ваших задач вы можете:
● жёстко задать эту сумму - для этого просто отправьте боту нужное число.
● указать макрос цифровой переменной в которой будет содержаться сумма и откуда эта сумма должна быть взята. Причём данная переменная может быть как глобальной так и индивидуальной. В случае индивидуальной переменной вы можете заранее создать форму и при помощи ввода переменной позволить юзеру самому задать значение данной переменной. Таким образом user сможет сам выбрать сумму для перевода.
● вы можете сделать переменную положительной либо отрицательной - для этого перед суммой (либо перед макросом цифровой переменной) поставьте знак минус. В этом случае сумма будет отнята у адресата.
3. Далее, бот попросит вас указать идентификатор юзера, переменную которого нужно изменить. Данные идентификатор можно указать жёстко - просто отправив его боту. Однако в подавляющем большинстве случаев данный идентификатор лучше задавать через макрос конкретной текстовой переменной.
ИНФО: Это позволит как вам самим с легкостью изменять это значение так и дать юзеру возможность, изменяя данную переменную, выбрать кому он будет отправлять свои средства. Для этого (так же как и в предыдущем случае), заранее создается Форма Обратной Связи в которой user, при помощи «Ввода Переменной», задает значение этой переменной, тем самым, самостоятельно определяя кому он отправляет свои средства.
Идентификатор пользователя это его Telegram ID или Menu Builder UserCode. Несмотря на то что оба они представлены цифрами, данная переменная должна быть текстовой или, в некоторых особых случаях, она может быть глобальной.
ВАЖНО: НЕ советуем использовать цифровые переменные для хранения идентификаторов, потому как данные идентификаторы могут начинаться с нуля, а цифровая переменная удалит его при сохранении - что приведёт к ошибке которую можно долго искать и не найти.
4. После этого бот попросит вас указать условия для срабатывания данного Action-а. Указывать или нет какие-либо условия зависит от вашей ситуации.
ИНФО: Данное условие понадобиться например для того чтобы проверить достаточно ли средств на балансе у отправителя для совершения перевода, при условии что отправленные средства вам в последствии нужно будет списать со счета отправителя. Соответственно если условие не выполняется то Action не сработает.
ВАЖНО: Как вы понимаете отдельный Action это лишь кирпичик в здании конечной функции. Поэтому за Action-ом Транзакции в очереди Action-ов может следовать Action Чисел, который и спишет с баланса отправленную сумму. Используйте тот же подход для списания, который вы установили для определения суммы перевода.
ВАЖНО: Обратите внимание на то, что если данный Action не сработал, то это никак не повлияет на остальные Action-ы в цепочке - то есть они продолжат выполняться как ни в чём ни бывало. По этой причине, если за Action-ом Транзакций следует Action Чисел, для списания с баланса, то схожее условие нужно добавить и для Action-а списания с баланса (или даже Action Условия, что полностью прервёт дальнейшее исполнение), иначе списание будет выполнено независимо от того произошёл сам перевод или нет.
5. После создания Условия бот предложит вам ввести сообщение которое будет показано юзеру если данное Условие не сработало. Другими словами сообщение об ошибке. В данном сообщении можно использовать макросы и эмодзи, но нельзя использовать markdown. Данное сообщение является необязательным и его можно не создавать.
6. Далее бот предложит вам ввести сообщение для юзера на случай успешного срабатывания данного Action-а. В данном сообщении можно использовать макросы и эмодзи но нельзя использовать markdown. Данное сообщение является необязательным и его тоже можно не создавать.
На этом создание «Action-а Транзакций» завершено.
⬛ Action Сообщений
Данный Action позволяет вам (или вашему юзеру), по нажатию кнопки, отправить сообщение заданному адресату. Мы намеренно не говорим "в группу" или "канал", потому что фактически Action позволяет отправлять сообщения любому у кого есть Telegram ID - то есть не только в группы и каналы, но и самим пользователям бота.
1. Бот попросит вас ввести само сообщение. В сообщении можно использовать любые доступные Макросы, Выражения и разметку Markdown.
ВАЖНО: Данное сообщение формируется во время отправки и поэтому, при использовании Макросов Переменных и Выражений, после пересылки будет содержать данные отправителя - независимо от того кому и где оно будет показано.
2. Далее необходимо ввести ID Чата, Группы или Пользователя бота - того места куда нужно отправить сообщение. Чаще всего это Группа или Канал (как настроить бот для работы в группе или канале), но можно отправлять сообщение и отдельному пользователю. для этого тут нужно указать его ID.
ИНФО: В этой настройке можно использовать Макросы Переменных и Выражения - таким образом адресата можно будет подставлять динамически, например заранее записав его ID в отдельную переменную - например при помощи Action-а Чисел или Текстов.
3. Данному Action-у можно так же задать Условие при котором он будет выполнен.
4. Далее можно ввести сообщение которое будет показано в случае если Условие не верно.
На этом создание «Action-а Сообщений» завершено.
⬛ Action Текстов
Данный Action позволяет вам присваивать значения Текстовым переменным, по нажатию кнопки юзером бота.
(Функционал данного Action-а возможно будет расширен в будущем)
1. На первом шаге нужно указать Текстовую Переменную значение которой нужно установить. Бот предложит для выбора только Текстовые Переменные созданные в вашем боте.
2. Далее бот попросит вас указать значение - то есть текст - который будет присвоен выбранной ранее переменной. Максимальная длинна текста для 200 символов (как и для любой Текстовой Переменной).
3. Данному Action-у так же можно задать Условие при котором он будет выполнен.
4. Далее можно ввести сообщение которое будет показано в случае если Условие не верно.
На этом создание «Action-а Текстов» завершено.
ВАЖНО: «Action Текстов» потребляет 3 «Токена Функций» вместо одного, как остальные Action-ы. Работа с текстами генерирует больше нагрузки на серверную часть.
