Google Play Install Referrer API em 2026: dados de atribuição e estados de conexão
A atribuição de instalação é a única medição da qual depende cada instalação paga, e no Google Play ela vem de uma interface única e pequena: a Install Referrer API. Não é um recurso de dashboard e não envia números por e-mail — ela entrega ao seu app o conteúdo de referência que o Play registrou no momento da instalação, uma única vez, e depois é seu trabalho armazená-lo e reconciliá-lo. Este tutorial percorre todo o caminho: o que a API retorna, como conectar, como ler a resposta, a regra dos 90 dias que a maioria das equipes descobre tarde demais e o que fazer com cada estado de conexão.
Tudo abaixo se baseia nas próprias páginas de referência do Google para a Install Referrer API e a Play Install Referrer Client Library, ambas verificadas em 27/10/2026.
Etapa 1 — Saiba exatamente o que a API retorna antes de projetar em torno dela
A API recupera o conteúdo de indicação registrado pelo app da Play Store, e o payload documentado é restrito e específico:
- a URL de referência do pacote instalado;
- o timestamp, em segundos, do clique no referenciador — disponível tanto no cliente quanto no servidor;
- o timestamp, em segundos, de quando a instalação começou — novamente tanto no lado do cliente quanto no do servidor;
- a versão do app no momento da primeira instalação;
- se o usuário interagiu com a experiência instantânea do seu app nos últimos 7 dias.
Dois requisitos condicionam tudo isso. A API é exposta pelo app da Play Store no dispositivo, e aparelhos com Play Store 8.3.73 ou superior têm acesso automaticamente. Você também precisa de uma conta Google Play Console. Por baixo, a API é uma interface AIDL; espera-se que desenvolvedores Kotlin e Java usem o wrapper da biblioteca cliente em vez do AIDL puro.
Consequência para o design: trata-se de atribuição de primeira instalação com um carimbo de data e hora do clique e um carimbo de data e hora do início da instalação. Não há cadeia multitouch, nem view-through, nem grafo entre dispositivos na resposta. Se o seu modelo de relatórios pressupõe qualquer um desses, os dados precisam vir de outro lugar.
Etapa 2 — Adicione a biblioteca cliente
No build.gradle do módulo do app, adicione a dependência. A versão documentada na página da biblioteca cliente é a 2.2:
dependencies { ... implementation "com.android.installreferrer:installreferrer:2.2" }
Se o seu módulo estiver configurado para Kotlin DSL, a mesma coordenada é adicionada com implementation("com.android.installreferrer:installreferrer:2.2"). Nada mais é necessário — nenhum receiver no manifesto, nenhuma permissão, nenhum toggle no Play Console. A antiga abordagem com broadcast receiver é justamente o que esta biblioteca substitui; não mantenha os dois caminhos.
Etapa 3 — Conecte-se ao app Play Store
A conexão é assíncrona, e é exatamente aí que começam a maioria das implementações quebradas. A sequência documentada é: criar um cliente com InstallReferrerClient.newBuilder(this).build(), chamar startConnection() e passar um InstallReferrerStateListener que recebe o resultado.
referrerClient = InstallReferrerClient.newBuilder(this).build() referrerClient.startConnection(object : InstallReferrerStateListener { override fun onInstallReferrerSetupFinished(responseCode: Int) { when (responseCode) { InstallReferrerResponse.OK -> { /* conexão estabelecida */ } InstallReferrerResponse.FEATURE_NOT_SUPPORTED -> { /* API indisponível neste app da Play Store */ } InstallReferrerResponse.SERVICE_UNAVAILABLE -> { /* não foi possível estabelecer a conexão */ } } } override fun onInstallReferrerServiceDisconnected() { /* chame startConnection() novamente antes da próxima solicitação */ } })
Leia o contrato de callback ao pé da letra. OK significa que a conexão foi bem-sucedida e você pode prosseguir. FEATURE_NOT_SUPPORTED significa que a API não está disponível no app Play Store daquele dispositivo — uma build da loja antiga ou fora do padrão, não um bug no seu código. SERVICE_UNAVAILABLE significa que a conexão não pôde ser estabelecida de forma alguma, o que é um problema de timing, não um veredito.
A desconexão é esperada, não excepcional: a própria nota do Google diz que o cliente pode perder a conexão se o serviço do Play Store estiver sendo atualizado em segundo plano, e que o cliente deve chamar startConnection() novamente para reiniciá-la antes de novas requisições. Então o listener não é de uso único; trate-o como uma máquina de estados que você controla.
Etapa 4 — Leia os detalhes do referenciador
Uma vez conectado, getInstallReferrer() é uma chamada sincronizada que retorna um objeto ReferrerDetails. Os campos correspondem um a um ao payload listado na Etapa 1:
val response: ReferrerDetails = referrerClient.installReferrer val referrerUrl: String = response.installReferrer val referrerClickTime: Long = response.referrerClickTimestampSeconds val appInstallTime: Long = response.installBeginTimestampSeconds val instantExperienceLaunched: Boolean = response.googlePlayInstantParam
Dois deles são mais úteis do que parecem. referrerClickTimestampSeconds e installBeginTimestampSeconds permitem calcular o delta de clique até instalação por campanha — um delta lento geralmente significa que a página da loja, e não o anúncio, perdeu o usuário. googlePlayInstantParam informa se a instalação veio de uma experiência instantânea nos últimos 7 dias, que é o único sinal de atribuição instantânea na resposta.
Etapa 5 — Respeite a janela de 90 dias e faça a chamada uma única vez
Esta é a frase que custa às equipes seus dados históricos: as informações do install referrer ficarão disponíveis por 90 dias e não mudarão a menos que o aplicativo seja reinstalado. A orientação do Google logo em seguida é igualmente direta — para evitar chamadas desnecessárias à API, invoque a API apenas uma vez durante a primeira execução após a instalação.
Os 90 dias não são uma licença de armazenamento. É a janela em que o valor ainda pode ser recuperado do Play, então um app que só o lê de forma preguiçosa, em alguma sessão posterior, tem um prazo rígido. Leia na primeira execução após a instalação e persista. Como ele não muda a menos que o app seja reinstalado, um loop de atualização não traz nada e só adiciona chamadas.
Feche a conexão quando terminar: chame endConnection() no cliente. O motivo do Google é explícito — fechar a conexão evita vazamentos e problemas de desempenho no dispositivo.
Etapa 6 — Ramifique pelo código de resposta, não repita às cegas
A leitura de atribuição no primeiro lançamento está no caminho crítico da primeira experiência do usuário, então a política de falha importa tanto quanto o código. Um mapeamento viável:
- OK — leia, persista,
endConnection(). Não leia novamente em inicializações posteriores. - SERVICE_UNAVAILABLE — trate como "agora não". Não armazene nada, não bloqueie a primeira tela e tente novamente em uma próxima abertura dentro da janela de 90 dias.
- FEATURE_NOT_SUPPORTED — a API não existe neste dispositivo. Recorra ao identificador de campanha que seu próprio link carrega e registre que a leitura não foi suportada, para que seus relatórios não a contem silenciosamente como orgânica.
- Desconectado — reinicie com
startConnection()antes da próxima solicitação; não presuma que o cliente ainda está ativo.
Uma regra de engenharia está acima das outras quatro: nunca deixe a atribuição bloquear a primeira experiência do usuário e nunca deixe uma leitura com falha gravar uma linha de atribuição "orgânica" falsa. A diferença entre "sem dados" e "orgânico" é exatamente onde os relatórios de instalação param de fechar.
Etapa 7 — Trate a string de referenciador como entrada não confiável
A biblioteca cliente retorna o valor do referrer como string. Ele é entregue pela plataforma, mas ainda é um valor originado fora do seu app, então vale a higiene comum para entrada externa: faça o parse em pares chave-valor de forma defensiva, limite o comprimento e nunca o interpole em uma URL, em uma rota de link direto ou em uma consulta de banco de dados sem validação.
Na prática, isso significa: decodifique o valor, separe pelos separadores documentados, coloque na lista de permitidos as chaves de campanha que você realmente reconhece e descarte todo o resto. Depois, confira com o seu próprio evento no lado do servidor antes que isso vire insumo de cobrança ou de receita. Os dados de atribuição decidem qual canal recebe orçamento — uma string não validada não deveria poder movimentar dinheiro.
Se a string de referenciador é encaminhada para redes de anúncios ou para um MMP, verifique se a sua declaração de Segurança dos dados do Play e a política de privacidade já cobrem esse compartilhamento antes de o pipeline entrar no ar, não depois de uma auditoria. A estrutura de atribuição é coleta de dados; a declaração precisa descrevê-la.
Etapa 8 — Anote o que a API não informa
A maioria das disputas de atribuição vem de esperar a coisa errada de uma resposta correta. A partir das duas páginas de referência, os limites honestos são:
- Dispositivos com Play Store anterior à versão 8.3.73 simplesmente não têm a API — planeje o fallback, porque
FEATURE_NOT_SUPPORTEDé um resultado real, não um erro para registrar e esquecer. - O valor é fixado na primeira instalação e não muda, a menos que o app seja reinstalado — portanto, não consegue expressar uma reativação de usuários, um upgrade ou um toque de campanha posterior.
- A recuperabilidade termina após 90 dias — tudo o que você não persistiu nessa janela se perde.
- A flag de experiência instantânea cobre apenas uma janela retroativa de 7 dias.
- É um sinal no nível de dispositivo e conta para instalações vindas do Play; não é uma identidade de usuário e não elimina duplicatas de instalações entre dispositivos.
Coloque esses cinco limites no mesmo documento do seu esquema de atribuição. Quando um relatório de campanha e um relatório de receita divergem, a divergência costuma ser uma dessas cinco afirmações, não um bug no cliente.
Fontes: Android Developers — Google Play Install Referrer API (developer.android.com/google/play/installreferrer): campos do payload, requisito do Play Store 8.3.73+, interface AIDL, exigência de conta no Play Console. Android Developers — Play Install Referrer Library (developer.android.com/google/play/installreferrer/library, página atualizada em 2026-10-23): versão de dependência 2.2, fluxo de conexão e códigos de resposta, campos getInstallReferrer() e ReferrerDetails, a nota de disponibilidade de 90 dias, a recomendação de uma vez por instalação e endConnection(). Ambas verificadas em 2026-10-27. O Google não publica taxas de atribuição por campanha nem números de latência do lado da loja; nenhum é inferido aqui.
Gerencia contas de desenvolvedor em escala? Cuidamos do lado operacional.
Recebemos sua mensagem e responderemos em até 24 horas.
← Voltar para editar