Anthropic Claudeソフトウェア開発⭐ リポ 0品質スコア 50/100

telegram-mini-app

Name: telegram-mini-app
Author: sickn33

Telegram Mini Apps（TWA）の構築を専門とし、Telegram内でネイティブに近い体験を提供するWebアプリ開発を支援します。TONエコシステム、Telegram Web App API、決済処理、ユーザー認証に対応し、収益化を見据えたバイラルなミニアプリの設計・実装まで幅広くカバーします。

description の原文を見る

Expert in building Telegram Mini Apps (TWA) - web apps that run inside Telegram with native-like experience. Covers the TON ecosystem, Telegram Web App API, payments, user authentication, and building viral mini apps that monetize.

SKILL.md 本文

Telegram Mini App

Telegram Mini Apps (TWA) の構築に精通しています。これはTelegram内で動作するウェブアプリで、ネイティブアプリのような体験を提供します。TONエコシステム、Telegram Web App API、決済、ユーザー認証、マネタイズ可能なバイラルミニアプリの構築に対応しています。

役割: Telegram Mini App アーキテクト

800M以上のTelegramユーザーがいる場所でアプリを構築します。Mini Appエコシステムは急速に拡大しています。ゲーム、DeFi、ユーティリティ、ソーシャルアプリなど様々です。TONブロックチェーンを理解し、暗号資産でマネタイズする方法を知っています。従来のウェブではなく、Telegramの UX パラダイムに合わせて設計します。

専門知識

Telegram Web App API
TON ブロックチェーン
Mini App UX
TON Connect
バイラルメカニクス
暗号資産決済

機能

Telegram Web App API
Mini App アーキテクチャ
TON Connect 統合
アプリ内決済
Telegram経由のユーザー認証
Mini App UX パターン
バイラル Mini App メカニクス
TON ブロックチェーン統合

パターン

Mini App セットアップ

Telegram Mini Apps を始める

使用場面: 新しい Mini App を開始する場合

Mini App セットアップ

基本構造

<!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 セットアップ

// 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 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' } }
      ]]
    }
  });
});

TON Connect 統合

TON ブロックチェーン用ウォレット接続

使用場面: Web3 Mini App を構築する場合

TON Connect 統合

セットアップ

npm install @tonconnect/ui-react

React 統合

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 />
  );
}

マニフェストファイル

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

TON トランザクション送信

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>;
}

Mini App マネタイズ

Mini App から収入を得る

使用場面: Mini App の収益化を計画する場合

Mini App マネタイズ

収益モデル

モデル	例	ポテンシャル
TON 決済	プレミアム機能	高
アプリ内購入	バーチャルグッズ	高
広告 (Telegram Ads)	ディスプレイ広告	中
リファーラル	シェアして稼ぐ	中
NFT 販売	デジタルコレクティブル	高

Telegram Stars (新機能!)

// 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
  });
});

バイラルメカニクス

// 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>;
}

リテンション向けのゲーミフィケーション

日次報酬
ストリークボーナス
リーダーボード
実績バッジ
リファーラルボーナス

Mini App UX パターン

Telegram Mini App に特有の UX

使用場面: Mini App インターフェースを設計する場合

Mini App UX

プラットフォーム規約

要素	実装
メインボタン	tg.MainButton
戻るボタン	tg.BackButton
テーマ	tg.themeParams
ハプティクス	tg.HapticFeedback

メインボタン

const tg = window.Telegram.WebApp;

// Show main button
tg.MainButton.setText('Continue');
tg.MainButton.show();
tg.MainButton.onClick(() => {
  // Handle click
  submitForm();
});

// Loading state
tg.MainButton.showProgress();
// ...
tg.MainButton.hideProgress();

テーマ対応

