Як створити свій перший Telegram Mini App: покрокова інструкція

Telegram і WeChat: битва суперзастосунків

WeChat уже багато років утримує беззаперечне лідерство серед суперзастосунків. Запущений у 2011 році, він став невіддільною частиною повсякденного життя в Китаї, об’єднавши в одній платформі листування, соцмережі, платежі та онлайн-торгівлю. Telegram з’явився пізніше — у 2013 році, — але швидко надолужив відставання й став серйозним претендентом на глобальному ринку суперзастосунків. Сьогодні розробники можуть створювати інноваційні сервіси й навіть запускати мінісервіси безпосередньо в Telegram. Завдяки зрозумілій документації з Mini Apps розробляти застосунки стало простіше, ніж будь-коли: можна створити нового Telegram-бота або розробити Mini App, використовуючи звичні вебтехнології.

Ключові відмінності між Telegram і WeChat:

WeChat давно домінує на китайському ринку як універсальний застосунок, але Telegram активно бореться за місце серед лідерів у всьому світі. Завдяки увазі до конфіденційності, передовим функціям і інструментам для розробників Telegram займає унікальну нішу. А завдяки Telegram Mini Apps (TMA), розробники тепер можуть створювати вебзастосунки, які без проблем інтегруються в платформу, допомагаючи їй швидко скоротити відставання та здобути популярність у всьому світі.

Тепер розберімося, як створити Telegram Mini App і долучитися до дедалі більшої спільноти розробників, які використовують потенціал Telegram.

Що таке Telegram Mini Apps і чому вони такі популярні?

Telegram Mini Apps (TMA) — це вебзастосунки, що працюють усередині Telegram. Уявіть звичайні сайти, створені за допомогою HTML, CSS і JavaScript, але з доступом до унікальних функцій Telegram через SDK. Вони запускаються прямо в Telegram, забезпечуючи зручну взаємодію з користувачем, інтеграцію даних і вбудовані платіжні системи. Щоб використовувати можливості Telegram для Mini Apps, розробники зазвичай створюють бота через BotFather, задають йому username і налаштовують зв’язок із застосунком. Після цього Mini Apps можна поширювати в групах Telegram або надсилати користувачам напряму — це потужне доповнення до екосистеми. Розробникам, які хочуть скористатися можливостями платформи, важливо розуміти, як працюють Telegram Mini Apps.

Чому розробники обирають TMA:

Приклади успішних Telegram Mini Apps

Розгляньмо кілька реальних прикладів:

• Wallet — приклад сервісу гаманця, доступного через Telegram; функції залежать від конкретного гаманця та регіону.
• Hamster Kombat — гра-клікер, яка зібрала величезну аудиторію.
• DurgerKing — демонстраційний Mini App від Telegram, де можна протестувати процес замовлення їжі та оплати.

Як почати створювати Telegram Mini Apps

Що знадобиться:

• Редактор коду (підійдуть VS Code або WebStorm).
• Базові знання HTML, CSS і JavaScript.
• Telegram встановлено на телефоні й комп’ютері.
• Бажання відкрити для себе щось нове.

Крок 1: створіть допоміжного бота

Почніть зі створення бота в Telegram. Він стане точкою входу у ваш застосунок. Ось як це зробити:

1. Знайдіть у Telegram @BotFather.
2. Надішліть команду /newbot.
3. Виберіть ім’я для бота.
4. Надійно збережіть токен, який надасть BotFather, на своєму сервері — він знадобиться для Bot API. Не додавайте його до коду в браузері чи загальнодоступного репозиторію.

Нижче наведено Node.js-код для сервера. Встановіть node-telegram-bot-api, задайте токен через змінну середовища на сервері й замініть https://your-domain.com/app на свою розгорнуту HTTPS-адресу, перш ніж запускати код. Кнопка web_app у вбудованій клавіатурі призначена для приватного чату з ботом:

javascript
const TelegramBot = require('node-telegram-bot-api');
const bot = new TelegramBot(token, { polling: true });

bot.onText(/\/start/, (msg) => {
const chatId = msg.chat.id;
bot.sendMessage(chatId, 'Вітаємо! Натисніть кнопку нижче, щоб відкрити застосунок.', {
reply_markup: {
inline_keyboard: [[
{
text: 'Відкрити застосунок',
web_app: { url: 'https://your-domain.com/app' }
}
]]
}
});
});

