Como Criar um Mini Jogo Web3 no Telegram Passo a Passo

Este tutorial ensinará não apenas como criar e implantar um Mini App do Telegram, mas também como usar os recursos gratuitos do SDK da thirdweb para implementar recursos essenciais Web3 como abstração de conta (Account Abstraction), criação de carteira e airdrops de token.

---

Por que escolher Mini Apps do Telegram para projetos Web3?

Tráfego social orgânico + experiência sem barreiras

O Telegram tem mais de 800 milhões de usuários ativos mensais e permite que desenvolvedores globais implantem aplicativos gratuitamente. Para projetos Web3, as vantagens dos Mini Apps do Telegram incluem:

• Não é necessária instalação: os usuários usam diretamente dentro do Telegram
• Rápida disseminação social: compartilhe um link para atrair novos usuários
• Stack de tecnologia unificada: baseado em tecnologias da Web, compatível com frameworks populares como React/Vue
• Otimizado para dispositivos móveis: adaptação nativa para clientes móveis e de desktop

Ao combinar a tecnologia de abstração de conta, você pode permitir que os usuários tenham uma carteira on-chain apenas com seu e-mail, sem a necessidade de instalar plug-ins de carteira – isso é crucial para reduzir a barreira de entrada para projetos Web3.

---

O que vamos construir? Um jogo completo de Pedra, Papel e Tesoura Web3

O fluxo principal deste jogo é:

1. O usuário abre o Mini App dentro do Telegram
2. Faça login com seu e-mail e gere automaticamente uma carteira de contrato inteligente (Smart Account)
3. Jogue Pedra, Papel e Tesoura
4. Após vencer, clique em "Reivindicar Recompensa" para receber tokens gratuitamente em sua carteira
5. O saldo é exibido em tempo real, e você pode continuar jogando ou sair

Todo o processo não requer que o usuário pague nenhuma taxa de Gas, nem exibe caixas complexas de confirmação de assinatura – esta é a verdadeira experiência Web3 sem atrito proporcionada pela abstração de conta + Gas patrocinado.

---

Seleção e ferramentas de tecnologia essenciais

Frameworks Frontend

• Vite + React: para configurar rapidamente a interface
• TypeScript: para melhorar a robustez do código

Integração de recursos Web3

• SDK da thirdweb: forncece conexão de carteira, abstração de conta e interação com contratos
• vov/react-telegram-web-app: biblioteca de adaptação oficial do Telegram

Rede Blockchain

• Base Sepolia Testnet (rede de teste): gratuita e rápida, adequada para desenvolvimento e demonstração

Auxílio ao Desenvolvimento

• ngrok: para expor seu ambiente de desenvolvimento local à internet, facilitando a depuração

---

Passo 1: Criar um Mini App do Telegram

1. Adicionar o BotFather e criar um Bot

Na barra de pesquisa do Telegram, digite @BotFather, encontre o bot oficial e clique em "Iniciar".

Digite o comando para criar um novo bot:

/newbot

Siga as instruções para inserir um nome e um nome de usuário (que deve terminar com bot), por exemplo:

Nome: thirdweb YouTube Demo
Nome de usuário: thirdwebYouTubeBot

Após a criação bem-sucedida, o BotFather retornará um Token – guarde-o com segurança, pois é sua credencial para gerenciar o bot.

2. Criar um Mini App

No BotFather, digite novamente:

/newapp

Selecione o Bot que você acabou de criar e preencha sequencialmente:

• Título: thirdweb Rock Paper Scissors Demo
• Descrição: Web3 Rock Paper Scissors Mini Game
• Imagem: Carregue uma imagem de capa (tamanho recomendado: 640×360)
• URL do Web App: Deixe em branco por enquanto, preencheremos mais tarde

Neste momento, o Telegram solicitará o link de acesso ao seu Mini App. Vamos desenvolver o aplicativo primeiro e depois preencher este campo.

---

Passo 2: Configurar o ambiente de desenvolvimento local

