Construire SpyClub : le guide complet du développement moderne de mini apps Telegram

3 février 2025

Thomas Cosialls

Introduction

Les mini apps Telegram se sont imposées comme une plateforme puissante pour créer des expériences blockchain engageantes. SpyClub incarne la fusion parfaite entre jeu occasionnel, fonctionnalités sociales et technologie blockchain, le tout dans un format accessible qui tourne directement dans Telegram.

Ce guide complet retrace la façon dont nous avons construit SpyClub, avec des enseignements concrets pour qui souhaite créer sa propre mini app Telegram intégrant la blockchain.

Présentation du jeu et fonctionnalités

SpyClub réinvente pour l'ère Web3 le jeu de société d'association de mots Codenames. Les joueurs rejoignent des parties en temps réel où ils rivalisent pour deviner des mots à partir d'indices. Les meilleurs remportent des jetons $SPY, convertibles en récompenses USDC.

Fonctionnalités clés :

Des parties multijoueurs en temps réel toutes les 30 minutes
Un système de récompenses mêlant monnaie de jeu et vraie cryptomonnaie ($SpyCoin sur la blockchain Hedera)
Des fonctions sociales : parrainage, classements et messages du bot Telegram
La création et la gestion automatisées de wallets on-chain
Un mécanisme de farming pour des gains passifs
Un système de quêtes progressives pour nourrir l'engagement

Architecture technique

architecture du projet spyclub — *SpyClub - architecture de la mini app Telegram*

Détail de la stack technique

Stack frontend

Cœur : React avec Vite et TypeScript
Gestion d'état : Zustand, pour un état global léger
Style : Tailwind CSS avec les composants shadcn/ui
Animations : Framer Motion pour des transitions fluides
Temps réel : Supabase Realtime pour le multijoueur
Intégration plateforme : le SDK des mini apps Telegram
Déploiement : CI/CD avec GitHub et Vercel

Stack backend

Serveur : Fastify, pour une API haute performance
Base de données : Supabase (PostgreSQL) pour la persistance
Temps réel : Supabase Realtime pour la gestion des WebSockets
Stockage : Supabase Storage pour les fichiers médias
Sûreté de typage : TypeScript sur toute la stack

Intégrations externes

Intégration Telegram

Authentification des utilisateurs via Telegram
SDK Mini App pour les fonctions natives (le retour haptique, par exemple)
Telegraf comme framework d'API bot pour les notifications et mises à jour

Jetez un œil à notre GitHub : nous avons publié un boilerplate pour démarrer votre mini app Telegram avec React et Vite.

Intégration blockchain

La blockchain Hedera pour les transactions de jetons
Une distribution quotidienne de récompenses USDC via des tâches CRON
La création automatisée de wallets on-chain pour les utilisateurs

Analytics et supervision

Suivi du comportement utilisateur avec MixPanel
Supervision des performances avec Google App Engine
Suivi et remontée des erreurs avec Sentry

Plongée dans le développement

La gestion des salons : le cœur du multijoueur

Dans SpyClub, les salons de jeu sont des entités dynamiques qui gèrent les interactions entre joueurs, le score et l'état de la partie. Voici un aperçu de notre système de gestion des salons :

gameRoom.ts

export class GameRoom {
  private players: Map<string, Player> = new Map()
  private currentRound: Round | null = null
  private scoreTracker: ScoreTracker

  async startGame() {
    if (this.players.size < MIN_PLAYERS) {
      throw new Error('Not enough players')
    }

    this.currentRound = await this.initializeRound()
    this.broadcastGameStart()
    
    this.gameLoop = setInterval(() => {
      this.updateGameState()
    }, TICK_RATE)
  }

  private async updateGameState() {
    if (this.shouldEndRound()) {
      await this.endRound()
      if (this.isGameComplete()) {
        await this.endGame()
      } else {
        await this.startNextRound()
      }
    }
  }
}

Gestion d'état : garder tout le monde synchronisé

La gestion de l'état côté frontend est déterminante pour une expérience de jeu fluide. Voici la structure de notre store de jeu Zustand :

gameStore.ts

interface GameState {
  room: GameRoom | null
  currentRound: RoundData | null
  players: Player[]
  userScore: number
  leaderboard: LeaderboardEntry[]
}

