Sistema de indicação React Native: guia completo em 1 dia

Passei 8 horas a codificar algo que não tem nada a ver com o produto em si. Nenhuma nova funcionalidade. Nenhuma correção de bug. Nenhuma otimização. Um sistema de referências completo — deep links Android, Play Store Install Referrer, recompensas acumuladas, notificações push em 6 idiomas — 22 ficheiros modificados, 1324 linhas adicionadas. Num só dia. Eis como construí um sistema de referências completo em React Native, as armadilhas técnicas a evitar e porque é o investimento de marketing mais rentável para um desenvolvedor solo.

Pontos-chave a reter:
- Um sistema de referências requer 3 fontes de captura (deep links web, Android App Links, Play Store Install Referrer) para cobrir todos os cenários de instalação.
- O Play Store Install Referrer é a fonte mais subestimada: ele captura o código mesmo que a instalação ocorra 3 dias após o clique.
- As recompensas acumuladas (fila de meses gratuitos) são mais motivadoras do que uma recompensa única, mas adicionam complexidade com o RevenueCat.
- A verificação do Android App Links é frágil: o SHA256 em assetlinks.json deve corresponder exatamente à chave de assinatura.

Por que um sistema de referências é o melhor investimento para um desenvolvedor solo?

Estou a desenvolver TAMSIV, um gestor de tarefas por voz para Android. Desenvolvedor solo, mais de 660 commits, 6 meses de trabalho. Tenho 12 testadores alfa na Play Store e preciso que esse número cresça — organicamente.

As opções clássicas de aquisição de utilizadores para uma aplicação móvel são dispendiosas:

• Publicidade paga: 1 a 5 EUR por instalação no Google Ads, sem garantia de retenção.
• ASO (App Store Optimization): longo prazo, resultados incertos sem orçamento de marketing.
• Influenciadores: fora do orçamento para um desenvolvedor solo.

A referência é diferente. Como mostra ReferralCandy, os utilizadores adquiridos por referência têm uma taxa de retenção 37% superior e um LTV (Lifetime Value) 16% mais elevado. A razão é simples: a recomendação de um amigo é a forma mais fiável de marketing.

O conceito é simples: cada utilizador tem um código de referência único. Tu partilhas. Quando alguém se regista com ele, ambos ganham 1 mês Pro gratuito. E isso acumula-se — 10 referências = 10 meses gratuitos, colocados em fila um após o outro.

Quais são as 3 fontes de captura indispensáveis para um sistema de referências Android?

A parte mais difícil não é gerar os códigos. É capturá-los de forma fiável. No Android, existem três cenários de instalação completamente diferentes, e cada um requer a sua própria mecânica de captura.

Fonte 1: Deep links via o site web

Quando alguém visita tamsiv.com/invite/CODE, o Next.js redireciona para a Play Store com o código de referência integrado. Este é o fluxo mais simples:

1. O utilizador A partilha o seu link tamsiv.com/invite/ABC123
2. O utilizador B clica — o Next.js deteta o código e redireciona para a Play Store
3. O código é passado via o parâmetro referrer do URL da Play Store
4. A aplicação recupera-o na instalação via a API Install Referrer

Fonte 2: Android App Links (abertura direta)

Se a aplicação já estiver instalada, tamsiv://invite/CODE abre-a diretamente. Este é o caso em que um utilizador existente partilha o seu código com alguém que já tem a aplicação. Isso requer:

• A configuração do AndroidManifest.xml com os intent-filters para o esquema tamsiv://
• Um ficheiro assetlinks.json no site para a verificação do domínio pelo Google
• O SHA256 exato da chave de assinatura no ficheiro assetlinks

É aqui que as coisas se complicam. A verificação do Android App Links é frágil. Se o SHA256 não corresponder exatamente — e há uma diferença entre a chave de depuração e a chave de produção — o link abre no navegador em vez da aplicação. Sem erro, sem mensagem. Simplesmente não funciona.

Fonte 3: Play Store Install Referrer

Esta é a fonte mais subestimada e mais poderosa. Quando alguém clica num link da Play Store com um parâmetro &referrer=CODE, o Android armazena essa string. Mesmo que a pessoa instale a aplicação 3 dias depois, ainda podemos ler o código.

A API Play Install Referrer permite recuperar este parâmetro no primeiro lançamento. A maioria dos tutoriais ignora este método, mas é a única forma fiável de capturar referências através de instalações diferidas.

Como implementar recompensas acumuladas com o RevenueCat?

A maioria dos sistemas de referências dá uma recompensa única. "Refere um amigo, ganha um mês gratuito." Fim. Nenhuma motivação para uma segunda referência.

Eu queria que as recompensas se acumulassem. Cada referência adiciona 30 dias de Pro, colocados em fila após a expiração do anterior. 10 referências = 10 meses gratuitos. O incentivo permanece constante.

A complexidade técnica com o RevenueCat

RevenueCat gere as subscrições do TAMSIV (Free, Pro, Team). Mas o RevenueCat não tem um conceito nativo de "crédito de tempo gratuito acumulado". É preciso geri-lo no lado do servidor:

1. Tabela de recompensas: cada referência cria uma linha em privat.referral_rewards com um status (pendente, ativo, usado, expirado).
2. Fila de espera: quando uma recompensa ativa expira, a próxima na fila é ativada automaticamente através de um cron job de backend.
3. Sincronização RevenueCat: o backend usa a API RevenueCat para conceder um promotional entitlement de 30 dias, renovado automaticamente se outras recompensas estiverem pendentes.
4. Verificação de duplicados: um utilizador não pode referir a mesma pessoa duas vezes. O código é verificado no backend antes de conceder a recompensa.