Inicializar o projeto

Abra o terminal e execute:

bun create vite

Selecione:

• Nome do projeto: thirdweb-telegram-miniapp
• Framework: React
• Variante: TypeScript + SWC

Entre no diretório do projeto:

cd thirdweb-telegram-miniapp

Instalar dependências

Instale a biblioteca de adaptação do Telegram Web App:

bun add @vov/react-telegram-web-app

Instale o SDK da thirdweb:

bun add thirdweb

Configurar script do Telegram

Abra index.html e adicione dentro da tag <head>:

<script src="https://telegram.org/js/telegram-web-app.js"></script>

Este código informa ao Telegram que sua página da web será executada em um ambiente de Mini App.

Iniciar o servidor de desenvolvimento

npm run dev

Por padrão, o serviço será iniciado em http://localhost:5174.

---

Passo 3: Expor o link local com ngrok

Como o Telegram precisa de um URL público para acessar seu Mini App, usaremos a ferramenta ngrok para expor temporariamente seu serviço local à internet.

Execute:

ngrok http 5174

O ngrok retornará um endereço público, por exemplo:

https://abc123.ngrok.io

Copie este link, volte para o BotFather e cole-o no campo URL do Web App.

Agora, se você clicar no link do Mini App no Telegram, deverá ver a página padrão do Vite!

---

Passo 4: Integrar o SDK da thirdweb e conexão de carteira

Criar um Client ID

Acesse o Dashboard da thirdweb e crie um novo Client ID em Settings > API Keys.

Copie o Client ID para o arquivo .env.local na raiz do projeto:

VITE_CLIENT_ID=your_client_id_here

Configurar o Provider thirdweb

No src/main.tsx, envolva o aplicativo:

import { ThirdwebProvider } from "thirdweb/react";
import { createThirdwebClient } from "thirdweb";

const client = createThirdwebClient({
  clientId: import.meta.env.VITE_CLIENT_ID,
});

root.render(
  <ThirdwebProvider>
    <App />
  </ThirdwebProvider>
);

Adicionar funcionalidade de login por e-mail

Use o componente ConnectButton fornecido pela thirdweb:

import { ConnectButton } from "thirdweb/react";
import { inAppWallet } from "thirdweb/wallets";

<ConnectButton
  client={client}
  wallets={[
    inAppWallet({
      auth: {
        options: ["email"],
      },
    }),
  ]}
/>

O usuário insere o e-mail → recebe um código de verificação → após a verificação bem-sucedida, uma carteira é gerada automaticamente → concluído!

---

Passo 5: Construir a lógica do jogo Pedra, Papel e Tesoura

Implemente a lógica principal em src/components/RockPaperScissors.tsx:

type Choice = "rock" | "paper" | "scissors";
type Result = "win" | "lose" | "tie";

const choices: Choice[] = ["rock", "paper", "scissors"];

const getComputerChoice = (): Choice => {
  return choices[Math.floor(Math.random() * 3)];
};

const determineWinner = (player: Choice, computer: Choice): Result => {
  if (player === computer) return "tie";
  if (
    (player === "rock" && computer === "scissors") ||
    (player === "paper" && computer === "rock") ||
    (player === "scissors" && computer === "paper")
  ) {
    return "win";
  }
  return "lose";
};

O usuário clica no botão → a escolha do computador é gerada aleatoriamente → o resultado é determinado → o resultado é exibido.

---

Passo 6: Implantar um contrato de token ERC-20

Volte para o Dashboard da thirdweb, clique em Contracts > Deploy, e selecione Token Drop.

Configurar:

• Nome: Rock Paper Scissors Token
• Símbolo: RPS
• Rede: Base Sepolia

Após a implantação bem-sucedida, defina as Claim Conditions como "Reivindicação pública, sem restrições".

Copie o endereço do contrato e adicione-o ao código:

import { getContract } from "thirdweb";
import { baseSepolia } from "thirdweb/chains";

