Indicações no App

Permita que os usuários do seu app virem indicadores dentro do próprio app. Com uma chamada ao SDK você mostra uma tela Indique um amigo pronta, dá a cada usuário o próprio código e link e vê quantos amigos ele trouxe, para recompensá-lo no app com créditos, tokens ou tempo grátis.

Indicadores no app são afiliados normais. Eles têm acesso ao painel, aparecem na sua lista de afiliados e podem ganhar comissão, recompensas no app ou ambos.

Como Funciona

1. Seu app inscreve o usuário. O SDK envia o e-mail e o nome do usuário. O Insert Affiliate cria a conta de afiliado, o código curto e (para empresas com Insert Links) o link.
2. O usuário compartilha. A tela pronta mostra o código e o link com os botões "Copy" (Copiar) e "Share" (Compartilhar). O compartilhamento usa o menu de compartilhamento do próprio celular.
3. Os amigos são atribuídos normalmente. Instalações, eventos e compras do celular do amigo são atribuídos ao indicador como a qualquer outro afiliado.
4. Você recompensa. O SDK, um webhook e a API Pública informam uma contagem de indicações. Quando ela aumentar, conceda a recompensa.

Configure no Painel

1. Acesse Configurações → Indicações no app
2. Ative Permitir que usuários virem indicadores dentro do app
3. Escolha O que conta como indicação:
   • Um amigo faz uma compra (recomendado): conta compras novas, não renovações
   • Um amigo conclui um evento no app: conta um evento rastreado como signup. Informe o nome do evento que seu app envia.
   • Um amigo instala o app: conta instalações e aberturas atribuídas. É o mais fácil de fraudar, veja quão segura é a contagem e Regras das lojas.
4. Se quiser, ative Exigir código por e-mail para novos indicadores caso seu app não verifique os e-mails por conta própria
5. Defina o Título, a Cor do botão e o Texto da recompensa exibidos na tela pronta. A pré-visualização é atualizada enquanto você digita.
6. Clique em Salvar configurações de indicação

Alterações no texto e na cor da tela chegam ao seu app na hora, sem precisar publicar uma nova versão.

Adicione ao Seu App

Todos os SDKs têm os mesmos métodos. O caminho mais rápido é a tela pronta, que cuida da inscrição, do código por e-mail e do compartilhamento.

React Native

import { ReferAFriend } from 'insert-affiliate-react-native-sdk';

<ReferAFriend
  visible={showReferral}
  onClose={() => setShowReferral(false)}
  email={currentUser.email}
  name={currentUser.name}
/>

Swift (iOS)

InsertAffiliateSwift.showReferAFriend(
  from: viewController,
  options: ReferAFriendOptions(email: currentUser.email, name: currentUser.name)
)

Flutter, Android (Java/Kotlin), Unity e JavaScript usam os mesmos nomes de métodos. Veja o README de cada SDK para a sintaxe exata: Swift, Android, React Native, Flutter, Unity, JavaScript.

Mudando o texto da tela

A tela vem com textos em inglês. Seu app pode substituir qualquer rótulo dela com a opção strings, passada quando a tela é aberta. É assim que você traduz a tela, já que não fornecemos traduções, e também que muda as palavras para combinar com o seu app.

<ReferAFriend
  visible={showReferral}
  onClose={() => setShowReferral(false)}
  strings={{
    emailLabel: 'E-mail',
    joinButton: 'Pegar meu link',
    codeSentNotice: 'Enviamos um código de 6 dígitos para {email}.',
    shareButton: 'Compartilhar',
    premiumUntil: 'Premium grátis até {date}',
  }}
/>

Regras válidas para todos os SDKs:

• Substitua só o que quiser. Uma chave que você deixar de fora, ou definir como texto vazio, mantém o nosso texto em inglês. Uma chave que não conhecemos é ignorada.
• Mantenha os marcadores. {email} em codeSentNotice e {date} em premiumUntil são preenchidos na hora de exibir o texto.
• Título e texto da recompensa não estão em strings. Eles vêm do seu painel, e cada SDK tem a própria opção para substituí-los por chamada.

As chaves que a maioria dos SDKs tem em comum:

A tela de cada SDK é um pouco diferente, então cada README traz a lista completa com os nossos textos em inglês. O SDK de JavaScript separa copyCodeButton e copyLinkButton e não tem o título "Your code", e os SDKs de Android, Unity, Flutter e React Native acrescentam chaves para rótulos próprios, como um título "Your link" separado ou o texto de exemplo dentro dos campos.