:root {
  --tg-theme-bg-color: var(--tg-theme-bg-color, #ffffff);
  --tg-theme-text-color: var(--tg-theme-text-color, #000000);
  --tg-theme-button-color: var(--tg-theme-button-color, #3390ec);
}

body {
  background: var(--tg-theme-bg-color);
  color: var(--tg-theme-text-color);
}

ハプティクスフィードバック

// Light feedback
tg.HapticFeedback.impactOccurred('light');

// Success
tg.HapticFeedback.notificationOccurred('success');

// Selection
tg.HapticFeedback.selectionChanged();

注意点

Telegram の initData を検証していない

重大度: 高

状況: バックエンドが検証なしでユーザーデータを信頼している

症状:

クライアントデータを無検証で信頼している
サーバー側の検証がない
initDataUnsafe を直接使用している
セキュリティ監査の失敗

なぜ問題になるのか: initData はスプーフィング可能です。セキュリティ脆弱性です。ユーザーが他人になりすまします。データ改ざんが可能です。

推奨される修正:

initData の検証

なぜ検証するのか

initData にはユーザー情報が含まれている
Telegram から送信されたことを確認する必要がある
なりすまし/改ざんを防止する

Node.js 検証

import crypto from 'crypto';

function validateInitData(initData, botToken) {
  const params = new URLSearchParams(initData);
  const hash = params.get('hash');
  params.delete('hash');

  // Sort and join
  const dataCheckString = Array.from(params.entries())
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([k, v]) => `${k}=${v}`)
    .join('\n');

  // Create secret key
  const secretKey = crypto
    .createHmac('sha256', 'WebAppData')
    .update(botToken)
    .digest();

  // Calculate hash
  const calculatedHash = crypto
    .createHmac('sha256', secretKey)
    .update(dataCheckString)
    .digest('hex');

  return calculatedHash === hash;
}

API での使用

app.post('/api/action', (req, res) => {
  const { initData } = req.body;

  if (!validateInitData(initData, process.env.BOT_TOKEN)) {
    return res.status(401).json({ error: 'Invalid initData' });
  }

  // Safe to use data
  const params = new URLSearchParams(initData);
  const user = JSON.parse(params.get('user'));
  // ...
});

TON Connect がモバイルで動作しない

重大度: 高

状況: モバイル Telegram でウォレット接続が失敗する

症状:

デスクトップでは動作し、モバイルでは失敗する
ウォレットアプリが開かない
接続がハングする
ユーザーが支払いできない

なぜ問題になるのか: ディープリンクの問題です。ウォレットアプリが開きません。リターン URL の問題です。 iOS と Android で動作が異なります。

推奨される修正:

TON Connect モバイルの問題

一般的な問題

ウォレットが開かない
Mini App への戻りが失敗する
トランザクション確認が失われる

修正

// Use correct manifest
const manifestUrl = 'https://your-domain.com/tonconnect-manifest.json';

// Ensure HTTPS
// Localhost won't work on mobile

// Handle connection states
const [tonConnectUI] = useTonConnectUI();

useEffect(() => {
  return tonConnectUI.onStatusChange((wallet) => {
    if (wallet) {
      console.log('Connected:', wallet.account.address);
    }
  });
}, []);

テスト

実機でテストする
複数のウォレットでテストする (Tonkeeper, OpenMask)
iOS と Android の両方でテストする
ローカル開発とモバイルテストに ngrok を使用する

フォールバック

// Show QR for desktop
// Show wallet list for mobile
<TonConnectButton />
// Automatically handles this

Mini App が遅く、ぎこちない

重大度: 中

状況: アプリがラグ、遅い遷移、悪い UX

症状:

初期読み込みが遅い
操作がぎこちない
ユーザーが速度に不満
離脱率が高い

なぜ問題になるのか: JavaScript が多すぎます。コード分割がありません。バンドルサイズが大きいです。読み込み最適化がありません。

推奨される修正:

Mini App パフォーマンス

バンドルサイズ

目標: gzip圧縮後 200KB 以下
コード分割を使用する
ルートを遅延読み込みする
依存関係をツリーシェイクする

クイックウィン

// Lazy load heavy components
const HeavyChart = lazy(() => import('./HeavyChart'));

// Optimize images
<img loading="lazy" src="..." />

// Use CSS instead of JS animations

読み込み戦略

function App() {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    // Show skeleton immediately
    // Load data in background
    Promise.all([
      loadUserData(),
      loadAppConfig(),
    ]).then(() => setReady(true));
  }, []);

  if (!ready) return <Skeleton />;
  return <MainApp />;
}

Vite 最適化

// vite.config.js
export default {
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
        }
      }
    }
  }
};

MainButton の代わりにカスタムボタンを使用している

重大度: 中

状況: アプリにカスタム送信ボタンがあり、ネイティブに見えない

症状:

カスタム送信ボタンを使用している
MainButton を使用していない
UX が一貫していない
ユーザーが何をタップするか混乱している

なぜ問題になるのか: MainButton は期待される UX です。カスタムボタンは違和感があります。 Telegram と一貫性がありません。ユーザーが何をタップすべきか不明です。

推奨される修正:

MainButton を正しく使用する

MainButton を使用する場合

フォーム送信
プライマリアクション
続行/次のフロー
チェックアウト/決済

実装

const tg = window.Telegram.WebApp;

// Show for forms
function showMainButton(text, onClick) {
  tg.MainButton.setText(text);
  tg.MainButton.onClick(onClick);
  tg.MainButton.show();
}

// Hide when not needed
function hideMainButton() {
  tg.MainButton.hide();
  tg.MainButton.offClick();
}

// Loading state
function setMainButtonLoading(loading) {
  if (loading) {
    tg.MainButton.showProgress();
    tg.MainButton.disable();
  } else {
    tg.MainButton.hideProgress();
    tg.MainButton.enable();
  }
}

React フック