const contract = getContract({
  client,
  chain: baseSepolia,
  address: "0xYourContractAddress",
});

---

Passo 7: Implementar abstração de conta + reivindicar tokens sem Gas

Habilitar abstração de conta

Adicione ao ConnectButton:

<ConnectButton
  client={client}
  wallets={[inAppWallet({ auth: { options: ["email"] } })]}
  accountAbstraction={{
    chain: baseSepolia,
    sponsorGas: true,
  }}
/>

Isso garante que a carteira gerada pelo usuário seja uma carteira de contrato inteligente (Smart Account), e podemos pagar as taxas de Gas por eles.

Botão de reivindicação de token

import { TransactionButton } from "thirdweb/react";
import { claimTo } from "thirdweb/extensions/erc20";

<TransactionButton
  transaction={() =>
    claimTo({
      contract,
      to: account.address,
      quantity: "10",
    })
  }
  onTransactionConfirmed={() => alert("Token reivindicado!")}
>
  Reivindicar 10 RPS
</TransactionButton>

O usuário clica no botão → a thirdweb lida automaticamente com a transação → os tokens chegam → nenhuma taxa é paga pelo usuário!

---

Passo 8: Exibir saldo e funcionalidade de logout

Ler o saldo do token

import { useReadContract } from "thirdweb/react";
import { getBalance } from "thirdweb/extensions/erc20";

const { data: tokenBalance } = useReadContract(getBalance, {
  contract,
  address: account.address,
});

<div>Saldo: {tokenBalance?.displayValue} RPS</div>

Adicionar botão de logout

import { useDisconnect, useActiveWallet } from "thirdweb/react";

const wallet = useActiveWallet();
const { disconnect } = useDisconnect();

<button onClick={() => disconnect(wallet)}>Sair</button>

---

Teste o fluxo completo em dispositivos móveis

No seu celular, abra o Telegram, pesquise pelo seu bot e clique no link do Mini App:

1. Insira seu e-mail → verifique → a carteira é gerada
2. Jogue o jogo → se vencer, clique em "Reivindicar Recompensa"
3. Os tokens chegam e seu saldo é atualizado
4. Nenhuma operação de plug-in ou assinatura necessária!

---

FAQ

Este plano é gratuito?

Todas as funcionalidades da thirdweb usadas neste tutorial estão dentro do plano gratuito, incluindo criação de carteira, interação com contratos, abstração de conta, etc. Se você precisar fazer login diretamente com uma conta do Telegram (sem verificação por e-mail), precisará fazer upgrade para um plano pago.

Como evitar que os usuários reivindiquem tokens repetidamente?

Você pode adicionar lógica ao seu contrato inteligente para limitar o número de reivindicações por endereço, ou usar o recurso Claim Conditions da thirdweb para definir regras como listas de permissão, janelas de tempo, etc.

Posso mudar para outra blockchain?

Absolutamente. Basta substituir a cadeia desejada (como Polygon, Arbitrum, etc.) nas configurações de getContract e accountAbstraction. A thirdweb suporta mais de 900 cadeias compatíveis com EVM.

Como implantar em um ambiente de produção?

Implante seu código em plataformas como Vercel, Netlify, etc., obtenha um domínio oficial e substitua o URL do Web App no BotFather.

Patrocinar taxas de Gas é caro?

O plano gratuito da thirdweb oferece uma certa quantidade de Gas patrocinado por mês, o que é suficiente para projetos pequenos ou testes. Se o tráfego for alto, você pode fazer upgrade de acordo com suas necessidades.

---

Conclusão

Com este tutorial, você aprendeu como construir um aplicativo Web3 completo dentro do Telegram – desde a criação de carteiras, lógica de jogo até a distribuição de tokens, tudo integrado perfeitamente. Essa stack de tecnologia não é apenas adequada para mini-jogos, mas também pode ser expandida para cenários DeFi, NFTs, aplicativos sociais e muito mais.