Как создать Telegram Mini App: пошаговое руководство

В этой статье, на примере реального приложения для заказа еды (аналогично Durer King), мы проведем вас через весь процесс разработки от 0 до 1. Независимо от того, являетесь ли вы фронтенд-разработчиком или менеджером продукта, желающим попробовать экосистему Telegram, эта статья поможет вам быстро начать работу.

---

Почему стоит выбрать мини-приложения Telegram?

Telegram — это не просто мессенджер, его открытая экосистема предоставляет разработчикам огромное пространство для творчества:

• Встроенная интеграция платежей: Не нужно подключать сторонние сервисы, транзакции можно проводить непосредственно через Telegram Payments.
• Низкая стоимость привлечения пользователей: Пользователям не нужно скачивать дополнительное приложение, его можно открыть прямо в окне чата.
• Единый кроссплатформенный опыт: Независимо от того, используете ли вы веб-версию, мобильное или настольное приложение, пользовательский опыт будет в высокой степени единообразным.

В качестве примера в этой статье мы создадим полноценную систему доставки еды, включающую Web App + Telegram Bot + платежную функцию. Для фронтенда будет использоваться React.js, для бэкенда — Node.js, а также будет интегрирована официальная платежная система Telegram.

---

Выбор технологий и подготовка к разработке

Прежде чем мы начнем, необходимо определить технологический стек:

• Фреймворк для фронтенда: React.js + TypeScript (обеспечивает типобезопасность, подходит для средних и крупных проектов)
• Сервис для бэкенда: Node.js (бесшовная интеграция с API Telegram)
• Инструменты для разработки: Telegram Mini App SDK (рекомендовано официально, богатый функционал)
• Требования к среде: Протокол HTTPS (обязательное требование Telegram)

Стоит отметить, что мини-приложения Telegram принудительно используют протокол HTTPS, что означает необходимость настройки SSL-сертификата и при локальной разработке. Далее мы подробно расскажем, как решить эту проблему.

---

Шаг 1: Создание Telegram-бота

Все мини-приложения Telegram запускаются через бота. Сначала создадим бота с помощью BotFather:

1. Найдите @BotFather в Telegram и откройте чат.
2. Отправьте команду /newbot.
3. Следуйте инструкциям, чтобы ввести название бота и его юзернейм.
4. После успешного создания вы получите API Token (обязательно сохраните его, он понадобится позже).

Этот токен работает как ключ, связывающий ваше приложение с серверами Telegram.

---

Шаг 2: Инициализация проекта и установка SDK

Далее мы быстро создадим проект с помощью официального Telegram Mini App SDK:

# Создание проекта React + TypeScript
npx create-react-app my-telegram-app --template typescript
cd my-telegram-app

# Установка Telegram SDK
npm install @twa-dev/sdk

SDK предоставляет богатый набор API для таких задач, как получение информации о пользователе, вызов платежных интерфейсов, отправка сообщений и т. д. После установки откройте проект в VS Code и запустите его:

npm start

В этот момент вы увидите, что проект запущен по адресу http://localhost:3000, но этого недостаточно — Telegram требует, чтобы все мини-приложения были доступны через HTTPS.

---

Шаг 3: Настройка HTTPS-среды

Многие разработчики останавливаются на этом этапе: как использовать HTTPS при локальной разработке? Есть два решения:

Вариант 1: Использование локального SSL-сертификата

Измените скрипт запуска в package.json:

"scripts": {
  "start": "HTTPS=true react-scripts start"
}

Таким образом, проект автоматически запустится с самоподписанным сертификатом по адресу https://localhost:3000.

Вариант 2: Использование ngrok (рекомендуется)

Если вам требуется удаленное тестирование (например, на мобильном телефоне), вы можете использовать ngrok для отображения локального сервиса в общедоступной сети:

ngrok http 3000

ngrok сгенерирует общедоступный HTTPS-адрес, скопируйте его, и его можно будет использовать в Telegram.

---

