SDK Android

Last updated March 30, 2021

Introduction

The purpose of this manual is to provide all of the information necessary to install and use the tools in the apps developed for the Android platform.
This SDK is written in Java, it gathers device data (information and location) and sends it to ClearSale. The data gathered will be related solely to the device and is unrelated to the integrated app.

Geolocation data depends on permission granted by the device user. This means the app must request access to user location data (the SDK does not ask for permission). If the app does not request access or if the user denies permission the data will not be gathered.

SDK respects Apple's privacy policy in terms of gathering device data and the level of permission granted by the device user.

Android

Package Installation

  • Gradle

The pod is available in a private repository, using it requires adding the following repository to the root file:

 

maven {
        url 'https://pkgs.dev.azure.com/vstscs/Produtos-Agile/_packaging/BehaviorAnalytics.SDK/maven/v1'
       name 'BehaviorAnalytics.SDK.Android'
       credentials {
       username "vstscs"
       password TOKEN_DE_ACESSO
    }
}

 

A request for an access token must be sent to ClearSale.

  • Gradle

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

 

maven {
        url 'https://pkgs.dev.azure.com/vstscs/Produtos-Agile/_packaging/BehaviorAnalytics.SDK/maven/v1'
       name 'BehaviorAnalytics.SDK.Android'
       credentials {
       username "vstscs"
       password TOKEN_DE_ACESSO
    }
}

 

É necessário solicitar o token de acesso junto à ClearSale.

Project Configuration

The following dependences must be used in the project: play-services-location, play-services-ads, gson. For this, add the following information to the dependencies section of the Gradle file.

dependencies {
    // Other project dependencies.
    //...
    // Required dependencies
    implementation 'com.google.android.gms:play-services-ads:18.3.0'
    api 'com.google.code.gson:gson:2.8.6'
    implementation 'sale.clear.behavior:sdk-behavior:3.0.2'

    // Optional dependencies
    api 'com.google.android.gms:play-services-location:17.0.0'
 }

We recommend Gradle 5.4.1, Android Studio 3.5.1 and plugin 3.5.1.

App permissions

Using SDK requires asking for the following permissions in the manifest file:

<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"/>

Apps using Android version 26 or higher as the Target and that wish to capture geolocation data must not only add ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION to the manifest, but also ask for user permission to gather geolocation data, as per the Android recommendation.

Behavior Class

Description

Behavioris the class responsible for data gathering.

Builders

This class has no public builders. The instance must be made using a static method.


Static Methods
Method name Description
Behavior.getInstance(String app) :Behavior Obtain the Behavior class instance for an AppKey.
The AppKey (provided by ClearSale) must be given as a parameter.

Methods

 

Method name Description
generateSessionID() :String Generates and returns a session identifier.
This method is to be used only if the app has no session value.
This value must be stored and sent to ClearSale at the moment of request [order] integration.
collectDeviceInformation(String sessionID) :void Gathers data on the device linked to the Session value.
SessionId, the session value must be provided as a parameter. This value must be stored and sent to ClearSale at the moment or request [order] integration.
(*) If that SessionID has no unique value use). generateSessionId().
(**) The maximum size of SessionID is 128 characters.
Exceptions:
  • SessionIDAlreadyUsedException - launched when a given session value is used more than once.
start() :void IInitiates the collection of data on the device and screen.
Exceptions:
  • CaptureWasStartedException - launched when a prior capture was not stopped.
stop() :void Ends the data capture process.
   

 

Examples

There are two ways to initialize the SDK. This depends on the type of screen to be used. If it is an Activity screen, initialization must use the onCreate() approach. If it is a Fragment screen, initialization must use the onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) approach

Note: In both cases (Activity or Fragment), if the stop() approach is not called within the onStop() method of one of the screens because it is a singleton, when start() is called on the next screen a CaptureWasStartedException exception will be launched.

All examples presume the existence of the following variables:

  • mBehavior, which represents the Behavior class instance. This may be replaced with ut1}Behavior.getInstance(contexto, CLEAR_SALE_APP).
  • String-type CLEAR_SALE_APP variable, the value of which will be provided by ClearSale.

To start a call on a Fragment screen.
@Override
public View onCreateView(LayoutInflater inflater, ViewGroup container,
                                Bundle savedInstanceState) {
    // To obtain the Context in a Fragment.
    View rootView = inflater.inflate(R.layout.fragment_login, container, false);
    Context context = rootView.getContext();
    //CLEAR_SALE_APP is a value to be provided by ClearSale.
    mBehavior = Behavior.getInstance(mContext, CLEAR_SALE_APP);
    return rootView;
}

For an Activity screen
@Override
public void onCreate() {
    //CLEAR_SALE_APP is a value to be provided by ClearSale.
    mBehavior = Behavior.getInstance(this, CLEAR_SALE_APP);
}

To initiate capture:

Use thestart() e stop() approaches for all screens. Use collectDeviceInformation(SESSION_ID) only when you want to send the collected data to ClearSale. 

@Override
    public void onResume() {
        super.onResume();
        try {
            mBehavior.start();
            //Only on the screens where the data gathered will be sent to ClearSale
            String sessionId = mBehavior.generateSessionID()
            mBehavior.BehaviorcollectDeviceInformation(sessionId);
        }
        catch (CaptureWasStartedException e) {
            //This indicates that the startCapture approach was called up previously and not 
            //the stopCapture() approach was called up in the onStop() approach.
            Log.e(LOG_TAG, e.getMessage());
        }catch (SessionIDAlreadyUsedException e) {
            //The same SessionID was used before.
            Log.e(LOG_TAG, e.getMessage());
        }
    }

To stop capturing:
@Override
public void onStop() {
    super.onStop();
    mBehavior.stop();
}

User License

By downloading and using our SDK you are agreeing to the following license.

Copyright © 2021 ClearSale

All rights reserved. This license grants permission to use the software "as is". The software may not be modified or copied for any purpose. The Software is licensed as configured and with absolutely no expressed or implicit guarantee, including but not limited to marketing guarantees, suitability for specific purposes and non-violation of patented rights. Under no circumstances may the owners of the Copyright be held liable for damages, losses, basis for lawsuits due to contract or illegal acts or any other illegal means arising from the use of the Software or other actions related to this Software without the prior written authorization of the copyright holders.

Copyright © 2021 ClearSale