KappS Base de conhecimento · Blog

Google Play Install Referrer API em 2026: dados de atribuição e estados de conexão

Blog Guia

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.

Clique para escolher um arquivo · clique com o botão direito → Colar, ou pressione Ctrl/⌘+V para colar uma captura de tela

Você também pode arrastar um arquivo para esta caixa.

Respondemos ao e-mail que você fornecer. Seus dados ficam com KappS.

✔ Enviado

Recebemos sua mensagem e responderemos em até 24 horas.


← Voltar para editar