Mobile SDK

Last update: Jul 20th, 2020

Introduction

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.

Android Mobile SDK 3.0.1

Overview

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.



Installation Guide

Package Installation

  • Download the SDK using the link below

You can install the SDK by downloading the file at this link.

  • Install the SDK using Gradle

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.



Project configuration

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.



App Permissions

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.



Behavior Class

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.



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.


Methods
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:
  • SessionIDAlreadyUsedException – This exception is returned when the same session ID is used more than once.
start() :void Starts collecting the device’s information.

Exceptions:
  • CaptureWasStartedException - This exception is returned when a previous capture was not completed.
stop() :void Stops the data collection process.


Examples

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();


Use License

By downloading and installing our Mobile SDK, you agree to the terms of our Use License.

iOS

Package download

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.

Application permissions

You will be required to perform a few permissions and to enable iCloud in the application that will consume the library.

  1. Enable iCloud in Apple's portal
    1. Go to developer.apple.com
    2. Select Certificates, IDs & Profiles menu
    3. In the Identifier section of the left side menu select App Ids
    4. Click on the app id of the desired app
    5. Click on Edit
    6. Mark the option iCloud and select Include CloudKit support (requires Xcode 6)
    7. By doing this the existing provisioning profiles for the application will be invalidated, and you will be required to generate new provisioning profiles for your app and then install them in XCode.
  2. Enable iCloud in XCode
    1. Access project configurations and open the Capabilities tab
    2. Activate the iCloud option
    3. Mark the option Key-value storage and the option CloudKit
    4. After selecting CloudKit two options will appear: Use default container and Specify custom container. Leave the option Use default container marked.

Profile Class

Description

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.

Package

This class is part of the package sale.clear.device.

Builders

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

Methods

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.

Statistic Methods
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).

Installation

Instructions to install the framework in the destination project:

  1. Drag the framework (CSClearDevice_1.1.0.framework) into the project, and select the following options:
    1. Copy items if needed
    2. Added folders: Create groups.
    3. Add to targets: “Name of the destination project”.
  2. Open the project editor, select the project, and add the flag “-ObjC” to the “Other Linker Flags” setting in the “Build Settings” tab.
  3. Add the following entries to the file Info.plist of 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>
                                        
  4. For projects developed in Objective-C, import <CSClearDevice/CSClearDevice.h> in the file where you want to use the framework.
  5. For projects developed in Swift, import <CSClearDevice_1.1.0/CSClearDevice.h> in the project's bridging header.

Examples

With SessionID already generated (Objective-C)
// ...
// 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.
// ...
                            
With SessionID already generated (Swift)
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.
// ...
                            
With SessionID not generated (Objective-C)
[[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.
// ....
                            
With SessionID not generated (Swift)
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.
// ...