# Дані застосунку

## Змінні

Змінна — іменоване значення, яке застосунок пам'ятає про людину: ім'я з поля введення, вибраний товар, відповідь зовнішнього сервісу. Змінні зберігаються в кожного користувача застосунку свої: те, що ввела одна людина, інша не побачить.

Змінні не потрібно створювати заздалегідь. Досить указати ім'я там, куди записується значення, — у полі «Змінна» елемента або блоку. Конструктор запам'ятовує імена зі схеми й підказує їх під час введення.

![Підказка імен змінних у полі «Змінна»](https://support.watbot.org/_media/uk/02-mini-apps/_images/variable-hint.webp?v=1791781231)

Звідки беруться значення:

| Джерело | Що записує |
|---|---|
| Поля введення | Те, що людина ввела або вибрала, — у змінну з поля «Змінна» |
| «Записи списку» та інші елементи, де вибирають рядок | Ідентифікатор вибраного рядка — у змінну з налаштувань елемента |
| «HTTP-запит» | Відповідь повністю, код відповіді та окремі значення з відповіді |
| «Знайти запис» | Колонки знайденого запису |
| «Додати запис», «Форма запису» | Ідентифікатор нового запису |
| «JavaScript», код застосунку, «HTML-код» | Змінні, які дозволено писати коду, — див. [Код у застосунку](https://support.watbot.org/uk/mini-apps/code) |

Ще кілька змінних застосунок заповнює сам під час запуску. Записати в них щось своє не можна:

| Змінна | Що в ній |
|---|---|
| `launchSource` | Звідки відкрито застосунок: `telegram`, `max`, `webchat`, `pwa` або `browser` |
| `startParam` | Параметр посилання запуску — те, що стоїть після `startapp`. Як його передати — на сторінці [Версії та публікація](https://support.watbot.org/uk/mini-apps/publish) |
| `contactTags` | Теги контакту бота через кому |
| `appTags` | Теги користувача застосунку через кому |

Змінні людини видно в її картці в розділі «Користувачі», там само їх можна виправити. Як змінюються змінні в попередньому перегляді, показує панель «Налагодження».

**Обмеження.** Ім'я змінної — до 64 символів, значення — до 4096. В одного користувача — до 500 змінних: нові понад це не записуються.

## Підстановки

Значення змінної підставляється в текст подвійними фігурними дужками: `{{ имя }}`. Підстановки працюють у текстах і заголовках екранів, у підписах, у значеннях полів за замовчуванням, в адресі й тілі HTTP-запиту, у значеннях колонок і умовах відбору записів, у повідомленнях бота.

Приклад: поле введення пише ім'я в змінну `name`, а на наступному екрані заголовок «Дякуємо, `{{ name }}`!» перетвориться на «Дякуємо, Ганно!».

Якщо змінної немає, на її місці буде порожньо. Підставляється лише значення змінної: вирази й функції, які працюють в автопідстановках чат-бота, тут не підтримуються.

> [!TIP]
> У полях конструктора, куди пишеться значення, почніть вводити ім'я — підказка вставить підстановку повністю. У полях, куди записується результат, підказка вставляє саме ім'я змінної.

### Дані контакту бота

Якщо застосунок відкрито з бота і людина цьому боту писала, доступні поля її контакту:

| Підстановка | Що в ній |
|---|---|
| `{{ 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.` порожні.

## Списки

Застосунок зберігає дані у списках проєкту — тих самих, з якими працюють чат-боти: [Списки](https://support.watbot.org/uk/lists). Список, заповнений у застосунку, видно в розділі «Списки» меню проєкту, і навпаки. Чужий список — з іншого проєкту — застосунок не відкриє.

Застосунок може заповнювати поля типів «Текст», «Число», «Грошовий», «Логічний», «Дата» і «Дата і час». Поля «Файл», «Картинка», «ID контакту» та «ID бота» заповнити із застосунку не можна.

| Завдання | Чим робити |
|---|---|
| Показати каталог, розклад, відгуки | Елемент «Записи списку» |
| Відкрити один запис на окремому екрані | Натискання на запис кладе його ідентифікатор у змінну (за замовчуванням `recordId`), наступний екран показує його елементом «Картка запису» або розкладає по змінних блоком «Знайти запис» |
| Прийняти заявку або анкету | Елемент «Форма запису» або поля введення плюс блок «Додати запис» |
| Дати людині виправити свій запис | «Форма запису» в режимі «Змінює запис» або блок «Змінити запис» |
| Видалити запис | Блок «Видалити запис» |

### Відбір і сортування

У «Записів списку» та блоків записів є «Умови»: «Колонка», «Умова» і «Значення». Умови: «Дорівнює», «Містить», «Починається з», «Закінчується на», «Більше», «Менше», «Порожньо», «Заповнено». Умов — до 20.

У значення можна підставити змінну — тоді відбір залежить від того, що вибрала людина. Наприклад, поле пошуку пише в `query`, а умова «Назва» «Містить» `{{ query }}` показує відповідні записи.

«Сортування» — колонка й напрямок «За спаданням» або «За зростанням». Порожньо — спочатку нові записи.

«Скільки показувати» — стільки записів завантажується за один раз; з позначкою «Підвантажувати під час прокручування» наступні підвантажуються, коли людина догорнула до кінця. За один раз застосунок віддає не більше ніж 50 записів.

![Елемент «Записи списку»: що показувати, відбір і сортування](https://support.watbot.org/_media/uk/02-mini-apps/_images/records-element.webp?v=1791781231)

### Свої записи

Запис можна закріпити за людиною, яка його створила: позначка «Запис належить користувачеві» у «Форми запису» або «Привʼязати запис до поточного користувача» в блоку «Додати запис». Це працює і в гостя з браузера.

З позначкою «Лише записи поточного користувача» елемент або блок бачить лише записи цієї людини — так роблять «мої заявки», «мої замовлення», обране. У блоків «Змінити запис» і «Видалити запис» ця позначка ввімкнена за замовчуванням: без неї людина могла б підставити чужий ідентифікатор і змінити чужий запис.

## Форми

Елемент «Форма запису» — короткий шлях від екрана до запису: кожне поле форми — колонка списку, а надсилання одразу створює або змінює запис. Окремий блок не потрібен; вихід форми спрацьовує після успішного надсилання.

1. Додайте на екран «Форма запису» й виберіть «Список».
2. У «Що робить форма» залиште «Додає запис» або виберіть «Змінює запис». Для зміни вкажіть «Який запис змінювати» — зазвичай змінну, яку кладе натискання на запис списку. Позначка «Показати в полях значення запису» заповнить поля поточними значеннями.
3. Додайте «Поля форми» — по одному або кнопкою «Поля за всіма колонками». Поле отримує підпис за іменем колонки.
4. Задайте перевірки: «Обов'язкове поле», довжину й «Шаблон (регулярний вираз)» у тексту, «Межі значення» в числа, «Межі дати» в дати. «Текст помилки» покажеться замість стандартного.
5. У «Кнопка надсилання» задайте напис, колір і вигляд кнопки. У «Після надсилання» — змінну для ідентифікатора нового запису.
6. Проведіть зв'язок із виходу форми на екран «Дякуємо».

![Елемент «Форма запису»: список і поля форми](https://support.watbot.org/_media/uk/02-mini-apps/_images/record-form.webp?v=1791781231)

Значення перевіряються ще раз на сервері. Поки є помилки, форма залишається на екрані й підсвічує поля. Тексти помилок за замовчуванням: «Заповніть це поле», «Введіть число», «Введіть дату», «Значення не менше …», «Значення не більше …», «Не коротше … символів», «Не довше … символів», «Значення не відповідає формату».

**Обмеження форми:**

- до 50 полів;
- з поля зберігається до 5000 символів;
- один відвідувач створює через форми до 60 нових записів на годину. Понад це — повідомлення «Забагато надсилань форми поспіль, спробуйте пізніше.»

## Теги

У застосунку два види тегів.

| | Теги користувача | Теги контакту |
|---|---|---|
| Чиї | Самого застосунку — є в кожного, хто його відкрив, навіть без бота | Контакту в чат-боті — ті самі, що в картці контакту |
| Чим змінюються | Блок «Теги користувача», вручну в картці користувача | Блок «Теги контакту». Потрібен контакт бота |
| Де видно | Картка користувача в розділі «Користувачі» | Картка контакту бота |
| Змінна | `appTags` | `contactTags` |

![Блок «Теги користувача»](https://support.watbot.org/_media/uk/02-mini-apps/_images/tags-block.webp?v=1791781231)

За тегами працюють умови: «Тег користувача» і «Тег контакту» з порівняннями «містить теги» та «не містить теги». Можна перелічити кілька тегів — достатньо одного з них. Теги порівнюються без урахування регістру.

В однієї людини — до 500 тегів: нові понад це не додаються.

## Умови

Умови задаються однаково в блоці «Умова» і в «Умові показу» елемента, області або кнопки шапки.

- «Як об'єднувати»: «Усі умови» або «Будь-яка з умов».
- У кожного порівняння — «Що перевіряємо», «Порівняння» і «Значення». Порівнянь — до 20.

![Налаштування блока «Умова»: змінна й тег користувача](https://support.watbot.org/_media/uk/02-mini-apps/_images/condition.webp?v=1791781231)

| «Що перевіряємо» | На що дивиться |
|---|---|
| «Змінну» | Будь-яку змінну — її ім'я вказується в полі «Змінна» |
| «Джерело запуску» | Звідки відкрито застосунок: «Браузер», «З екрана (PWA)», «Telegram», «MAX», «Веб-чат». Порівняння — `=` і `!=` |
| «Параметр посилання» | Те, що було в посиланні після `startapp`: за ним розрізняють джерела переходів і акції |
| «Тег контакту» | Теги контакту в чат-боті |
| «Тег користувача» | Теги застосунку |

Порівняння: `=`, `!=`, `>`, `<`, `>=`, `<=`, «містить», «не містить», «порожньо», «не порожньо», «містить теги», «не містить теги». «Більше» і «менше» порівнюють числа, «містить» — текст без урахування регістру. У «Значення» можна підставити змінну: `{{ имя }}`.

Умова показу за полем цього ж екрана спрацьовує одразу, поки людина заповнює поле: наприклад, поле «Коментар» з'являється, лише коли ввімкнено перемикач «Потрібна доставка».