# Про стилізацію клавіатури у Viber

Viber дозволяє налаштовувати зовнішній вигляд кнопок клавіатури через JSON конфігурацію. Це дозволяє створювати візуально привабливі інтерфейси з кольоровими кнопками, зображеннями та кастомним форматуванням.

## Контекст і проблема

У багатьох сценаріях потрібно створити візуально привабливий інтерфейс для користувачів:
- Кольорові кнопки для виділення важливих дій
- Зображення на кнопках для кращого розуміння
- Кастомне форматування для покращення UX
- Rich Media повідомлення з комбінацією текстів, зображень та кнопок

Стилізація клавіатури у Viber вирішує цю задачу, дозволяючи налаштовувати зовнішній вигляд кнопок через JSON конфігурацію.

## Основні концепції

### Типи стилізації

Viber підтримує різні типи стилізації клавіатури:
- **Фон кнопок** — колір фону всіх кнопок у клавіатурі
- **Окремі кнопки** — колір, зображення та форматування кожної кнопки окремо
- **Rich Media** — складні повідомлення з комбінацією текстів, зображень та кнопок

### Параметри конфігурації

Основні параметри для стилізації кнопок:
- `Columns` — ширина кнопки в стовбцях (1-6)
- `Rows` — висота кнопки в рядках (1-2)
- `BgColor` — колір фону кнопки
- `Image` — URL зображення на кнопці
- `TextVAlign`, `TextHAlign` — вирівнювання тексту
- `ActionType`, `ActionBody` — тип дії та тіло відповіді

## Варіанти підходів

### Звичайна клавіатура vs Rich Media

**Звичайна клавіатура:**
- ✅ Плюси: Простота налаштування, швидка реалізація
- ❌ Мінуси: Обмежені можливості стилізації

**Rich Media:**
- ✅ Плюси: Максимальна гнучкість, можливість створення складних інтерфейсів
- ❌ Мінуси: Складніше налаштування, обмеження на загальну висоту (7 рядків)

**Чому використовуємо обидва підходи:**
Звичайна клавіатура підходить для простих випадків, а Rich Media — для складних інтерфейсів з комбінацією текстів, зображень та кнопок.

## Прийняті рішення

### Обмеження Rich Media

Для Rich Media загальна висота всіх кнопок повинна дорівнювати 7 рядків, а ширина — 6 колонок. Це вимога Viber API для коректного відображення Rich Media повідомлень.

### Підтримка плейсхолдерів

У Rich Media можна використовувати плейсхолдер `{{broadcast-image}}` для динамічного вибору зображення на основі мови користувача при розсилках.

### Логіка відповіді з клавіатури

Натискання кнопки викликає різну відповідь в залежності від значення `ActionType`:
- `reply` — відправка тексту з `ActionBody`
- `open-url` — відкриття посилання з `ActionBody`
- `none` — кнопка без дії

## Наслідки для користувачів і імплементації

### Для інтеграторів

При використанні стилізації клавіатури у Viber важливо:

1. **Використовувати високу якість зображень** — рекомендовано x2 або x3 розмір для чіткості
2. **Дотримуватися обмежень Rich Media** — загальна висота повинна дорівнювати 7 рядків
3. **Налаштувати правильні розміри** — `Columns` та `Rows` для кожної кнопки
4. **Перевірити відображення** — тестувати на різних пристроях та розмірах екрану

### Типові помилки

**Помилка:** Rich Media не відображається коректно  
**Проблема:** Загальна висота не дорівнює 7 рядкам  
**Рішення:** Перевірити суму `Rows` всіх кнопок — вона повинна дорівнювати 7

**Помилка:** Зображення розмиті  
**Проблема:** Використано зображення низької якості  
**Рішення:** Використовувати зображення x2 або x3 розміру від потрібного

**Помилка:** Кнопка не виконує дію  
**Проблема:** Не вказано `ActionType` або `ActionBody`  
**Рішення:** Вказати правильний `ActionType` та `ActionBody` в JSON конфігурації

### Обмеження

- Rich Media працює тільки для Viber
- Загальна висота всіх кнопок повинна дорівнювати 7 рядків
- Максимальна ширина — 6 колонок
- Зображення повинні мати високу якість (рекомендовано x2 або x3 розмір)

## Приклади використання

### Додавання фона подложки кнопок

```json
{
  "BgColor": "#2db9b9",
  "DefaultHeight": null
}
```

### Додавання зображення на кнопку

```json
{
  "Columns": null,
  "Rows": null,
  "BgColor": null,
  "BgMediaType": null,
  "BgMedia": null,
  "BgLoop": null,
  "Image": "https://example.com/image.jpg"
}
```

### Rich Media структура

Rich Media вимагає загальну висоту 7 рядків:
- Заголовок: `Rows: 1`
- Малюнок: `Rows: 4`
- Інформація: `Rows: 1`
- Кнопка: `Rows: 1`
- Загальна висота: 1 + 4 + 1 + 1 = 7

## Пов'язані документи

- **Reference:** [Viber Bot API - Keyboards](https://developers.viber.com/docs/api/rest-bot-api/#keyboards) — офіційна документація Viber про клавіатури
- **Reference:** [Viber Bot API - Rich Media](https://developers.viber.com/docs/api/rest-bot-api/#rich-media) — офіційна документація Viber про Rich Media
- **Explanation:** [Стартове повідомлення у Viber](/uk/scenariodialog/explanation/viber-start-message.md) — особливості роботи з Viber