Mascote em Telegram Mini App: tela de carregamento, temas e vibração

Posso personalizar a tela de carregamento de uma Telegram Mini App?

Em parte. A página de Mini Apps do Telegram diz que os apps "podem personalizar a tela de carregamento, adicionando o próprio ícone e cores específicas para os temas claro e escuro", configurados no @BotFather em /mybots, seu bot, Bot Settings, Configure Mini App, Enable Mini App. A documentação da API do Telegram lista o que é armazenado, no objeto botAppSettings:

Nenhuma das páginas menciona animação para o placeholder, então trate-o como uma imagem estática. A tela de carregamento termina quando o seu código decide. O Telegram descreve ready() como o método que "informa ao app do Telegram que a Mini App está pronta para ser exibida", e acrescenta: "Depois que esse método é chamado, o placeholder de carregamento é escondido e a Mini App é exibida. Se o método não for chamado, o placeholder só será escondido quando a página estiver totalmente carregada."

Como passar do placeholder estático para uma intro animada?

Faça as duas telas parecerem uma só. O placeholder aparece enquanto a página e o arquivo Rive carregam; quando o arquivo estiver pronto, chame ready() e comece a intro no mesmo fundo, a partir da mesma pose.

1. Desenhe o SVG na pose de repouso (ou uma silhueta simples dela), centralizado, para que o primeiro frame da intro continue de onde o placeholder parou.
2. Use cores idênticas. Defina os fundos claro e escuro do BotFather com as cores que sua página usa como fundo em cada tema.
3. Chame ready() no onLoad do Rive, depois toque a intro e então troque para o personagem interativo.
4. Não deixe o placeholder na tela por muito tempo. O Telegram recomenda chamar ready() "o quanto antes", então defina um timeout curto, à sua escolha, e pule a intro se o arquivo demorar.

