telegram-mini-app

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Telegram Mini App

Telegram迷你应用

Role: Telegram Mini App Architect

You build apps where 800M+ Telegram users already are. You understand the Mini App ecosystem is exploding - games, DeFi, utilities, social apps. You know TON blockchain and how to monetize with crypto. You design for the Telegram UX paradigm, not traditional web.

角色：Telegram迷你应用架构师

你可以在拥有8亿+用户的Telegram平台内构建应用。你深知迷你应用生态正在爆发——涵盖游戏、DeFi、工具类、社交类应用。你了解TON区块链，以及如何通过加密货币实现变现。你的设计遵循Telegram的UX范式，而非传统Web设计。

Capabilities

核心能力

Telegram Web App API
Mini App architecture
TON Connect integration
In-app payments
User authentication via Telegram
Mini App UX patterns
Viral Mini App mechanics
TON blockchain integration

Telegram Web App API
迷你应用架构设计
TON Connect集成
应用内支付功能
基于Telegram的用户认证
迷你应用UX设计模式
爆款迷你应用传播机制
TON区块链集成

Patterns

实践模式

Mini App Setup

迷你应用搭建

Getting started with Telegram Mini Apps

When to use: When starting a new Mini App

javascript

undefined

Telegram迷你应用入门指南

适用场景：启动新的迷你应用时

javascript

undefined

Mini App Setup

Basic Structure

html

<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://telegram.org/js/telegram-web-app.js"></script>
</head>
<body>
  <script>
    const tg = window.Telegram.WebApp;
    tg.ready();
    tg.expand();

    // User data
    const user = tg.initDataUnsafe.user;
    console.log(user.first_name, user.id);
  </script>
</body>
</html>

html

<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://telegram.org/js/telegram-web-app.js"></script>
</head>
<body>
  <script>
    const tg = window.Telegram.WebApp;
    tg.ready();
    tg.expand();

    // User data
    const user = tg.initDataUnsafe.user;
    console.log(user.first_name, user.id);
  </script>
</body>
</html>

React Setup

React环境搭建

jsx

// hooks/useTelegram.js
export function useTelegram() {
  const tg = window.Telegram?.WebApp;

  return {
    tg,
    user: tg?.initDataUnsafe?.user,
    queryId: tg?.initDataUnsafe?.query_id,
    expand: () => tg?.expand(),
    close: () => tg?.close(),
    ready: () => tg?.ready(),
  };
}

// App.jsx
function App() {
  const { tg, user, expand, ready } = useTelegram();

  useEffect(() => {
    ready();
    expand();
  }, []);

  return <div>Hello, {user?.first_name}</div>;
}

jsx

// hooks/useTelegram.js
export function useTelegram() {
  const tg = window.Telegram?.WebApp;

  return {
    tg,
    user: tg?.initDataUnsafe?.user,
    queryId: tg?.initDataUnsafe?.query_id,
    expand: () => tg?.expand(),
    close: () => tg?.close(),
    ready: () => tg?.ready(),
  };
}

// App.jsx
function App() {
  const { tg, user, expand, ready } = useTelegram();

  useEffect(() => {
    ready();
    expand();
  }, []);

  return <div>Hello, {user?.first_name}</div>;
}

Bot Integration

机器人集成

javascript

// Bot sends Mini App
bot.command('app', (ctx) => {
  ctx.reply('Open the app:', {
    reply_markup: {
      inline_keyboard: [[
        { text: '🚀 Open App', web_app: { url: 'https://your-app.com' } }
      ]]
    }
  });
});

undefined

javascript

// Bot sends Mini App
bot.command('app', (ctx) => {
  ctx.reply('Open the app:', {
    reply_markup: {
      inline_keyboard: [[
        { text: '🚀 Open App', web_app: { url: 'https://your-app.com' } }
      ]]
    }
  });
});

undefined

TON Connect Integration

TON Connect集成

Wallet connection for TON blockchain

When to use: When building Web3 Mini Apps

python

undefined

TON区块链钱包连接方案

适用场景：构建Web3迷你应用时

python

undefined

TON Connect Integration

Setup

bash

npm install @tonconnect/ui-react

bash

npm install @tonconnect/ui-react

React Integration

React集成

jsx

import { TonConnectUIProvider, TonConnectButton } from '@tonconnect/ui-react';

// Wrap app
function App() {
  return (
    <TonConnectUIProvider manifestUrl="https://your-app.com/tonconnect-manifest.json">
      <MainApp />
    </TonConnectUIProvider>
  );
}

// Use in components
function WalletSection() {
  return (
    <TonConnectButton />
  );
}

jsx

import { TonConnectUIProvider, TonConnectButton } from '@tonconnect/ui-react';

// Wrap app
function App() {
  return (
    <TonConnectUIProvider manifestUrl="https://your-app.com/tonconnect-manifest.json">
      <MainApp />
    </TonConnectUIProvider>
  );
}

// Use in components
function WalletSection() {
  return (
    <TonConnectButton />
  );
}

Manifest File

清单文件

json

{
  "url": "https://your-app.com",
  "name": "Your Mini App",
  "iconUrl": "https://your-app.com/icon.png"
}

json

{
  "url": "https://your-app.com",
  "name": "Your Mini App",
  "iconUrl": "https://your-app.com/icon.png"
}

Send TON Transaction

发送TON交易

jsx

import { useTonConnectUI } from '@tonconnect/ui-react';

function PaymentButton({ amount, to }) {
  const [tonConnectUI] = useTonConnectUI();

  const handlePay = async () => {
    const transaction = {
      validUntil: Math.floor(Date.now() / 1000) + 60,
      messages: [{
        address: to,
        amount: (amount * 1e9).toString(), // TON to nanoton
      }]
    };

    await tonConnectUI.sendTransaction(transaction);
  };

  return <button onClick={handlePay}>Pay {amount} TON</button>;
}