Um código de erro para o qual não temos uma chave usa errorServer.

Estilizando a tela

O mesmo objeto de opções também define a aparência, por chamada:

• Cor: primaryColor, um valor #RRGGBB que substitui a cor de botão do seu painel.
• Fonte: fontName no Swift, fontFamily no React Native, no Flutter e no JavaScript, font no Unity e setTypeface no Android.
• Raio dos cantos: cornerRadius para os botões, os campos e a própria tela.
• Texto de compartilhamento: shareMessage, a mensagem que o compartilhamento já traz preenchida.

Criando sua própria tela

Prefere seu próprio design? Ignore a nossa tela e chame os métodos você mesmo. Eles são tudo o que a tela pronta usa.

Chame nesta ordem:

1. getReferralProgramConfig() quando a sua tela abrir. Se o programa não estiver ativo, não mostre a tela.
2. getMyAffiliateDetails() ao mesmo tempo. Se vierem dados, este dispositivo já está conectado, então vá direto para o estado de indicador.
3. Ainda não é indicador: peça e-mail e nome e chame createAffiliateForUser. created vai para o estado de indicador e verificationRequired vai para a etapa do código.
4. Precisa do código: peça o código de 6 dígitos e chame verifyAffiliateCode. Para enviar um novo código, chame createAffiliateForUser de novo.
5. Já é indicador: mostre o código curto e o link, referralCount, totalEarned e currency, e ofereça copiar e compartilhar.
6. Recompensas: rewardsGranted e premiumUntil cobrem o tempo premium grátis. rewardCodes traz os códigos das lojas, cada um com code, store e redeemUrl. Mostre só os do celular em que o usuário está, porque um código da App Store não pode ser resgatado no Android e um código do Google Play não pode ser resgatado no iPhone.
7. Erros: todo erro volta como um código, por exemplo PROGRAM_DISABLED, AFFILIATE_LIMIT_REACHED, INVALID_EMAIL, INVALID_CODE, TOO_MANY_CODES ou RATE_LIMITED, então você escreve as suas próprias mensagens.
8. setReferrerAccount quando o usuário assinar ou entrar depois, e signOutAffiliate() quando ele sair.

Duas coisas para saber antes de começar:

• Um resultado vazio não diz o motivo. getMyAffiliateDetails() não retorna nada tanto quando o dispositivo não está conectado quanto quando a requisição falhou. Consulte isUserAnAffiliate() depois para diferenciar: se ainda for verdadeiro, a requisição falhou e vale tentar de novo.
• Alguns auxiliares da tela são internos. Filtrar os códigos de recompensa por loja, montar o texto de compartilhamento e limpar o código digitado não são públicos, então a sua tela escreve os seus próprios. Cada um tem poucas linhas sobre o que os métodos já retornam, e shareReferralLink cobre o texto de compartilhamento.

redeemUrl e dashboardUrl vêm do nosso servidor, então confira se cada um começa com https:// antes de abrir.

Reinstalações e Celulares Novos

Quando um usuário vira indicador, o celular dele recebe um token de acesso privado que prova quem ele é. No iPhone ele fica no Keychain, então normalmente continua lá mesmo se o app for apagado e reinstalado.

Se o token for perdido (um celular novo ou uma reinstalação no Android), inscrever o mesmo e-mail de novo não libera o acesso imediatamente. Em vez disso:

1. createAffiliateForUser retorna verificationRequired e enviamos um código de 6 dígitos para o e-mail do usuário
2. O usuário digita o código e seu app chama verifyAffiliateCode
3. O celular é conectado de novo. Indicações, ganhos e painel continuam iguais.

A tela pronta mostra essa etapa automaticamente. Os códigos expiram em 10 minutos e deixam de funcionar após 5 tentativas erradas, e enviamos no máximo 3 códigos por hora para o mesmo e-mail (depois disso, createAffiliateForUser retorna TOO_MANY_CODES). Quem já é seu afiliado, incluindo criadores com painel, sempre confirma um código ao conectar um celular novo. Isso também impede que alguém veja as indicações de outra pessoa digitando o e-mail dela.

Recompensando Indicadores

Configure em Configurações → Indicações no app → Recompensas dos indicadores. Vale para cada novo indicador que entra pelo seu app:

• Comissão em dinheiro: sua comissão padrão, sem dinheiro (só recompensas) ou uma comissão diferente só para indicadores.
• Desconto do amigo: escolha um dos seus códigos de oferta para iOS, Android e web. Amigos que usam o link ou código de um indicador recebem esse desconto.
• Recompensa por cada indicação: Nada extra (só comissão), Tempo premium grátis, concedido automaticamente ou Eu mesmo recompenso.

referralCount conta cada amigo uma vez e só aumenta.

Tempo premium grátis, concedido automaticamente

Concedemos a recompensa pelo que você usa para compras, assim que uma indicação conta:

Diga quem é o indicador no seu sistema de compras, para recompensarmos a conta certa:

// Quando ele entra (app user ID do RevenueCat ou customer user ID do Adapty)
await createAffiliateForUser(email, name, { appUserId: revenueCatAppUserId });

// Ou depois, por exemplo quando assinar (Android: o token de compra do Play)
await setReferrerAccount({ appUserId, playPurchaseToken });

Se uma indicação chegar antes de o seu app enviar isso, a recompensa espera e é concedida assim que chegar.

No Android, envie o token de compra do Play do indicador assim que ele assinar. Sem ele, não sabemos que ele é assinante, então ele recebe um código promocional, e o Google não deixa quem já assinou antes resgatar um.

Códigos de oferta da App Store: criamos códigos de uso único para você com a sua chave do App Store Connect. Cada pessoa só pode resgatar um código por oferta, então escolha suas ofertas em ordem: a 2ª recompensa de um indicador vem da sua 2ª oferta, e assim por diante. A oferta define o que ele recebe, por exemplo um mês grátis. Cada indicador pode receber uma recompensa da App Store por oferta escolhida (até 20 ofertas). Depois de receber todas, as próximas recompensas aparecem como failed, então escolha ofertas suficientes ou recompense as demais você mesmo.

Códigos promocionais do Google Play: o Google não nos permite criar códigos promocionais, e só quem nunca assinou pode resgatar um. Por isso, assinantes têm a cobrança adiada e os demais recebem um código de uma lista que você envia:

1. No Play Console, abra Monetizar com o Google Play > Códigos promocionais e crie uma promoção de códigos de uso único para a sua assinatura, com um teste grátis de 3 a 90 dias. O Google permite 10.000 códigos por assinatura a cada trimestre.
2. Baixe o CSV e envie em Configurações > Indicações no app, com a data de término da promoção. Paramos de entregar códigos 2 dias antes dela.
3. Cada recompensa usa o próximo código não usado. Se acabarem, as recompensas esperam e são entregues até uma hora depois do próximo envio.

Recompensando você mesmo

Quão segura é a contagem? Depende do que você conta:

• Compras não podem ser falsificadas. Uma compra só conta depois de verificada contra o recibo da loja pela sua verificação de compras (App Store, Google Play, RevenueCat, Adapty e as demais), como qualquer venda de afiliado. Recompensas por compra são seguras, inclusive meses grátis.
• Cadastros e instalações são informados pelo seu app, então um app modificado ou chamadas automatizadas poderiam falsificá-los. Use-os para pequenos benefícios e conte compras para recompensas valiosas.

Para a configuração mais segura, conceda recompensas pelo seu servidor. Seu backend lê a contagem verificada pelo webhook ou pela API Pública, em vez de confiar no que o celular mostra.

Webhook: referral.created

Se você configurou webhooks, enviamos referral.created sempre que acontece algo que você conta como indicação:

{
  "event": "referral.created",
  "affiliate_id": "ia_45fee001",
  "email": "[email protected]",
  "deep_link": "https://myapp.link/ref/abc123",
  "short_code": "a1b2c3d4",
  "trigger": "purchase",
  "referral_count": 3,
  "reward_status": "not_automatic",
  "occurred_at": "2026-09-18T12:00:00.000Z"
}

Recompense até referral_count. Como é um total acumulado, você nunca recompensa duas vezes, e o próximo envio compensa qualquer um que você tenha perdido. Webhooks não são reenviados, então para ter o quadro completo consulte a API Pública, que sempre mostra a contagem atual.

reward_status informa o que aconteceu com a nossa recompensa automática quando a indicação foi registrada:

