Данные приложения
Переменные
Переменная — именованное значение, которое приложение помнит о человеке: имя из поля ввода, выбранный товар, ответ внешнего сервиса. Переменные хранятся у каждого пользователя приложения свои: что ввёл один человек, другой не увидит.
Переменные не нужно заводить заранее. Достаточно указать имя там, куда записывается значение, — в поле «Переменная» у элемента или блока. Конструктор запоминает имена из схемы и подсказывает их при вводе.
Откуда берутся значения:
| Источник | Что записывает |
|---|---|
| Поля ввода | То, что человек ввёл или выбрал, — в переменную из поля «Переменная» |
| «Записи списка» и другие элементы, где выбирают строку | Идентификатор выбранной строки — в переменную из настроек элемента |
| «HTTP-запрос» | Ответ целиком, код ответа и отдельные значения из ответа |
| «Найти запись» | Колонки найденной записи |
| «Добавить запись», «Форма записи» | Идентификатор новой записи |
| «JavaScript», код приложения, «HTML-код» | Переменные, которые разрешено писать коду, — см. Код в приложении |
Ещё несколько переменных приложение заполняет само при запуске. Записать в них что-то своё нельзя:
| Переменная | Что в ней |
|---|---|
launchSource |
Откуда открыто приложение: telegram, max, webchat, pwa или browser |
startParam |
Параметр ссылки запуска — то, что стоит после startapp. Как его передать — на странице Версии и публикация |
contactTags |
Теги контакта бота через запятую |
appTags |
Теги пользователя приложения через запятую |
Переменные человека видно в его карточке в разделе «Пользователи», там же их можно поправить. Ход переменных в предпросмотре показывает панель «Отладка».
Ограничения. Имя переменной — до 64 символов, значение — до 4096. У одного пользователя — до 500 переменных: новые сверх этого не записываются.
Подстановки
Значение переменной подставляется в текст двойными фигурными скобками: {{ имя }}. Подстановки работают в текстах и заголовках экранов, в подписях, в значениях полей по умолчанию, в адресе и теле HTTP-запроса, в значениях колонок и условиях отбора записей, в сообщениях бота.
Пример: поле ввода пишет имя в переменную name, а на следующем экране заголовок «Спасибо, {{ name }}!» превратится в «Спасибо, Анна!».
Если переменной нет, на её месте будет пусто. Подставляется только значение переменной: выражения и функции, которые работают в автоподстановках чат-бота, здесь не поддерживаются.
Совет
В полях конструктора, куда пишется значение, начните вводить имя — подсказка вставит подстановку целиком. В полях, куда записывается результат, подсказка вставляет голое имя переменной.
Данные контакта бота
Если приложение открыто из бота и человек этому боту писал, доступны поля его контакта:
| Подстановка | Что в ней |
|---|---|
{{ contact.id }} |
Номер контакта |
{{ contact.name }}, {{ contact.first_name }}, {{ contact.last_name }} |
Имя целиком, имя, фамилия |
{{ contact.username }} |
Ник в мессенджере |
{{ contact.phone }}, {{ contact.email }}, {{ contact.address }} |
Телефон, почта, адрес |
{{ contact.source }} |
Канал контакта |
{{ contact.created_at }} |
Когда контакт появился в боте |
{{ contact.start_message }} |
Первое сообщение боту |
{{ contact.telegram_id }}, {{ contact.max_id }} |
Идентификатор в Telegram и MAX |
Свои переменные контакта тоже читаются с приставкой: {{ contact.city }} — переменная city из карточки контакта.
Переменные приложения и переменные контакта бота — разные. Значение из поля приложения в контакт не попадает, а переменная контакта не видна в приложении без приставки contact.. Записать переменную в контакт может только код блока «JavaScript». У гостя из браузера контакта нет — поля contact. пусты.
Списки
Приложение хранит данные в списках проекта — тех же, с которыми работают чат-боты: Списки. Список, заполненный в приложении, виден в разделе «Списки» меню проекта, и наоборот. Чужой список — из другого проекта — приложение не откроет.
Приложение может заполнять поля типов «Текст», «Число», «Денежный», «Логический», «Дата» и «Дата и время». Поля «Файл», «Картинка», «ID контакта» и «ID бота» заполнить из приложения нельзя.
| Задача | Чем делать |
|---|---|
| Показать каталог, расписание, отзывы | Элемент «Записи списка» |
| Открыть одну запись на отдельном экране | Нажатие на запись кладёт её идентификатор в переменную (по умолчанию recordId), следующий экран показывает её элементом «Карточка записи» или раскладывает по переменным блоком «Найти запись» |
| Принять заявку или анкету | Элемент «Форма записи» или поля ввода плюс блок «Добавить запись» |
| Дать человеку поправить свою запись | «Форма записи» в режиме «Меняет запись» или блок «Изменить запись» |
| Удалить запись | Блок «Удалить запись» |
Отбор и сортировка
У «Записей списка» и блоков записей есть «Условия»: «Колонка», «Условие» и «Значение». Условия: «Равно», «Содержит», «Начинается с», «Заканчивается на», «Больше», «Меньше», «Пусто», «Заполнено». Условий — до 20.
В значение можно подставить переменную — тогда отбор зависит от того, что выбрал человек. Например, поле поиска пишет в query, а условие «Название» «Содержит» {{ query }} показывает подходящие записи.
«Сортировка» — колонка и направление «По убыванию» или «По возрастанию». Пусто — сначала новые записи.
«Сколько показывать» — столько записей загружается за один раз; с отметкой «Подгружать при прокрутке» следующие подгружаются, когда человек долистал до конца. За один раз приложение отдаёт не больше 50 записей.
Свои записи
Запись можно закрепить за человеком, который её создал: отметка «Запись принадлежит пользователю» у «Формы записи» или «Привязать запись к текущему пользователю» у блока «Добавить запись». Это работает и у гостя из браузера.
С отметкой «Только записи текущего пользователя» элемент или блок видит только записи этого человека — так делают «мои заявки», «мои заказы», избранное. У блоков «Изменить запись» и «Удалить запись» эта отметка включена по умолчанию: без неё человек мог бы подставить чужой идентификатор и изменить чужую запись.
Формы
Элемент «Форма записи» — короткий путь от экрана к записи: каждое поле формы — колонка списка, а отправка сразу создаёт или меняет запись. Отдельный блок не нужен; выход формы срабатывает после успешной отправки.
- Добавьте на экран «Форма записи» и выберите «Список».
- В «Что делает форма» оставьте «Добавляет запись» или выберите «Меняет запись». Для изменения укажите «Какую запись менять» — обычно переменную, которую кладёт нажатие на запись списка. Отметка «Показать в полях значения записи» заполнит поля текущими значениями.
- Добавьте «Поля формы» — по одному или кнопкой «Поля по всем колонкам». Поле получает подпись по имени колонки.
- Задайте проверки: «Обязательное поле», длину и «Шаблон (регулярное выражение)» у текста, «Границы значения» у числа, «Границы даты» у даты. «Текст ошибки» покажется вместо стандартного.
- В «Кнопка отправки» задайте надпись, цвет и вид кнопки. В «После отправки» — переменную для идентификатора новой записи.
- Проведите связь с выхода формы на экран «Спасибо».
Значения проверяются ещё раз на сервере. Пока есть ошибки, форма остаётся на экране и подсвечивает поля. Тексты ошибок по умолчанию: «Заполните это поле», «Введите число», «Введите дату», «Значение не меньше …», «Значение не больше …», «Не короче … символов», «Не длиннее … символов», «Значение не подходит по формату».
Ограничения формы:
- до 50 полей;
- из поля сохраняется до 5000 символов;
- один посетитель создаёт через формы до 60 новых записей в час. Сверх этого — сообщение «Слишком много отправок формы подряд, попробуйте позже.»
Теги
В приложении два вида тегов.
| Теги пользователя | Теги контакта | |
|---|---|---|
| Чьи | Самого приложения — есть у каждого, кто его открыл, даже без бота | Контакта в чат-боте — те же, что в карточке контакта |
| Чем меняются | Блок «Теги пользователя», вручную в карточке пользователя | Блок «Теги контакта». Нужен контакт бота |
| Где видны | Карточка пользователя в разделе «Пользователи» | Карточка контакта бота |
| Переменная | appTags |
contactTags |
По тегам работают условия: «Тег пользователя» и «Тег контакта» со сравнениями «содержит теги» и «не содержит теги». Можно перечислить несколько тегов — достаточно одного из них. Теги сравниваются без учёта регистра.
У одного человека — до 500 тегов: новые сверх этого не добавляются.
Условия
Условия задаются одинаково в блоке «Условие» и в «Условии показа» элемента, области или кнопки шапки.
- «Как объединять»: «Все условия» или «Любое из условий».
- У каждого сравнения — «Что проверяем», «Сравнение» и «Значение». Сравнений — до 20.
| «Что проверяем» | На что смотрит |
|---|---|
| «Переменную» | Любую переменную — её имя указывается в поле «Переменная» |
| «Источник запуска» | Откуда открыто приложение: «Браузер», «С экрана (PWA)», «Telegram», «MAX», «Веб-чат». Сравнения — = и != |
| «Параметр ссылки» | То, что было в ссылке после startapp: по нему различают источники переходов и акции |
| «Тег контакта» | Теги контакта в чат-боте |
| «Тег пользователя» | Теги приложения |
Сравнения: =, !=, >, <, >=, <=, «содержит», «не содержит», «пусто», «не пусто», «содержит теги», «не содержит теги». «Больше» и «меньше» сравнивают числа, «содержит» — текст без учёта регистра. В «Значение» можно подставить переменную: {{ имя }}.
Условие показа по полю этого же экрана срабатывает сразу, пока человек заполняет поле: например, поле «Комментарий» появляется, только когда включён переключатель «Нужна доставка».