Um simples "dá 1 mês gratuito" é fácil. Colocar várias recompensas em fila requer gerir as datas de início, fim e a relação com o RevenueCat. Esta foi a parte que demorou mais tempo no dia.

Como enviar notificações push de referência em 6 idiomas?

Quando alguém usa o teu código, recebes uma notificação push. No teu idioma. Porque o TAMSIV fala 6 idiomas, o backend verifica a preferência linguística do referenciador antes de enviar via FCM (Firebase Cloud Messaging).

O modelo de notificação é traduzido para os 6 idiomas:

• FR: "Ton ami {name} a utilise ton code ! Tu gagnes 1 mois Pro gratuit."
• EN: "Your friend {name} used your code! You earn 1 free Pro month."
• DE, ES, IT, PT: equivalentes traduzidos

É um detalhe, mas é o tipo de detalhe que torna o sistema profissional. Receber uma notificação de referência num idioma que não compreendes mata a emoção do momento. A notificação deve ser tão natural quanto uma mensagem de um amigo.

Quais são os erros técnicos a evitar com os deep links Android?

Após este dia de desenvolvimento, aqui estão as armadilhas que encontrei:

Armadilha 1: o ficheiro assetlinks.json

O ficheiro .well-known/assetlinks.json deve ser servido exatamente no local correto (https://tamsiv.com/.well-known/assetlinks.json) com o SHA256 exato da tua chave de assinatura. Atenção: a chave de depuração e a chave de produção têm SHA256 diferentes. O Google Play App Signing adiciona uma camada adicional — tu deves usar o SHA256 do certificado de upload, não o de signing.

Armadilha 2: o caching dos intent-filters

O Android armazena em cache os intent-filters. Se corrigires o teu assetlinks.json, o dispositivo pode continuar a usar a verificação antiga por horas. Solução: desinstalar completamente a aplicação, limpar a cache do Chrome e reinstalar.

Armadilha 3: o referrer URL encoding

O parâmetro referrer do URL da Play Store deve ser corretamente codificado. Os caracteres especiais no código (se usares UUIDs) devem ser escapados. Perdi 30 minutos por causa de um + num código que foi decodificado como um espaço.

Que resultados esperar de um sistema de referências para uma aplicação em alfa?

Com 12 testadores alfa, os resultados absolutos são modestos. Mas o sistema está pronto para escalar. O ROI é medido em duas dimensões:

• Custo de aquisição: 0 EUR por utilizador adquirido via referência (vs 1-5 EUR em publicidade paga).
• Qualidade dos utilizadores: um utilizador referenciado já conhece o conceito graças à recomendação — a taxa de retenção é mecanicamente superior.
• Efeito viral: cada novo utilizador pode ele próprio referenciar — o custo marginal de aquisição tende para zero.

Para um desenvolvedor solo sem orçamento de marketing, este é exatamente o tipo de mecanismo que permite crescer sem pagar. É complementar à estratégia de internacionalização como canal de aquisição que implementei.

Qual é o balanço técnico deste dia de desenvolvimento?

Em números:

• 22 ficheiros modificados (backend, frontend, website, manifesto Android)
• 1 324 linhas adicionadas
• 1 dia de trabalho concentrado (8 horas)
• 6 idiomas suportados para as notificações
• 3 fontes de captura para cobertura máxima

O sistema toca todas as camadas da arquitetura: o monorepo (frontend, backend, website), a base de dados (Supabase), as notificações (FCM) e as subscrições (RevenueCat). É isso que torna a funcionalidade complexa — não está isolada num módulo, atravessa tudo.

Perguntas frequentes

O Play Store Install Referrer funciona em todos os dispositivos Android?

Sim, desde que a Play Store esteja atualizada (versão 8.3.73+, ou seja, >99% dos dispositivos ativos). A API é fornecida pelo Google através da biblioteca com.android.installreferrer. Nos raros dispositivos sem Play Services (Huawei AppGallery), é necessário um fallback.

Quanto tempo o referrer é mantido pela Play Store?

De acordo com a documentação do Google, o referrer é mantido por 90 dias após o clique. Isso é mais do que suficiente para capturar instalações diferidas — mesmo que o utilizador espere várias semanas antes de instalar a aplicação.

Como evitar abusos do sistema de referências (contas múltiplas)?

Três mecanismos de proteção: (1) verificação de e-mail único — um e-mail só pode receber uma recompensa de referência, (2) rate limiting — máximo de 5 referências por hora por referenciador, (3) verificação no backend — o código é válido e o referenciado nunca foi referenciado antes. O sistema de rate limiting global do TAMSIV protege contra tentativas de abuso.

O RevenueCat suporta nativamente os promotional entitlements?

Sim, via API REST (POST /subscribers/{app_user_id}/entitlements/{entitlement_id}/promotional). Tu podes conceder um entitlement por uma duração definida (30 dias no nosso caso). No entanto, a gestão da fila de espera (acumulação de recompensas) deve ser feita no lado do servidor — o RevenueCat só gere o entitlement ativo.

É necessário um backend para um sistema de referências ou pode-se fazer tudo no lado do cliente?

Um backend é indispensável para a segurança. Toda a lógica de validação (código válido, utilizador elegível, anti-fraude) deve estar no servidor. O frontend limita-se a enviar o código e a receber o resultado. A geração de códigos, a atribuição de recompensas e o envio de notificações são feitos exclusivamente no backend.