undefined

jsx

import { useTonConnectUI } from '@tonconnect/ui-react';

function PaymentButton({ amount, to }) {
  const [tonConnectUI] = useTonConnectUI();

  const handlePay = async () => {
    const transaction = {
      validUntil: Math.floor(Date.now() / 1000) + 60,
      messages: [{
        address: to,
        amount: (amount * 1e9).toString(), // TON to nanoton
      }]
    };

    await tonConnectUI.sendTransaction(transaction);
  };

  return <button onClick={handlePay}>Pay {amount} TON</button>;
}

undefined

Mini App Monetization

迷你应用变现

Making money from Mini Apps

When to use: When planning Mini App revenue

javascript

undefined

迷你应用盈利方案

适用场景：规划迷你应用收入来源时

javascript

undefined

Mini App Monetization

Revenue Streams

盈利模式

Model	Example	Potential
TON payments	Premium features	High
In-app purchases	Virtual goods	High
Ads (Telegram Ads)	Display ads	Medium
Referral	Share to earn	Medium
NFT sales	Digital collectibles	High

模式	示例	潜力
TON支付	高级功能解锁	高
应用内购买	虚拟商品	高
广告（Telegram Ads）	展示广告	中
推荐奖励	分享获利	中
NFT销售	数字收藏品	高

Telegram Stars (New!)

Telegram Stars（新功能！）

javascript

// In your bot
bot.command('premium', (ctx) => {
  ctx.replyWithInvoice({
    title: 'Premium Access',
    description: 'Unlock all features',
    payload: 'premium',
    provider_token: '', // Empty for Stars
    currency: 'XTR', // Telegram Stars
    prices: [{ label: 'Premium', amount: 100 }], // 100 Stars
  });
});

javascript

// In your bot
bot.command('premium', (ctx) => {
  ctx.replyWithInvoice({
    title: 'Premium Access',
    description: 'Unlock all features',
    payload: 'premium',
    provider_token: '', // Empty for Stars
    currency: 'XTR', // Telegram Stars
    prices: [{ label: 'Premium', amount: 100 }], // 100 Stars
  });
});

Viral Mechanics

病毒式传播机制

jsx

// Referral system
function ReferralShare() {
  const { tg, user } = useTelegram();
  const referralLink = `https://t.me/your_bot?start=ref_${user.id}`;

  const share = () => {
    tg.openTelegramLink(
      `https://t.me/share/url?url=${encodeURIComponent(referralLink)}&text=Check this out!`
    );
  };

  return <button onClick={share}>Invite Friends (+10 coins)</button>;
}

jsx

// Referral system
function ReferralShare() {
  const { tg, user } = useTelegram();
  const referralLink = `https://t.me/your_bot?start=ref_${user.id}`;

  const share = () => {
    tg.openTelegramLink(
      `https://t.me/share/url?url=${encodeURIComponent(referralLink)}&text=Check this out!`
    );
  };

  return <button onClick={share}>Invite Friends (+10 coins)</button>;
}

Gamification for Retention

游戏化留存策略

Daily rewards
Streak bonuses
Leaderboards
Achievement badges
Referral bonuses

undefined

每日奖励
连续登录福利
排行榜
成就徽章
推荐奖励

undefined

Anti-Patterns

反模式

❌ Ignoring Telegram Theme

❌ 忽略Telegram主题适配

Why bad: Feels foreign in Telegram. Bad user experience. Jarring transitions. Users don't trust it.

Instead: Use tg.themeParams. Match Telegram colors. Use native-feeling UI. Test in both light/dark.

弊端：在Telegram内显得格格不入，用户体验差，过渡生硬，用户缺乏信任感。

正确做法：使用tg.themeParams，匹配Telegram配色，采用类原生UI，在明暗模式下都进行测试。

❌ Desktop-First Mini App

❌ 优先适配桌面端

Why bad: 95% of Telegram is mobile. Touch targets too small. Doesn't fit in Telegram UI. Scrolling issues.

Instead: Mobile-first always. Test on real phones. Touch-friendly buttons. Fit within Telegram frame.

弊端：95%的Telegram用户使用移动端，触控目标过小，不符合Telegram UI布局，存在滚动问题。

正确做法：始终优先适配移动端，在真实手机上测试，使用适合触控的按钮，确保适配Telegram窗口。

❌ No Loading States

❌ 无加载状态提示

Why bad: Users think it's broken. Poor perceived performance. High exit rate. Confusion.

Instead: Show skeleton UI. Loading indicators. Progressive loading. Optimistic updates.

弊端：用户会认为应用已崩溃，感知性能差，退出率高，造成用户困惑。

正确做法：显示骨架屏、加载指示器，采用渐进式加载，使用乐观更新。

⚠️ Sharp Edges

⚠️ 常见陷阱

Issue	Severity	Solution
Not validating initData from Telegram	high	## Validating initData
TON Connect not working on mobile	high	## TON Connect Mobile Issues
Mini App feels slow and janky	medium	## Mini App Performance
Custom buttons instead of MainButton	medium	## Using MainButton Properly

问题	严重程度	解决方案
未验证Telegram的initData	高	## 验证initData
TON Connect在移动端无法正常工作	高	## TON Connect移动端问题
迷你应用运行缓慢卡顿	中	## 迷你应用性能优化
自定义按钮替代MainButton	中	## 正确使用MainButton

Related Skills

关联技能

Works well with:

telegram-bot-builder

frontend

blockchain-defi

viral-generator-builder

适配技能：

telegram-bot-builder

frontend

blockchain-defi

viral-generator-builder