TeleTemplate文档Telegram
Telegram MiniApp
Telegram MiniApp 集成介绍
概述
Telegram MiniApp（前身为 Web Apps）允许你构建在 Telegram 内运行的交互式 Web 应用。SuperTele 提供无缝的 MiniApp 集成，支持自动认证和主题同步。
特性
自动认证
用户打开 MiniApp 时自动完成认证，无需手动登录。
主题同步
MiniApp 自动同步 Telegram 的亮色/暗色主题设置。
原生体验
使用 Telegram 原生 UI 组件，提供无缝的用户体验。
工作原理
用户打开 MiniApp
用户从 Bot 菜单或内联按钮打开 MiniApp。
Telegram 注入 initData
Telegram 客户端注入包含用户信息和签名的 initData。
服务端验证 initData
服务端使用 Bot Token 验证签名，确保数据真实性。
创建或关联用户
如果 Telegram 用户不存在，创建新账户；否则关联到现有账户。
建立会话
创建会话并返回 MiniApp，用户已完成登录。
配置
环境变量
# MiniApp 认证验证必需
TELEGRAM_BOT_TOKEN=your_bot_tokenMiniApp Provider
模板包含 TelegramMiniAppProvider，自动处理认证：
// src/components/providers/telegram-miniapp-provider.tsx
<TelegramMiniAppProvider>
{children}
</TelegramMiniAppProvider>检测 MiniApp 环境
使用 useTelegramMiniApp hook 检测应用是否在 Telegram 内运行：
import { useTelegramMiniApp } from '@/hooks/use-telegram-miniapp';
function MyComponent() {
const { isMiniApp, isLoading } = useTelegramMiniApp();
if (isMiniApp) {
// 在 Telegram MiniApp 内运行
return <MiniAppUI />;
}
// 在普通浏览器中运行
return <WebUI />;
}MiniApp 特定功能
在 MiniApp 中隐藏元素
某些 UI 元素应在 MiniApp 环境中隐藏：
const { isMiniApp } = useTelegramMiniApp();
return (
<div>
{!isMiniApp && <Header />}
<MainContent />
{!isMiniApp && <Footer />}
</div>
);Telegram UI 组件
使用 Telegram 原生组件以获得更好的集成体验：
- MainButton - 底部操作按钮
- BackButton - 导航返回按钮
- HapticFeedback - 振动反馈
- CloudStorage - 持久化存储
文件结构
src/
├── components/providers/
│ └── telegram-miniapp-provider.tsx # 认证 Provider
├── hooks/
│ └── use-telegram-miniapp.ts # MiniApp 检测 hook
└── app/api/telegram/miniapp/
└── auth/route.ts # 认证 API 端点