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.
| Entrada | O que carrega | Em que tela pousa | Onde se perde |
|---|---|---|---|
| Card compartilhado de um chat | Id do produto, id do grupo, quem compartilhou | Aquele produto ou grupo exato, com o estado aplicado | O card aponta para a home; o contexto nunca sai de quem enviou |
| QR com valor de cena | Id da cena, campanha, ponto de colocação | Uma primeira tela específica da campanha | O parâmetro de cena some quando o link é copiado para fora do anfitrião |
| Link de anúncio ou SMS | Campanha, criativo, um payload curto | A oferta que o anúncio realmente prometeu | O navegador externo não abre o esquema do anfitrião; o toque morre ali |
| Aviso ou mensagem de assinatura | Um motivo e uma tela de destino | Uma tela concreta, não a caixa de entrada | Limites de template descartam o campo custom; abre uma página genérica |
| Miniprograma já aberto | Um payload novo na retomada | O destino novo, decidido na retomada | O 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
- Android Developers — App Links — como a plataforma decide qual app fica com um link recebido.
- WeChat — documentação para desenvolvedores de miniprogramas — valores de cena, opções de inicialização e onde os parâmetros de entrada aparecem.
- Telegram — Bot API — payloads de link profundo que chegam na primeira abertura.
- Apple Developer — documentação da plataforma — como um anfitrião limita links externos e os links universais.