Introdução

O objetivo deste manual é fornecer todas as informações necessárias para instalação e uso da ferramenta nos aplicativos desenvolvidos para plataforma Android.

Este SDK realiza a coleta de dados (informações e localização) do dispositivo e envio para ClearSale. Todas as informações coletadas são dados relacionados apenas ao dispositivo, sem relação ao aplicativo integrado.

A informação de geolocalização depende da permissão concedida pelo usuário do dispositivo, neste caso é necessário que o aplicativo solicite o acesso da informação de localização do usuário**** (o SDK não solicita permissão). Caso o aplicativo não solicite o acesso ou o usuário não conceda permissão, para localização, não será realizada a captura das informações de GeoLocation.

O SDK respeita a política de privacidade da Google para a captura dos dados do dispositivo e o nível de permissão atribuído pelo usuário (usuário do dispositivo).

Configuração

Checksum

Para verificar o checksum das dependencias no Gradle 7.0 ou superior, siga as instruções desse link: Dependency Verification

Upgrade de versão

Para realizar a atualização da versão 3.x.x para a versão 5.6.5, siga essas etapas:

1. Remova a dependencia 'com.google.code.gson:gson' se ela não for utilizada no seu projeto
2. Substitua o plugin play-services-ads pelo plugin play-services-ads-identifier:18.0.1
3. Atualize a versão do plugin play-services-location para a versão 21.0.1

Nova Instalação

Instalação do Package

• Gradle (Recomendamos o uso do Gradle 7.0.2 ou superior)

O pacote está disponível em um repositório privado, e para sua utilização é necessário adicionar o seguinte repositório ao arquivo raiz:

maven {
    url 'https://pkgs.dev.azure.com/PublicPackagesCS/Behavior/_packaging/BehaviorAnalytics.SDK/maven/v1'
    name 'BehaviorAnalytics.SDK.Android'
}

Configuração do Projeto

É necessário utilizar as seguintes dependências no seu projeto: play-services-location, play-services-ads-identifier. Para isso adicione no arquivo Gradle do seu projeto, na seção de dependências, as seguintes informações.

dependencies {
    // Demais dependências do seu projeto.
    //...
    // Dependências Obrigatórias:
    implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
    implementation 'sale.clear.behavior:sdk-behavior:5.6.5'
    api 'com.google.android.gms:play-services-location:21.0.1'
 }

A dependência 'com.google.android.gms:play-services-ads-identifier:18.0.1' é utilizada para obter as informações do identificador de publicidade do dispositivo.

Já a dependência 'com.google.android.gms:play-services-location:21.0.1' deve ser utilizada sempre que for necessário coletar informações de geolocalização do dispositivo.

Proguard

Se estiver utilizando o Proguard, inclua está regra

-keep class sale.clear.behavior.** { *; }

Permissões no aplicativo

Para o uso do sdk é necessário requisitar algumas permissões no arquivo de manifesto, são elas:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

Obs: Para aplicações que utilizam como Target a versão 26 ou superior do Android, e que desejem capturar informações de geolocalização, é necessário, além de adicionar no manifest as permissões ACCESS_FINE_LOCATION e ACCESS_COARSE_LOCATION, solicitar permissão ao usuário para coletar dados de geolocalização, seguindo a esta recomendação do Android. Já para as aplicações que utilizam como Target a versão 33 (Android 13) ou superior, será necessário incluir a permissão AD_ID para que possa ser possível capturar as informações referentes ao advertisingID

Privacidade da Play Store

Caso o usuário não tenha consentido com as coletas de geolocalização e da lista de aplicativos, os métodos blockGeoLocation() e blockAppList() devem ser chamados, conforme exemplo abaixo:

@Override
public void onResume() {
    super.onResume();
    try {
        mBehavior.blockGeoLocation(); // Bloqueia a captura de geolocalização
        mBehavior.blockAppList(); //Bloqueia a captura de informações dos apps instalados no dispositivo
        mBehavior.start(); //Inicialização da captura de informações.
        String sessionId = mBehavior.generateSessionID()
        //Apenas nas telas que se deseja enviar os dados coletados para a ClearSale
        mBehavior.collectDeviceInformation(sessionId);
    }
    catch (CaptureWasStartedException e) {
        //Isso indica que o método startCapture foi chamado anteriormente e não
        //foi chamado o método stopCapture() no metodo onStop().
    }catch (SessionIDAlreadyUsedException e) {
        //O mesmo sessionId foi usado anteriormente.
    }
}

Classe Behavior

Descrição
Behavior é a classe responsável pela coleta das informações.

Construtores
Esta classe não possui construtores públicos. A instância deverá ser feita através de um método estático.

Métodos Estáticos

Métodos

Exemplos

Existem duas formas de inicializar o SDK. Isso depende do tipo de tela que será utilizada. Caso a tela seja uma Activity, a inicialização deve ser feita no método onCreate(). Caso seja um Fragment, a inicialização deve ser feita no método onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState)