Шаг 4: Подключение Web App к боту

Теперь нам нужно сообщить Telegram, где находится точка входа мини-приложения этого бота. Вернитесь в BotFather:

1. Отправьте команду /mybots, выберите созданного вами бота.
2. Нажмите Bot Settings → Menu Button.
3. Введите HTTPS-адрес, который вы получили ранее (например, https://your-ngrok-url.io).

После этого, открыв вашего бота, нажмите на кнопку меню внизу, и мини-приложение откроется внутри Telegram!

---

Шаг 5: Инициализация кода и тестирование

Очистите стандартный код React, оставив основную структуру:

import { useEffect } from 'react';
import './App.css';

function App() {
  useEffect(() => {
    // Инициализация Telegram SDK
    const tg = (window as any).Telegram.WebApp;
    tg.ready();
    console.log('Telegram WebApp загружен');
  }, []);

  return (
    <div className="App">
      <h1>Привет, Telegram!</h1>
    </div>
  );
}

export default App;

После сохранения и обновления в Telegram вы должны увидеть страницу "Привет, Telegram!", а в консоли — сообщение об успешной инициализации SDK.

---

Шаг 6: Правила оформления и глобальная настройка

Для обеспечения единообразного отображения на разных устройствах рекомендуется использовать Normalize.css и настроить глобальные стили:

/* App.css */
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

body {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
  background-color: var(--tg-theme-bg-color);
  color: var(--tg-theme-text-color);
}

Telegram предоставляет набор переменных темы, которые позволяют вашему приложению автоматически адаптироваться к темному/светлому режиму пользователя.

---

Дальнейшие направления разработки

После выполнения этих шагов у вас будет готовый каркас работающего мини-приложения Telegram. Далее вы можете:

• Добавить маршрутизацию страниц: Использовать React Router для реализации переходов между страницами.
• Интегрировать API бэкенда: Создать интерфейсы для управления заказами, списки товаров и т. д. с помощью Node.js.
• Подключить платежную функцию: Использовать Telegram Payments API для завершения транзакций.
• Улучшить пользовательский опыт: Добавить анимацию загрузки, уведомления об ошибках, логику корзины и т. д.

Если вам нужен антидетект-браузер для управления несколькими аккаунтами, автоматизированного тестирования и других сценариев, рассмотрите использование MasLogin. Он поможет вам смоделировать различные среды на этапе разработки и тестирования, избегая рисков, связанных с аккаунтами.

---

Частые вопросы (FAQ)

Почему мое мини-приложение не открывается в Telegram?

• Убедитесь, что используется протокол HTTPS (HTTP будет заблокирован).
• Проверьте правильность настройки адреса Menu Button для бота.
• Изучите консоль разработчика браузера на наличие сообщений об ошибках.

Нужно ли каждый раз перенастраивать ngrok при каждой модификации во время локальной разработки?

Если вы используете бесплатную версию ngrok, адрес будет меняться после каждого перезапуска. Рекомендуется:

• Обновить до платной версии ngrok (позволяет закрепить домен).
• Использовать альтернативные решения, такие как Cloudflare Tunnel.

Какие функции поддерживает Telegram SDK?

Основные API включают:

• window.Telegram.WebApp.ready() — Инициализация.
• window.Telegram.WebApp.MainButton — Управление главной кнопкой.
• window.Telegram.WebApp.initData — Получение информации о пользователе.
• window.Telegram.WebApp.close() — Закрытие мини-приложения.

Подробную документацию см. в Telegram WebApp API.

Как протестировать платежную функцию в Telegram?

Telegram предоставляет песочницу для тестирования. Вы можете использовать тестовые платежные реквизиты для отладки. Подробности см. в официальной документации по платежам.

---

Заключение

Благодаря этой статье вы освоили основные этапы разработки мини-приложений Telegram. Помните: сначала запустите минимально жизнеспособную версию, затем постепенно оптимизируйте ее. Начните создавать свои приложения в экосистеме Telegram прямо сейчас!