const useGameStore = create<GameState>((set) => ({
  room: null,
  currentRound: null,
  players: [],
  userScore: 0,
  leaderboard: [],
  updateGameState: (newState: Partial<GameState>) => 
      set((state) => ({ ...state, ...newState })),
  handleRoundEnd: async (roundResults) => {
      set((state) => ({
        ...state,
        userScore: state.userScore + roundResults.score,
        leaderboard: roundResults.newLeaderboard
      }))
  }
}))

Mise en place du bot Telegram

Voyons comment créer un bot Telegram simple avec des commandes personnalisées. Il faut d'abord discuter avec BotFather, le bot officiel de Telegram qui sert à créer les autres bots. Voici la marche à suivre :

Ouvrez Telegram et cherchez « @BotFather »
Démarrez la conversation avec /newbot
Suivez les instructions pour :
- Définir le nom affiché de votre bot
- Choisir un identifiant unique (il doit se terminer par « bot »)

Une fois terminé, BotFather vous fournit un Bot Token : c'est votre clé d'accès à l'API Telegram. Gardez-la en lieu sûr, nous en aurons besoin dans nos variables d'environnement :


// From config.ts
export const BOT_TOKEN = process.env.BOT_TOKEN || ""
export const TELEGRAM_API_BASE_URL = "https://api.telegram.org"

Vous pouvez ensuite configurer les commandes du bot côté serveur :

commands.ts

import { FastifyInstance } from "fastify"
import { Telegraf, Context } from "telegraf"
import { BOT_TOKEN, BACKEND_URL, APP_URL, TELEGRAM_BOT_URL } from "../config"

export function setupBotCommands(fastify: FastifyInstance) {
  const bot = new Telegraf(BOT_TOKEN)

  bot.command("start", async (ctx: Context) => {
    /** Your start command logic **/
  })

  // Set up webhook
  fastify.post(`/bot${BOT_TOKEN}`, (request, reply) => {
    bot.handleUpdate(request.body as any, reply.raw)
  })

  // Start the bot
  bot.launch({
    webhook: {
      domain: `${BACKEND_URL}`,
      hookPath: `/bot${BOT_TOKEN}`,
    },
  })

  fastify.log.info("Bot commands set up successfully")
}

Enfin, n'oubliez pas d'enregistrer votre webhook via l'API bot de Telegram :


curl --location --request POST 'https://api.telegram.org/bot{bot_token}/setWebhook'
payload_data = {
‘url’: your-webhook-url
}

Vous pouvez vérifier que le webhook est bien enregistré en appelant :


curl --location 'https://api.telegram.org/bot{bot_token}/getWebhookInfo'

Déploiement et montée en charge : prêt pour la croissance

L'architecture de SpyClub est conçue pour passer à l'échelle horizontalement, grâce aux capacités de Google App Engine.

Les salons de jeu sont répartis sur plusieurs instances serveur
Les requêtes en base sont optimisées par une indexation soignée
Des couches de cache couvrent les données les plus consultées
Un équilibrage de charge répartit uniformément les connexions des joueurs

Notre app.yaml ressemble à ceci :

app.yaml

runtime: nodejs20

service: spyclub-backend-prod

automatic_scaling:
  min_instances: 1

inbound_services:
  - warmup

env_variables: your env here

Les enseignements

Tout au long du développement de SpyClub, nous avons tiré plusieurs leçons :

Cohérence en temps réel : maintenir l'état du jeu sur plusieurs clients demande une synchronisation rigoureuse
Intégration blockchain : prévoyez toujours des mécanismes de réessai et une gestion d'erreur solide pour les transactions
Expérience utilisateur : l'équilibre entre mécaniques de jeu et fonctionnalités blockchain est déterminant
Performance : optimisez pour le mobile, car la plupart des joueurs utilisent Telegram sur téléphone

Prêt à construire la vôtre ?

Réussir une mini app Telegram demande de la préparation et de la rigueur d'exécution. Que vous construisiez un jeu, une application DeFi ou tout autre chose, l'architecture et les patterns partagés ici vous donneront une base solide.

Souvenez-vous : la clé du succès ne tient pas seulement à l'implémentation technique, mais à la capacité de créer une expérience qui donne envie de revenir. Bon développement !

Besoin d'aide pour votre prochain projet blockchain ? Écrivez-nous et concrétisons votre vision !

Suivez-nous