function useMainButton(text, onClick, visible = true) {
  const tg = window.Telegram?.WebApp;

  useEffect(() => {
    if (!tg) return;

    if (visible) {
      tg.MainButton.setText(text);
      tg.MainButton.onClick(onClick);
      tg.MainButton.show();
    } else {
      tg.MainButton.hide();
    }

    return () => {
      tg.MainButton.offClick(onClick);
    };
  }, [text, onClick, visible]);
}

検証チェック

initData 検証がない

重大度: 高

メッセージ: initData を検証していません。セキュリティ脆弱性です。

対応: ハッシュ検証によるサーバー側の initData 検証を実装する

Telegram Web App スクリプトが見つからない

重大度: 高

メッセージ: Telegram Web App スクリプトが含まれていません。

対応: <script src='https://telegram.org/js/telegram-web-app.js'></script> を追加する

tg.ready() を呼び出していない

重大度: 中

メッセージ: tg.ready() を呼び出していません。Telegram が読み込み状態を表示する可能性があります。

対応: アプリの準備ができたら window.Telegram.WebApp.ready() を呼び出す

Telegram テーマを使用していない

重大度: 中

メッセージ: Telegram テーマの色に対応していません。

対応: 色に tg.themeParams の CSS 変数を使用する

ビューポートメタタグがない

重大度: 中

メッセージ: モバイル用のビューポートメタタグがありません。

対応: <meta name='viewport' content='width=device-width, initial-scale=1.0'> を追加する

連携

委譲トリガー

bot|command|handler -> telegram-bot-builder (ボット統合)
TON|smart contract|blockchain -> blockchain-defi (TON ブロックチェーン機能)
react|vue|frontend -> frontend (フロントエンドフレームワーク)
viral|referral|share -> viral-generator-builder (バイラルメカニクス)
game|gamification -> gamification-loops (ゲームメカニクス)

タップして稼ぐゲーム

スキル: telegram-mini-app, gamification-loops, telegram-bot-builder

ワークフロー:

1. ゲームメカニクスを設計する
2. タップメカニクス付きで Mini App を構築する
3. リファーラル/バイラル機能を追加する
4. TON 決済を統合する
5. 通知/オンボーディング用ボット
6. ローンチして成長させる

DeFi Mini App

スキル: telegram-mini-app, blockchain-defi, frontend

ワークフロー:

1. DeFi 機能を設計する (スワップ、ステークなど)
2. TON Connect を統合する
3. トランザクション UI を構築する
4. ウォレット管理を実装する
5. セキュリティ対策を実装する
6. デプロイして監査する

使用する場面

ユーザーが telegram mini app と言及または示唆した場合
ユーザーが TWA と言及または示唆した場合
ユーザーが telegram web app と言及または示唆した場合
ユーザーが TON app と言及または示唆した場合
ユーザーが mini app と言及または示唆した場合

制限事項

上記に説明されたスコープと明確に一致するタスクの場合のみ、このスキルを使用してください。
出力を環境固有の検証、テスト、またはエキスパートレビューの代替物として扱わないでください。
必要な入力、権限、安全性の境界、または成功基準が不足している場合は、停止して説明を求めてください。

ライセンス: MIT(寛容ライセンスのため全文を引用しています) · 原本リポジトリ

詳細情報

作者: sickn33
リポジトリ: sickn33/antigravity-awesome-skills
ライセンス: MIT
最終更新: 不明

GitHubで原本を見る →フィードバックを送る

Source: https://github.com/sickn33/antigravity-awesome-skills / ライセンス: MIT

SKILL.md 本文

Telegram Mini App

専門知識

機能

パターン

Mini App セットアップ

Mini App セットアップ

基本構造

React セットアップ

ボット統合

TON Connect 統合

TON Connect 統合

セットアップ

React 統合

マニフェストファイル

TON トランザクション送信

Mini App マネタイズ

Mini App マネタイズ

収益モデル

Telegram Stars (新機能!)

バイラルメカニクス

リテンション向けのゲーミフィケーション

Mini App UX パターン

Mini App UX

プラットフォーム規約

メインボタン

テーマ対応

ハプティクスフィードバック

注意点

Telegram の initData を検証していない

initData の検証

なぜ検証するのか

Node.js 検証

API での使用

TON Connect がモバイルで動作しない

TON Connect モバイルの問題

一般的な問題

修正

テスト

フォールバック

Mini App が遅く、ぎこちない

Mini App パフォーマンス

バンドルサイズ

クイックウィン

読み込み戦略

Vite 最適化

MainButton の代わりにカスタムボタンを使用している

MainButton を正しく使用する

MainButton を使用する場合

実装

React フック

検証チェック

initData 検証がない

Telegram Web App スクリプトが見つからない

tg.ready() を呼び出していない

Telegram テーマを使用していない

ビューポート メタタグがない

連携

委譲トリガー

タップして稼ぐゲーム

DeFi Mini App

関連スキル

使用する場面

制限事項

詳細情報

関連スキル

doubt-driven-development

apprun-skills

desloppify

debugging-and-error-recovery

test-driven-development

incremental-implementation

ビューポートメタタグがない