Um amigo te manda um card: «falta um voto, toca para colocar o seu». Você toca. O miniprograma abre na home, o voto sumiu e você precisa achar o grupo de novo do zero. Nada quebrou. O botão funcionou. O link só esqueceu o que carregava.

Já publicamos esse defeito mais de uma vez, e raramente é um botão quebrado. É um link pensado como endereço quando devia ser uma frase: abra isto, neste estado, para esta pessoa, deste lugar. Anos de URLs da web nos treinaram a tratar links como lugares. Dentro de um super app, um link sem contexto mal é um link: é só um jeito de abrir a porta da frente.

Um link é uma frase, não um endereço

Cada ponto de entrada te entrega um envelope pequeno de contexto antes da primeira tela renderizar. Há o que você controla: um id de produto, um id de grupo, uma tag de campanha, quem compartilhou. E há o que o anfitrião acrescenta, como um valor de cena que diz se você chegou por um adesivo de QR, por um chat ou por um atalho salvo. O WeChat chama isso de valores de cena; o Alipay tem o equivalente; um bot do Telegram recebe um payload start no primeiro /start. Nomes diferentes, mesma ideia: o anfitrião já sabe algo de como você chegou, e vale ler isso em vez de adivinhar.

O movimento prático é fazer o compartilhamento guardar estado. Quando alguém compartilha da tela de um produto, o card devia levar aquele id e deixar quem recebeu naquela tela exata, não na home com um vago «olha isso». Quando uma campanha traz gente, a primeira tela devia ser o que a campanha prometeu. Parece óbvio até você auditar um app real e encontrar metade dos cards apontando para a rota raiz.

Uma regra que aprendemos apanhando: deixe identidade, preço e permissão fora desses parâmetros. Tudo que vai num link é fornecido pelo cliente. Trate o payload como dica de para onde ir, e deixe o servidor decidir o que a pessoa pode mesmo ver.

Dois caminhos, um mesmo payload

É aqui que quase todo mundo tropeça. Não existe uma forma de entrar, existem duas, e elas se comportam diferente.

O cold start, com o miniprograma sem rodar, entrega o payload ao ciclo de vida de inicialização. Você lê uma vez, decide a rota e renderiza a tela de destino. Beleza. Mas se o miniprograma já estava aberto em segundo plano, um link novo não reinicia nada: ele retoma. O payload fresco chega no hook de retomada, a página atual não recarrega, e se você não tratar esse hook de propósito, a pessoa fica na tela que deixou dez minutos atrás. É aquele defeito de «toquei e não aconteceu nada», e como não é um crash, passa pelos testes.

Então trate os dois: parseie e roteie na inicialização, e parseie e roteie de novo toda vez que o app volta para a frente. A mesma função pequena, dois pontos de chamada. Pule o segundo e mais ou menos metade dos seus links profundos não faz nada, em silêncio.

EntradaO que carregaEm que tela pousaOnde se perde
Card compartilhado de um chatId do produto, id do grupo, quem compartilhouAquele produto ou grupo exato, com o estado aplicadoO card aponta para a home; o contexto nunca sai de quem enviou
QR com valor de cenaId da cena, campanha, ponto de colocaçãoUma primeira tela específica da campanhaO parâmetro de cena some quando o link é copiado para fora do anfitrião
Link de anúncio ou SMSCampanha, criativo, um payload curtoA oferta que o anúncio realmente prometeuO navegador externo não abre o esquema do anfitrião; o toque morre ali
Aviso ou mensagem de assinaturaUm motivo e uma tela de destinoUma tela concreta, não a caixa de entradaLimites de template descartam o campo custom; abre uma página genérica
Miniprograma já abertoUm payload novo na retomadaO destino novo, decidido na retomadaO hook de retomada não é tratado e a tela antiga fica parada

Onde a atribuição morre em silêncio

Agora a parte honesta. Presuma que algo vai se perder. Payloads são truncados: limite de tamanho, caracteres especiais, uma etapa de codificação que você não esperava, um anfitrião que reescreve o link ao reenviar. Os anfitriões também limitam a abertura externa. Um link dentro de um navegador ou SMS costuma precisar de um esquema específico, ser interceptado ou mostrar uma confirmação antes de abrir; e um link criado para um anfitrião simplesmente não abre em outro. Adoraríamos uma URL que funcionasse em todo lugar, mas nenhum anfitrião quer isso, então pare de desenhar para ela. Faça uma entrada por anfitrião e guarde um fallback web sem graça para o resto.

A atribuição pode quebrar em qualquer ponta. Quem envia edita a rota. Quem recebe copia o link para outro chat e o id da cena não acompanha. Uma segunda abertura sobrescreve os parâmetros de cold start que você ia registrar. Alguém tira um print do QR em vez de escanear. Você vai acabar com um balde de «origem desconhecida» por mais cuidado que tenha, e fingir que ele não existe só produz painéis confiantes e errados.

Há também o custo de segurança. Se você confiou num id de usuário ou num flag de admin da query string porque isso facilitava o roteamento, entregou um bug de autorização de graça. Verifique no servidor, sempre. O link diz onde pousar; nunca deve dizer quem é a pessoa.

Antes de desenhar o próximo card, teste uma coisa: abra o miniprograma, mande para segundo plano e toque um link novo de outra conversa. Se ele pousar na tela antiga, você acabou de achar o defeito que quase todo mundo publica. Trate o caminho de retomada, mantenha o payload curto e sem graça, verifique no servidor tudo que for sensível — e aceite que o id de cena que alguém colou num grupo é um buraco com o qual se convive, não um que se fecha.

Fontes