Para desenvolvedores que desejam entrar no ecossistema do Telegram, os Mini Apps do Telegram são, sem dúvida, um excelente ponto de partida. Eles não apenas alcançam milhões de usuários, mas também podem ser profundamente integrados a funcionalidades como pagamentos e bots. No entanto, muitos ficam travados no início: qual stack de tecnologia devo usar? Como configurar o ambiente de desenvolvimento? Como fazer um projeto local realmente rodar no Telegram?
Este artigo usará um caso real de aplicativo de delivery de comida (semelhante ao Durer King) como exemplo para guiá-lo no processo de desenvolvimento do zero. Seja você um desenvolvedor front-end ou um gerente de produto que deseja explorar o ecossistema do Telegram, este artigo o ajudará a começar rapidamente.
O Telegram não é apenas uma ferramenta de mensagens instantâneas; seu ecossistema aberto oferece um enorme espaço para a imaginação dos desenvolvedores:
Usando o exemplo deste artigo, construiremos um sistema completo de delivery de comida que inclui Web App + Telegram Bot + Funcionalidade de Pagamento. Utilizaremos React.js para o front-end, Node.js para o back-end e integraremos a funcionalidade de pagamento oficial do Telegram.
Antes de começarmos, precisamos definir nossa solução técnica:
É importante notar que os Mini Apps do Telegram exigem o uso do protocolo HTTPS, o que significa que você também precisará configurar um certificado SSL durante o desenvolvimento local. Detalharemos como resolver esse problema mais adiante.
Todos os Mini Apps do Telegram precisam ser iniciados por meio de um Bot. Vamos criar um bot usando o BotFather:
@BotFather no Telegram e abra a conversa./newbot.Esse token funciona como uma chave para conectar seu aplicativo aos servidores do Telegram.
Em seguida, usaremos o Telegram Mini App SDK oficial para configurar rapidamente o projeto:
# Criar projeto React + TypeScript
npx create-react-app my-telegram-app --template typescript
cd my-telegram-app
# Instalar o SDK do Telegram
npm install @twa-dev/sdk
O SDK fornece APIs ricas, como obter informações do usuário, chamar interfaces de pagamento, enviar mensagens, etc. Após a instalação, abra o VS Code e inicie o projeto:
npm start
Neste ponto, você verá o projeto sendo executado em http://localhost:3000, mas isso não é suficiente - o Telegram exige que todos os Mini Apps sejam acessados via HTTPS.
Muitos desenvolvedores ficam travados nesta etapa: como usar HTTPS durante o desenvolvimento local? Existem duas soluções:
Modifique o script de inicialização em package.json:
"scripts": {
"start": "HTTPS=true react-scripts start"
}
Isso fará com que o projeto use automaticamente um certificado autoassinado e seja executado em https://localhost:3000.
Se você precisar testar remotamente (por exemplo, em um telefone), pode usar o ngrok para mapear seu serviço local para a internet pública:
ngrok http 3000
O ngrok gerará um endereço HTTPS público. Você pode copiá-lo e usá-lo no Telegram.
Agora precisamos informar ao Telegram onde está o ponto de entrada do Mini App deste Bot. Volte ao BotFather:
/mybots e selecione o Bot que você acabou de criar.Bot Settings → Menu Button.https://your-ngrok-url.io).Após concluir, abra seu Bot e clique no botão Menu na parte inferior, e o Mini App será aberto dentro do Telegram!
Limpe o código padrão do React, mantendo a estrutura principal:
import { useEffect } from 'react';
import './App.css';
function App() {
useEffect(() => {
// Inicializar o Telegram SDK
const tg = (window as any).Telegram.WebApp;
tg.ready();
console.log('Telegram WebApp carregado');
}, []);
return (
<div className="App">
<h1>Olá Telegram!</h1>
</div>
);
}
export default App;
Salve e atualize o Telegram. Você deverá ver a página "Olá Telegram!" e, no console, o log indicando que o SDK foi inicializado com sucesso.
Para garantir uma exibição consistente em diferentes dispositivos, é recomendável usar Normalize.css e definir estilos globais:
/* App.css */
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
background-color: var(--tg-theme-bg-color);
color: var(--tg-theme-text-color);
}
O Telegram fornece um conjunto de variáveis de tema, usando essas variáveis permitirá que seu aplicativo se adapte automaticamente ao modo escuro/claro do usuário.
Após concluir as etapas acima, você terá um framework funcional de Mini App do Telegram. Em seguida, você pode:
Se você precisar de um navegador anti-associação em cenários como gerenciamento de várias contas ou testes automatizados, considere usar o MasLogin. Ele pode ajudá-lo a simular diferentes ambientes durante o desenvolvimento e teste, evitando riscos de conta.
Se você usar a versão gratuita do ngrok, o endereço mudará a cada reinicialização. Recomenda-se:
As APIs comumente usadas incluem:
window.Telegram.WebApp.ready() - Inicializaçãowindow.Telegram.WebApp.MainButton - Controle do botão principalwindow.Telegram.WebApp.initData - Obter informações do usuáriowindow.Telegram.WebApp.close() - Fechar o Mini AppPara documentação detalhada, consulte a API WebApp do Telegram.
O Telegram fornece um ambiente de sandbox. Você pode usar credenciais de pagamento de teste para depuração. Consulte os documentos oficiais de pagamento para o fluxo específico.
Através deste artigo, você aprendeu o fluxo de desenvolvimento principal dos Mini Apps do Telegram. Lembre-se: primeiro, faça a versão mínima viável funcionar e, em seguida, itere e otimize gradualmente. Comece a experimentar agora e crie seu próprio aplicativo no ecossistema do Telegram!
Esboço