Крок 2: налаштуйте середовище

Створіть базову структуру проєкту для Telegram Mini App і налаштуйте тестове середовище:

Структура папок проєкту (вміст index.html наведено в кроці 3):

text
my-tma/
├── index.html
├── styles/
│ └── main.css
├── scripts/
│ └── app.js
└── assets/
└── images/

Крок 3: створіть застосунок

Збережіть цей HTML-код у файлі index.html. Він підключає міст Telegram WebApp і скрипт scripts/app.js. Це приклад інтерфейсу, а не реалізація автентифікації: перш ніж довіряти даним про особу користувача, перевіряйте Telegram initData на своєму бекенді.
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Мій перший TMA</title>
<link rel="stylesheet" href="styles/main.css">
<script src="https://telegram.org/js/telegram-web-app.js"></script>
</head>
<body>
<div id="app">
<h1>Привіт, Telegram!</h1>
</div>
<script src="scripts/app.js"></script>
</body>
</html>

Стилізація застосунку

Збережіть JavaScript-код нижче у файлі scripts/app.js: setupTheme задає кольори теми Telegram, а styles/main.css — окрема таблиця стилів, яку можна налаштувати. Перевірте застосунок у Telegram на Android та iOS. Важливо: sendData працює лише в Mini Apps, запущених кнопкою web_app у клавіатурі відповідей, але не кнопкою вбудованої клавіатури з кроку 1. Щоб зберігати дані під час запуску через цю кнопку, створіть endpoint на бекенді та перевіряйте initData. У цьому прикладі дані не зберігаються, а вхідні повідомлення web_app_data не обробляються:

javascript
const app = {
data: { count: 0 },

init() {
this.setupTheme();
this.setupCounter();
this.setupMainButton();
},

setupTheme() {
const theme = window.Telegram.WebApp.themeParams;
document.body.style.backgroundColor = theme.bg_color;
document.body.style.color = theme.text_color;
},

setupCounter() {
const counter = document.createElement('div');
counter.innerHTML = `
<h2>Лічильник: <span id="count">0</span></h2>
<button id="increment">+1</button>
<button id="decrement">-1</button>
`;
document.querySelector('#app').appendChild(counter);

document.querySelector('#increment').onclick = () => this.updateCount(1);
document.querySelector('#decrement').onclick = () => this.updateCount(-1);
},

setupMainButton() {
const MainButton = window.Telegram.WebApp.MainButton;
MainButton.setText('Зберегти');
MainButton.onClick(() => this.saveData());
MainButton.show();
},

updateCount(delta) {
this.data.count += delta;
document.querySelector('#count').textContent = this.data.count;
},

saveData() {
window.Telegram.WebApp.sendData(JSON.stringify(this.data));
}
};

window.Telegram.WebApp.ready();
app.init();

Розширення функціональності

Після того як налаштуєте базові функції, можна розширити можливості Mini App:

• За потреби додайте функції Web3 на базі TON. Водночас за цифрові товари й послуги в Telegram потрібно платити через Telegram Stars, а не TON.
• Додайте оплату цифрових товарів і послуг через Telegram Stars. Налаштуйте підтвердження платежів і обробку повернень.
• Зберігайте дані користувачів на сервері після перевірки initData та всіх переданих значень.
• Додайте анімацію та складнішу логіку.
• Налаштуйте сповіщення від бота, отримавши потрібний дозвіл користувача. Mini App не може надсилати повідомлення будь-кому.
• Додайте кнопку меню для навігації.

Що далі?

1. Розгорніть застосунок на HTTPS-сервері.
2. Під’єднайте застосунок до Telegram через @BotFather.
3. Налагодьте застосунок і протестуйте його в реальних умовах.
4. Запустіть Telegram Mini App і зберіть перші відгуки.
5. Поділіться кодом на GitHub, щоб отримати відгуки спільноти. Не додавайте токени бота, секрети чи персональні дані.
6. Збирайте відгуки користувачів і вдосконалюйте застосунок.

Виконавши ці кроки, ви значно наблизитеся до створення успішного Telegram Mini App, який повною мірою використовує можливості екосистеми платформи, що стрімко розвивається.