Biblioteca Play Install Referrer

Você pode usar a API Install Referrer da Google Play Store para recuperar com segurança o conteúdo de referência do Google Play. A biblioteca de cliente da API Play Install Referrer é escrita em linguagem de programação Java e é um wrapper para o arquivo em Linguagem de definição de interface do Android (AIDL, na sigla em inglês) que define a interface para o serviço de referenciador de instalação. É possível usar a biblioteca de cliente da API Play Install Referrer para simplificar o processo de desenvolvimento.

Este guia aborda os conceitos básicos da recuperação de informações de referência do Google Play usando a biblioteca Play Install Referrer.

Como atualizar as dependências do app

Adicione a linha a seguir à seção de dependências do arquivo build.gradle do seu app:

dependencies {
    ...
    implementation "com.android.installreferrer:installreferrer:2.2"
}

dependencies {
    ...
    implementation("com.android.installreferrer:installreferrer:2.2")
}

Como conectar ao Google Play

Antes de usar a biblioteca da API Play Install Referrer, estabeleça uma conexão com o app da Play Store usando as seguintes etapas:

1. Chame o método newBuilder() para criar uma instância da classe InstallReferrerClient.

2. Chame startConnection() para estabelecer uma conexão com o Google Play.

3. O método startConnection() é assíncrono. Portanto, você precisa substituir InstallReferrerStateListener para receber um callback depois que o startConnection() for concluído.

4. Substitua o método onInstallReferrerSetupFinished() para receber uma notificação quando o callback for concluído. Esse método é chamado com um código de resposta necessário para processar os diferentes estados. A constante OK indica que a conexão foi feita sem problemas. Cada uma das outras constantes InstallReferrerResponse é usada em diferentes tipos de erros.

5. Substitua o método onInstallReferrerServiceDisconnected() para processar conexões perdidas com o Google Play. Por exemplo, o cliente da Play Install Referrer Library poderá perder a conexão se o serviço da Play Store estiver sendo atualizado em segundo plano. O cliente da biblioteca precisa chamar o método startConnection() para reiniciar a conexão antes de fazer outras solicitações.

O código a seguir mostra como iniciar e testar uma conexão com o app da Play Store.

private lateinit var referrerClient: InstallReferrerClient

referrerClient = InstallReferrerClient.newBuilder(this).build()
referrerClient.startConnection(object : InstallReferrerStateListener {

    override fun onInstallReferrerSetupFinished(responseCode: Int) {
        when (responseCode) {
            InstallReferrerResponse.OK -> {
                // Connection established.
            }
            InstallReferrerResponse.FEATURE_NOT_SUPPORTED -> {
                // API not available on the current Play Store app.
            }
            InstallReferrerResponse.SERVICE_UNAVAILABLE -> {
                // Connection couldn't be established.
            }
        }
    }

    override fun onInstallReferrerServiceDisconnected() {
        // Try to restart the connection on the next request to
        // Google Play by calling the startConnection() method.
    }
})

InstallReferrerClient referrerClient;

referrerClient = InstallReferrerClient.newBuilder(this).build();
referrerClient.startConnection(new InstallReferrerStateListener() {
    @Override
    public void onInstallReferrerSetupFinished(int responseCode) {
        switch (responseCode) {
            case InstallReferrerResponse.OK:
                // Connection established.
                break;
            case InstallReferrerResponse.FEATURE_NOT_SUPPORTED:
                // API not available on the current Play Store app.
                break;
            case InstallReferrerResponse.SERVICE_UNAVAILABLE:
                // Connection couldn't be established.
                break;
        }
    }

    @Override
    public void onInstallReferrerServiceDisconnected() {
        // Try to restart the connection on the next request to
        // Google Play by calling the startConnection() method.
    }
});

Receber o referenciador de instalação

Depois de estabelecer uma conexão com o app da Play Store, é possível ver as informações do referenciador de instalação seguindo estas etapas:

1. Use o método getInstallReferrer() sincronizado para retornar uma instância de ReferrerDetails.

2. Use os métodos que a classe ReferrerDetails oferece para ver informações sobre o referenciador de instalação.

O código a seguir mostra como você pode acessar as informações do referenciador de instalação:

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

ReferrerDetails response = referrerClient.getInstallReferrer();
String referrerUrl = response.getInstallReferrer();
long referrerClickTime = response.getReferrerClickTimestampSeconds();
long appInstallTime = response.getInstallBeginTimestampSeconds();
boolean instantExperienceLaunched = response.getGooglePlayInstantParam();

Atenção: as informações de referência da instalação ficarão disponíveis por 90 dias e não serão alteradas, a menos que o app seja reinstalado. Para evitar chamadas de API desnecessárias no app, invoque a API apenas uma vez durante a primeira execução após a instalação.

Fechar a conexão de serviço

Após receber as informações de referência, chame o método endConnection() na instância de InstallReferrerClient para encerrar a conexão. O encerramento da conexão ajudará a evitar vazamentos e problemas de desempenho.

Para saber mais, consulte a referência da biblioteca Play Install Referrer.