Observação: Em ambos os casos (Activity ou Fragment), se o método stop() não for chamado dentro do método onStop() de uma das telas, por se tratar de um singleton, na próxima tela quando for chamado o start() será lançada a exceção CaptureWasStartedException.

Em todos os exemplos se assume a existência das seguintes variáveis:

• mBehavior que representa a instância da classe Behavior. Pode ser substituído por Behavior.getInstance(contexto, CLEAR_SALE_APP).
• CLEAR_SALE_APP variável do tipo string, o valor desta variável deve ser fornecido pela ClearSale.

Para inicializar a chamada, quando a tela é um Fragment:

@Override
public View onCreateView(LayoutInflater inflater, ViewGroup container,
Bundle savedInstanceState) {
    // Para obter o Context em um Fragment.
    View rootView = inflater.inflate(R.layout.fragment_login, container, false);
    Context context = rootView.getContext();
    //CLEAR_SALE_APP é um valor que deve ser fornecido pela ClearSale.
    mBehavior = Behavior.getInstance(context, CLEAR_SALE_APP);
    return rootView;
}

Quando a tela é uma Activity:

@Override
public void onCreate() {
    //CLEAR_SALE_APP é um valor que deve ser fornecido pela ClearSale.
    mBehavior = Behavior.getInstance(this, CLEAR_SALE_APP);
}

Para iniciar a captura:

@Override
public void onResume() {
    super.onResume();
    try {
        mBehavior.start(); //Inicialização da captura de informações.
        String sessionId = mBehavior.generateSessionID()
        //Apenas nas telas que se deseja enviar os dados coletados para a ClearSale
        mBehavior.collectDeviceInformation(sessionId);
    }
    catch (CaptureWasStartedException e) {
        //Isso indica que o método startCapture foi chamado anteriormente e não
        //foi chamado o método stopCapture() no metodo onStop().
    }catch (SessionIDAlreadyUsedException e) {
        //O mesmo sessionId foi usado anteriormente.
    }
}

Os métodos start() e stop() devem ser implementados apenas na tela em que a captura de informações será realizada. O método collectDeviceInformation(SESSION_ID) deve ser chamado no momento em que deseja enviar as informações coletadas para a ClearSale, na mesma tela em que foi implementado os métodos anteriores.

OBS: O método collectDeviceInformation deve ser, obrigatoriamente, chamado depois do método start() já ter sido executado.

Recomendamos que estes métodos sejam implementados em uma tela de "finalização" onde haja interação do usuário por, no mínimo, 3 segundos.

Para encerrar a captura:

@Override
public void onStop() {
    super.onStop();
    mBehavior.stop(); //Finalização da captura de informações.
}                         

Exemplo completo de implementação:

public class ExemploImplementacaoActivity extends AppCompatActivity {

    private Behavior mBehavior;

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        //CLEAR_SALE_APP é um valor que deve ser fornecido pela ClearSale.
        mBehavior = Behavior.getInstance(this, "CLEAR_SALE_APP");
    }

    @Override
    public void onResume() {
        super.onResume();
        try {
            mBehavior.start(); //Inicialização da captura de informações.
            String sessionId = mBehavior.generateSessionID();
            //Apenas na tela que se deseja enviar os dados coletados para a ClearSale
            mBehavior.collectDeviceInformation(sessionId);
        } catch (CaptureWasStartedException e) {
            //Isso indica que o método startCapture foi chamado anteriormente e não
            //foi chamado o método stopCapture() no metodo onStop().
        } catch (SessionIDAlreadyUsedException e) {
            //O mesmo sessionId foi usado anteriormente.
        }
    }

    @Override
    public void onStop() {
        super.onStop();
        mBehavior.stop(); //Finalização da captura de informações.
    }
}

Projeto de Exemplo

É possível visualizar a implementação do SDK em um projeto de exemplo Clicando aqui.

Detalhes de privacidade

Uso de Dados

Todas as informações coletadas pelo SDK da ClearSale são com exclusiva finalidade de prevenção à fraude e proteção ao próprio usuário, aderente à política de segurança e privacidade da plataforma Google e à LGPD. Por isso, estas informações devem constar na política de privacidade do aplicativo.

Tipo de dados coletados

O SDK da ClearSale coleta as seguintes informações do dispositivo :

• Localização precisa (quando habilitada permissão pelo usuário);
• Identificadores de publicidade do dispositivo (quando habilitada permissão pelo usuário);
• Características físicas do dispositivo/ hardware (Como tela, bateria, teclado, espaço livre em disco, modelo, nome do dispositivo);
• Características de software (Como versão, idioma, build, controle parental);
• Informações de rede (Como Conexões, IP);
• Informações da configuração do sistema

Saiba mais em: Privacidade de dados da Play Store

Política de privacidade da Google