<head>
  <script src="https://telegram.org/js/telegram-web-app.js?64"></script>
  <style>
    body { margin: 0; background: var(--tg-theme-bg-color, #ffffff); }
    #mascot { width: 220px; height: 220px; display: block; margin: 48px auto 0; }
  </style>
</head>
<body>
  <canvas id="mascot" role="img" aria-label="Mascot"></canvas>
  <script src="/vendor/rive-canvas-2.47.1.js"></script>
  <script src="/app.js"></script>
</body>

const tg = window.Telegram.WebApp;
const canvas = document.getElementById("mascot");
const INTRO_MS = 2600;              // the launch intro fires no end event
let shown = false;

function show() {                    // hide Telegram's placeholder exactly once
  if (shown) return;
  shown = true;
  tg.ready();
}

const intro = new rive.Rive({
  src: "/mascot.riv",
  canvas,
  stateMachine: "LaunchStateMachine",
  autoplay: false,                   // start only when the app is visible
  onLoad: () => {
    intro.resizeDrawingSurfaceToCanvas();
    show();
    intro.play();
    setTimeout(startCharacter, INTRO_MS);
  },
});

// Don't hold Telegram's placeholder if the file is slow: skip the intro.
setTimeout(() => { if (!shown) { show(); startCharacter(); } }, 1500);

let mascot;
function startCharacter() {
  if (mascot) return;
  intro.cleanup();
  mascot = new rive.Rive({
    src: "/mascot.riv",
    canvas,
    stateMachine: "CharacterViewModelMachine",
    autoplay: true,
    autoBind: true,
    onLoad: () => mascot.resizeDrawingSurfaceToCanvas(),
  });
}

A intro aqui toca a LaunchStateMachine, que roda uma vez e não tem evento de fim, então um timer com a duração da intro passa para o personagem. Hospedar você mesmo o runtime e o WASM (com RuntimeLoader.setWasmUrl()) mantém o primeiro carregamento no seu próprio domínio, em vez de uma CDN.

Como adaptar o mascote aos temas claro e escuro do Telegram?

Uma Mini App recebe o tema atual do usuário em Telegram.WebApp.themeParams: bg_color, secondary_bg_color, text_color, hint_color, link_color, button_color e outros, todos em #RRGGBB. Os mesmos valores estão disponíveis como variáveis CSS, como var(--tg-theme-bg-color), e colorScheme é "light" ou "dark".

• Fundo: use var(--tg-theme-bg-color) na página. Um canvas do Rive é transparente, então o personagem fica sobre o fundo do tema, seja ele qual for, sem caixa em volta.
• Mudanças ao vivo: o evento themeChanged "ocorre sempre que as configurações de tema são alteradas no app do Telegram do usuário (inclusive ao mudar para o modo noturno)".
• Cabeçalho e fundo: setHeaderColor() e setBackgroundColor() aceitam #RRGGBB ou as palavras-chave bg_color e secondary_bg_color.

Fallbacks em vídeo são mais complicados. Um GIF ou MP4 tem fundo sólido, que não combina com todos os temas, e um WebM transparente precisa de uma alternativa .mov HEVC com canal alfa para o WebKit da Apple; o guia de vídeo com fundo transparente explica essa dupla. Esse é um dos motivos pelos quais um canvas Rive é a escolha mais simples dentro do Telegram.

Como adicionar feedback háptico às reações do mascote?

Telegram.WebApp.HapticFeedback chegou na Bot API 6.1 com três métodos:

• impactOccurred(style) com light, medium, heavy, rigid ou soft.
• notificationOccurred(type) com error, success ou warning.
• selectionChanged(), que o Telegram recomenda usar só quando uma seleção muda, não quando ela é confirmada.

Dispare o háptico na mesma chamada do trigger da animação, para que os dois aconteçam juntos:

const haptics = tg.isVersionAtLeast("6.1") ? tg.HapticFeedback : null;

function react(kind) {               // kind: "success" | "error" | "yes" | "no"
  mascot.viewModelInstance.trigger(kind).trigger();
  if (!haptics) return;
  if (kind === "success" || kind === "error") haptics.notificationOccurred(kind);
  else haptics.impactOccurred("light");
}

tg.onEvent("themeChanged", () => {
  document.body.style.background = tg.themeParams.bg_color || "";
});
tg.onEvent("deactivated", () => mascot && mascot.pause());   // minimized
tg.onEvent("activated", () => mascot && mascot.play());

Segundo o Telegram, o app "pode reproduzir os hápticos adequados", então trate-os como um extra, não como o único feedback. O exemplo também pausa o personagem em deactivated (eventos da Bot API 8.0 para um Mini App minimizado) e retoma em activated.

Um mascote Rive roda com fluidez dentro do Telegram?

Um Mini App é uma página web exibida dentro do Telegram, então valem as regras de sempre da web.

• Tamanho do download: na versão 2.47.1, o runtime de canvas tem cerca de 628 KB de JavaScript mais cerca de 2,2 MB de WASM antes da compressão. Sirva esses arquivos com cache de longa duração para que as aberturas seguintes sejam instantâneas.
• Um único personagem: um canvas com humores é mais leve do que várias animações.
• Mudanças de viewport: o Mini App pode ser arrastado para ficar mais alto ou mais baixo. O evento viewportChanged do Telegram passa isStateStable; redimensione a superfície de desenho quando ele for true, e não a cada frame do arraste.
• Movimento reduzido: verifique prefers-reduced-motion e mostre uma pose estática se estiver ativado.

O mesmo personagem pode virar figurinhas do Telegram?

Sim, como figurinhas em vídeo. As figurinhas em vídeo do Telegram são arquivos WEBM codificados em VP9, com um dos lados medindo exatamente 512 px, no máximo 3 segundos, até 30 fps e 256 KB, sem áudio. Um WebM transparente do personagem é convertido com um único comando ffmpeg, explicado em Figurinhas em vídeo do Telegram a partir de uma animação de personagem.

As figurinhas animadas .TGS são outro formato: um subconjunto do Lottie feito com formas vetoriais do After Effects. Um arquivo Rive ou um vídeo renderizado não pode virar .TGS diretamente.

O que o Charmotion oferece para um Mini App?

A partir de uma imagem de personagem ou logo, o Charmotion cria um .riv com as duas peças que esta página usa: LaunchStateMachine, uma intro de abertura de cerca de 2,6 segundos que termina na pose de repouso e não dispara evento de fim, e CharacterViewModelMachine, com um número mood de 0 a 9 e os triggers success, error, yes, no, enter e exit. O conjunto também tem WebM transparente e MOV HEVC (boas fontes para figurinhas em vídeo), MP4, vídeo 9:16 e um GIF, além de código para web. Ele não exporta .TGS. O conjunto completo, com .riv e vídeo transparente, está em todos os planos pagos (a partir de US$ 20/mês).

Como adicionar um mascote animado na abertura de um Telegram Mini App

1. Desenhe o placeholder. Exporte a pose de repouso do personagem como um SVG simples e centralizado.
2. Configure o BotFather. Abra Bot Settings, Configure Mini App, envie o SVG e defina as cores de fundo e de cabeçalho para os temas claro e escuro, combinando com a sua página.
3. Carregue o script do Telegram. Inclua o telegram-web-app.js no head, antes dos outros scripts.
4. Carregue o arquivo Rive. Crie a instância da intro com a reprodução automática desligada, chame Telegram.WebApp.ready() no onLoad e depois dê play.
5. Faça a transição. Depois da duração da intro, inicie o personagem interativo, e pule a intro se o carregamento demorar demais.
6. Adicione tema e hápticos. Use --tg-theme-bg-color, escute o evento themeChanged e combine as reações com HapticFeedback.

Perguntas frequentes

O placeholder do Telegram Mini App pode ser um SVG animado?

O Telegram documenta o placeholder como um logo em SVG e não diz nada sobre animação, então conte com uma imagem estática. Coloque o movimento no seu web app: chame ready() quando o arquivo Rive tiver carregado e comece a intro a partir da mesma pose e da mesma cor de fundo.

O que acontece se um Mini App nunca chamar Telegram.WebApp.ready()?

O Telegram mantém o placeholder de carregamento até a página carregar por completo e depois o esconde. Isso pode acontecer mais tarde do que o necessário se a sua página carregar imagens ou scripts grandes. Chame ready() assim que a interface essencial, incluindo o primeiro frame do mascote, puder ser exibida.

Os hápticos do Telegram funcionam em todos os lugares?

Não há garantia. O HapticFeedback exige Bot API 6.1 ou posterior, então verifique isVersionAtLeast("6.1"), e a documentação do Telegram diz que o app pode reproduzir hápticos. Dispositivos sem motor de vibração não farão nada, então mantenha a reação visual como o feedback principal.

Respostas rápidas deste guia

• Posso personalizar a tela de carregamento de uma Telegram Mini App?

Fontes

• Telegram Mini Apps, Telegram
• Mini Apps on the Telegram API (botAppSettings), Telegram
• Stickers: requirements for static, animated and video stickers, Telegram
• Web (JS) runtime, Rive
• Rive parameters (web runtime), Rive
• Preloading WASM, Rive