• granted: concedida
• not_automatic: não concedemos recompensa. Ou você escolheu Eu mesmo recompenso, então recompense agora, ou escolheu Nada extra (só comissão).
• waiting_for_account: ainda não sabemos a conta do indicador no seu sistema de compras, ou o seu sistema de compras ainda não tem registro dele. Tentamos de novo a cada hora, então isso se resolve sozinho assim que a conta existir.
• waiting_for_codes: estamos esperando a Apple gerar os códigos de oferta, ou você enviar mais códigos promocionais do Google Play. Tentamos de novo a cada hora.
• failed: não foi possível conceder a recompensa, por exemplo porque falta uma chave ou configuração. As causas mais comuns são não ter chave do App Store Connect nem ofertas configuradas (então indicadores no iPhone não podem ser recompensados), faltar o nome do entitlement ou do nível de acesso, e um indicador que já recebeu todas as ofertas configuradas.
• capped: acima do limite mensal, não recompense esta

Ele é enviado uma vez, quando a indicação é registrada. Se uma recompensa em espera for concedida depois, nenhum segundo webhook é enviado.

API Pública

GET /public/v1/affiliates/{identifier} (o e-mail ou o código curto do afiliado) inclui um objeto referrals com trigger (o que o seu programa conta), referralCount, installCount, eventCount e purchaseCount. A API Pública está disponível no plano Enterprise.

Autoindicações e limites

• Cada amigo conta uma vez. Instalações e eventos são associados ao celular do amigo, então um amigo que se cadastra duas vezes é uma indicação. Compras são associadas à conta do amigo no app (o app user ID do RevenueCat ou o customer user ID do Adapty). Sem ela, cada compra é associada separadamente, então um amigo que compra dois produtos diferentes pode contar duas vezes.
• Uma indicação precisa de um amigo identificável. Uma instalação ou um evento que chega sem ID do dispositivo não é contado.
• Indicar a si mesmo não conta. Uma instalação ou um evento vindo do próprio celular do indicador é registrado, mas não conta nem é recompensado. Em compras, só conseguimos identificar a compra do próprio indicador quando seu app enviou o app user ID dele (veja acima) e o mesmo ID vem com a compra. Sem isso, um indicador que compra no próprio celular é contado como qualquer amigo.
• Limite mensal (opcional). Desativado por padrão. Ative Limitar recompensas por indicador a cada mês para limitar as recompensas. Indicações acima do limite ainda contam no total, mas não geram recompensa naquele mês.

Estatísticas do programa

A aba Indicações no app mostra seus indicadores, as indicações no total e no mês, as recompensas concedidas e os principais indicadores.

Regras das Lojas

Programas de indicação são permitidos na App Store e no Google Play. A tela pronta já segue estas regras:

• Compartilhar é opcional. Nunca bloqueie um recurso atrás do compartilhamento e nunca recompense uma avaliação.
• Somente o menu de compartilhamento. A tela não pede acesso aos Contatos e não tem opção de "convidar todos".
• Recompense ações reais. Recompensar compras ou eventos no app é o mais seguro. O Google Play monitora apps que recompensam instalações.
• Tempo premium grátis. Conceda por códigos de oferta da App Store, códigos promocionais do Google Play ou uma cobrança adiada no Google Play, um entitlement promocional do RevenueCat ou um nível de acesso do Adapty, e não por um sistema de códigos próprio.
• Sem recompensas em cripto por convidar pessoas.

Bom Saber

• Indicadores ocupam uma vaga. Cada um conta para o limite de afiliados do seu plano, como qualquer afiliado. Ao atingir o limite, createAffiliateForUser retorna AFFILIATE_LIMIT_REACHED.
• É preciso um e-mail para virar indicador. É com ele que a pessoa entra no painel.
• Links. Cada indicador recebe um link da mesma forma que qualquer novo afiliado: empresas com Insert Links recebem um gerado automaticamente, empresas só com código curto compartilham o código, e empresas com Branch, AppsFlyer ou links de compra web do RevenueCat recebem o próximo link dos deep links que enviaram. Se os links enviados acabarem, novos indicadores ainda entram e compartilham o código, então mantenha a lista abastecida.
• Comissão. Indicadores recebem a comissão que você escolher em Recompensas dos indicadores. Escolha Sem dinheiro (só recompensas) se quiser dar apenas recompensas no app.
• Encontrando indicadores. Indicadores no app têm o selo No app na sua lista de afiliados, e você pode filtrar pela forma como os afiliados entraram.