Last update: Jul 20th, 2020
This manual aims to provide all the information required for the mobile application developers to integrate their applications with our solution for Android and iOS.
The purpose of this guide is to provide developers with all the necessary information to integrate their apps with our Mobile SDK for the Android platform.
Mobile SDK collects public information from the user's device and sends it to ClearSale. The information collected is limited to data used to identify the device and is used for fraud prevention. Mobile SDK does not collect integrated data from the app.
The geolocation data collected depends on the permissions granted by the user. At this point, it is important for the app to request access to the user's geolocation data, as our Mobile SDK does not request this permission itself. If the app does not request geolocation access or the user does not grant permission, the geolocation is not collected.
Android Mobile SDK respects Google's privacy policy for device data collection.
Package Installation
You can install the SDK by downloading the file at this link.
The SDK is available in a private repository. To use it, add the following repository to the root file:
maven {
url 'https://pkgs.dev.azure.com/vstscs/Produtos-Agile/_packaging/BehaviorAnalytics.SDK.Android/maven/v1'
name 'BehaviorAnalytics.SDK.Android'
credentials {
username "vstscs"
password YOUR_ACCESS_TOKEN
}
}
ClearSale will send the access token.
You must apply the following dependencies in your project:
play-services-location, play-services-ads, and gson.
You can do this by adding the following information to your project's Gradle file in the dependencies section.
dependencies {
// Other dependencies of your project.
//...
// Mandatory 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.1'
// Optional dependencies:
api 'com.google.android.gms:play-services-location:17.0.0'
}
Note: We recommend using Gradle 5.4.1, Android Studio 3.5.1, and the 3.5.1 plugin.
For the information collection software to access the relevant data on the device, the following permissions must be set:
<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"/>
Note: For apps that target Android version 26 or higher, it is necessary not only to add the permissions in the manifest, but also to request permission from the user to collect geolocation data by following Android’s recommendations.
The Behavior class is responsible for collecting the device’s information.
This class has no public constructors. An instance must be created using a static method.
| Method name | Description |
|---|---|
| Behavior.getInstance(String app) :Behavior | Gets the instance of the Behavior class for an AppKey. It is necessary to pass the AppKey provided by ClearSale as a parameter; the AppKey value is provided by ClearSale. |
| Method name | Description |
|---|---|
| generateSessionId() :String | Generates and returns a session identifier (session ID). Use this method only if the app does not have a session ID. This value must be stored to be sent to ClearSale later in the order transaction. |
| collectDeviceInformation(String sessionID) :void | Collects information from the device linked to the session ID. It is necessary to pass the session ID as a parameter. Note: The session ID’s maximum size is 256 characters. Exceptions:
|
| start() :void | Starts collecting the device’s information. Exceptions:
|
| stop() :void | Stops the data collection process. |
There are two ways to initialize the SDK, depending on the the type of screen your app uses.
If it is an activity, the initialization must be written using the onCreate() method. If it is a fragment, the initialization must use the onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) method.
Note: both cases, if the stop() method is not called within the onStop() method, the CaptureWasStartedException exception will be thrown on the next screen when start() is called.
Note: In the examples, we assume that the following variables have already been created:
This is the implementation when the screen is a fragment:
@Override
public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) {
// Getting 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 that must be provided by ClearSale.
mBehavior = Behavior.getInstance(mContext, CLEAR_SALE_APP);
return rootView;
}
This is the implementation when the screen is an activity:
@Override
public void onCreate() {
//CLEAR_SALE_APP is a value that must be provided by ClearSale.
mBehavior = Behavior.getInstance(this, CLEAR_SALE_APP);
}
Do the following to begin collecting device data:
Call the start() and stop() methods on all screens.
Call the collectDeviceInformation(SESSION_ID) method 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 you want to send the collected data to ClearSale:
String sessionId = mBehavior.generateSessionId()
collectDeviceInformation(sessionId);
}
catch (CaptureWasStartedException e) {
// This indicates that the startCapture method was called
//and the stopCapture() method was not called in the onStop() method.
Log.e(LOG_TAG, e.getMessage());
}catch (SessionIDAlreadyUsedException e) {
//This indicates that the same SessionId was used more than once.
Log.e(LOG_TAG, e.getMessage());
}
}
Do the following to stop collecting device data:
@Override
public void onStop() {
super.onStop();
mBehavior.stopCapture();
In order to start the development of the integration it will be necessary to download a file with .zip extension from the website below.
https://device.clearsale.com.br/ios/cscleardevice_1.1.0.framework.zip
This compressed file contains the library required to implement the integration.
You will be required to perform a few permissions and to enable iCloud in the application that will consume the library.
Profile is the class responsible for identifying the application that is using the library and the collection, analysis, and delivery of the information to the ClearSale environment.
This class is part of the package sale.clear.device.
This class has no public builders. The instance must be made by a static method.
| setApp(String) | Defines the application that is integrating the information. This value will be provided by ClearSale. |
| setSessionID(String) | Defines the session identifier of the purchase in the application. This identifier must be the same one sent to ClearSale along with the order information. |
| getSessionID() | Gets the session identifier of the purchase in the application. |
| generateSessionID() | Generates a session identifier. This method must only be used if the application does not generate unique identifiers for each purchase. When this method is used it is essential to use the getSessionID method to get the number generated to be sent later to ClearSale along with the order information. |
| send() | Sends the information collected and analyzed. |
| getInstance(String) | Gets the instance of the Profile class. The Context is type android.content.Context. It can be found using getApplicationContext(), getContext(), getBaseContext() or this (when it is in an Activity class). |
Instructions to install the framework in the destination project:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>clearsale.com.br</key>
<dict>
<key>NSIncludesSubdomains</key>
<true />
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true />
<key>NSTemporaryExceptionMinimumTLSVersion</key>
<string>TLSv1.0</string>
</dict>
</dict>
</dict>// ...
// Your code for generating the session identifier.
// ...
[[CSClearDevice getInstance] setApp:@"seuapp"]; // This value will be provided by ClearSale.
[[CSClearDevice getInstance] setSessionID:@"sessionID "]; // Generated session identifier.
[[CSClearDevice getInstance] send];
// ...
// Remainder of your application code.
// ...var sessionID; // Variable name for example purposes only.
// ...
// Your code for generating the session identifier.
// ...
let profile = CSClearDevice.getInstance();
profile.setApp("seuapp"); // This value will be provided by ClearSale.
profile.setSessionID(sessionID);
profile.send();
// ...
// Remainder of your application code.
// ...[[CSClearDevice getInstance] setApp:@"seuapp"]; // This value will be provided by ClearSale.
[[CSClearDevice getInstance] generateSessionID]; // Create session identifier.
[[CSClearDevice getInstance] send];
// If the SessionID was generated by the Profile class, you must use the getSessionID() method.
[[CSClearDevice getInstance] getSessionID];
// ...
// Remainder of your application code.
// ....let profile = CSClearDevice.getInstance();
profile.setApp("seuapp"); // This value will be provided by ClearSale.
profile. generateSessionID();
profile.send();
// If the SessionID was generated by the Profile class, you must use the getSessionID() method.
var sessionID = profile.getSessionID();
// ...
// Remainder of your application code.
// ...