SDK Integration - Android SDK integration

Page / - last modified by Developer on 2021/04/23 14:02

Android SDK integration

last modified by Developer

on 2021/04/23 14:02

Table of Contents

1. Overview

2. Adding library to project

Step 1

Step 2

WorkManager known issues

3. SDK Initialization

4. Tracking in-app events

4.1 Overview

4.2 Implementation

4.3 Event categories

4.4 Event parameters

5. Additional Configuration (Optional)

5.1 Setting Permissions

5.2 Configuring data Collectors

5.3 Set email

5.4 Custom user ID

5.5 User and device identification

5.6 Logging and debugging

5.7 SDK information

5.8 Data gather policy

5.9 Advertising systems

6. Testing SDK integration

Page Contents

1. Overview

2. Adding library to project

Step 1

Step 2

WorkManager known issues

3. SDK Initialization

4. Tracking in-app events

4.1 Overview

4.2 Implementation

4.3 Event categories

4.4 Event parameters

5. Additional Configuration (Optional)

5.1 Setting Permissions

5.2 Configuring data Collectors

5.3 Set email

5.4 Custom user ID

5.5 User and device identification

5.6 Logging and debugging

5.7 SDK information

5.8 Data gather policy

5.9 Advertising systems

6. Testing SDK integration

1. Overview

MobigateSDK is a tool for gathering users phone data and event tracking. We have developed an SDK that is highly robust, secure, lightweight and very simple to embed.
You can track installs, updates and sessions and also track additional in-app events beyond app installs .

The MobigateSDK is compatible with Android OS version 4.0 and above.

Chapters 2 and 3 are MANDATORY to implement BASIC SDK integration. Tracking in-app events chapter is HIGHLY RECOMMENDED to implement. The rest of the described features are OPTIONAL to implement, although some of them may be necessary for you, depending on your app's business logic.

2. Adding library to project

Click here to download sample app integration source code.

Step 1

To add the library into Android Studio with Gradle build system, add to your top-level build.gradle file:

repositories {
maven {
url "https://repository.spicymobile.pl/repository/spicymobilerelease/"
}
...
}

Step 2

Then add the implementation dependency to your module build.gradle file (latest version is 1.0.19, you can fin the repository here):

dependencies {
implementation 'pl.spicymobile.mobigate.sdk:mobigate-sdk:1.x'
...
}

WorkManager known issues

In order to minimise any possibility of impacting behavior of your application Mobigate SDK does the majority of its work in a second process. There are some known issuse (described here) regarding performance of WorkManager in context of multiprocess applications. In ofred to avoid those issues please use androidx.work:work-multiprocess:2.5.0 or higher as your WorkManager gradle dependency.

3. SDK Initialization

In order to obtain "API_KEY", contact us by going to the "Contact" tab.

To initialize the SDK, add the following code in your Application onCreate() function:

public class MyApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
/*minimum library configuration*/
SDK sdk = new MobigateSDK.Builder(getApplicationContext(),"Api_key").build();
/*start data gather*/
sdk.startService();
}
}

4. Tracking in-app events

4.1 Overview

In-App Events provide insight on what is happening in your app. It is recommended to take the time and define the events you would like to measure.

An event consists of two fields that you can use to describe a user's interaction with your app content:

Field name	Type	Required	Description
Category	String/EventCategory	yes	Event category
Parameter	String/EventParameter	no	Event parameter. There can be more than one

You can use any event category or parameter string of your choice. However, our SDK contains recommended event categories and parameters via enumerations (see Event categories and Event parameters).

4.2 Implementation

Tracking in-app events is performed by two methods:

MobigateSDK.get().trackEvent(new Category.Builder(EventCategory.ADD_PAYMENT_INFO)
.setParameter(EventParameter.CITY,"warszawa")
.setParameter(EventParameter.CURRENCY, "PLN")
.setParameter("UserChoiceParameterName", 12345)
.build())
MobigateSDK.get().trackAppInstall(long timestamp) //with event timestamp parameter

4.3 Event categories

The following section describes the recommended structure of each event category. In-app events categories are defined as part of the EventCategory enumeration class.

LEVEL_ACCOMPLISHED

Description: Track accomplished game level achievement
Event category: EventCategory.LEVEL_ACCOMPLISHED
Recommended parameters: LEVEL, SCORE

ADD_PAYMENT_INFO

Description: Track payment info
Event category: EventCategory.ADD_PAYMENT_INFO
Recommended parameters: SUCCESS

ADD_TO_BASKET

Description: Track add item to basket
Event category: EventCategory.ADD_TO_BASKET
Recommended parameters: PRICE, CONTENT_TYPE, CONTENT_ID, CONTENT, CURRENCY, QUANTITY

REMOVED_FROM_BASKET

Description: Track removed item from basket
Event category: EventCategory.REMOVED_FROM_BASKET
Recommended parameters: PRICE, CONTENT_TYPE, CONTENT_ID, CONTENT, CURRENCY, QUANTITY

ADD_TO_WISH_LIST

Description: Track add item to wish list
Event category: EventCategory.ADD_TO_WISH_LIST
Recommended parameters: PRICE, CONTENT_TYPE, CONTENT_ID, CONTENT, CURRENCY, QUANTITY

REGISTRATION

Description: Track registration
Event category: EventCategory.REGISTRATION
Recommended parameters: REGISTRATION_METHOD

TUTORIAL_COMPLETION

Description: Track tutorial completion
Event category: EventCategory.TUTORIAL_COMPLETION
Recommended parameters: SUCCESS, CONTENT, CONTENT_ID

TRIGGER_CHECKOUT

Description: Track triggered checkout
Event category: EventCategory.TRIGGER_CHECKOUT
Recommended parameters: PROCE, CONTENT_TYPE, CONTENT_ID, CONTENT, QUANTITY, PAYMENT_INFO_AVAILABLE, CURRENCY

PURCHASE

Description: Track purchased item
Event category: EventCategory.PURCHASE
Recommended parameters: REVENUE, CONTENT_TYPE, CONTENT_ID, CONTENT, PRICE, QUANTITY, CURRENCY, ORDER_ID

SUBSCRIBE

Description: Track subscription purchase
Event category: EventCategory.SUBSCRIBE
Recommended parameters: REVENUE, CURRENCY

BEGIN_TRIAL

Description: Track begin trail of product
Event category: EventCategory.BEGIN_TRIAL
Recommended parameters: PRICE, CURRENCY

RATE

Description: Track app/item rate
Event category: EventCategory.RATE
Recommended parameters: RATING_VALUE, CONTENT_TYPE, CONTENT_ID, CONTENT, MAX_RATING_VALUE

SEARCH

Description: Track search event
Event category: EventCategory.SEARCH
Recommended parameters: CONTENT_TYPE, SEARCH_STRING, SUCCESS

USED_CREDIT

Description: Track use of credit
Event category: EventCategory.USED_CREDIT
Recommended parameters: PRICE, CONTENT_TYPE, CONTENT_ID, CONTENT

UNLOCKED_ACHIEVEMENT

Description: Track achievement unlock
Event category: EventCategory.UNLOCKED_ACHIEVEMENT
Recommended parameters: DESCRIPTION

VIEW_CONTENT

Description: Track content view event
Event category: EventCategory.VIEW_CONTENT
Recommended parameters: PRICE, CONTENT_TYPE, CONTENT_ID, CONTENT, CURRENCY

VIEW_LIST

Description: Track list event
Event category: EventCategory.VIEW_LIST
Recommended parameters: CONTENT_TYPE, CONTENT_LIST

CLICK_AD

Description: Track ad click
Event category: EventCategory.CLICK_AD
Recommended parameters: CONTENT_TYPE, CONTENT_ID

VIEW_AD

Description: Track view ad
Event category: EventCategory.VIEW_AD
Recommended parameters: CONTENT_TYPE, CONTENT_ID

EVENT_BOOKING

Description: Track booking event
Event category: EventCategory.EVENT_BOOKING
Recommended parameters: REVENUE, DESTINATION_A, DESTINATION_B, CLASS, DESCRIPTION, CUSTOMER_USER_ID, CONTENT_TYPE, CONTENT_ID, DATE_A, DATE_B

SHARE

Description: Track share event
Event category: EventCategory.SHARE
Recommended parameters: DESCRIPTION

INVITE

Description: Track social invite event
Event category: EventCategory.INVITE
Recommended parameters: NONE

LOGIN

Description: Track user login event
Event category: EventCategory.LOGIN
Recommended parameters: NONE

EVENT_RETURN

Description: Track re engagement event
Event category: EventCategory.EVENT_RETURN
Recommended parameters: NONE

OPENED_PUSH_NOTIFICATION

Description: Track user opened push notification
Event category: EventCategory.OPENED_PUSH_NOTIFICATION
Recommended parameters: NONE

UPDATE

Description: Track update event
Event category: EventCategory.UPDATE
Recommended parameters: CONTENT_ID

4.4 Event parameters

In addition each category that is passed with event may have optional parameters defined as part of the EventParameter enum class, or custom defined as String. Below is a list of recommended parameters.

Parameter enum	Recommended value
EventParameter.REVENUE	FLoat
EventParameter.PRICE	Float
EventParameter.LEVEL	Integer
EventParameter.SUCCESS	Boolean
EventParameter.CONTENT_TYPE	String
EventParameter.CONTENT_LIST	Array of strings
EventParameter.CONTENT_ID	String
EventParameter.CURRENCY	String
EventParameter.REGISTRATION_METHOD	String
EventParameter.QUANTITY	Integer
EventParameter.PAYMENT_INFO_AVAILABLE	Boolean
EventParameter.RATING_VALUE	Float
EventParameter.MAX_RATING_VALUE	Float
EventParameter.SEARCH_STRING	String
EventParameter.DESCRIPTION	String
EventParameter.SCORE	Integer
EventParameter.DESTINATION_A	String
EventParameter.DESTINATION_B	String
EventParameter.CLASS	String
EventParameter.DATE_A	String
EventParameter.DATE_B	String
EventParameter.EVENT_START	Unixtime
EventParameter.EVENT_END	Unixtime
EventParameter.LATITUDE	Double
EventParameter.LONGITUDE	Double
EventParameter.CUSTOMER_USER_ID	String
EventParameter.CUSTOMER_SEGMENT	String
EventParameter.VALIDATED	String
EventParameter.RECEIPT_ID	String
EventParameter.ORDER_ID	String
EventParameter.TUTORIAL_ID	String
EventParameter.ACHIEVEMENT_ID	String
EventParameter.VIRTUAL_CURRENCY_NAME	String
EventParameter.DEEP_LINK	String
EventParameter.OLD_VERSION	String
EventParameter.NEW_VERSION	String
EventParameter.REVIEW_TEXT	String
EventParameter.COUPON_CODE	String
EventParameter.DEPARTING_DEPARTURE_DATE	String
EventParameter.RETURNING_DEPARTURE_DATE	String
EventParameter.DESTINATION_LIST	String[]
EventParameter.CITY	String
EventParameter.REGION	String
EventParameter.COUNTRY	String
EventParameter.DEPARTING_ARRIVAL_DATE	String
EventParameter.RETURNING_ARRIVAL_DATE	String
EventParameter.SUGGESTED_DESTINATIONS	String[]
EventParameter.TRAVEL_START	String
EventParameter.TRAVEL_END	String
EventParameter.NUM_ADULTS	Integer
EventParameter.NUM_CHILDREN	Integer
EventParameter.NUM_INFANTS	Integer
EventParameter.SUGGESTED_HOTELS	String[]
EventParameter.USER_SCORE	Float
EventParameter.HOTEL_SCORE	Float
EventParameter.PURCHASE_CURRENCY	String
EventParameter.PREFERRED_STAR_RATINGS	Integer[2]
EventParameter.PREFERRED_PRICE_RANGE	Integer[2]
EventParameter.PREFERRED_NEIGHBORHOODS	String[]
EventParameter.PREFERRED_NUM_STOPS	Integer
EventParameter.CONTENT	String
EventParameter.PARAM_1	String
EventParameter.PARAM_2	String
EventParameter.PARAM_3	String
EventParameter.PARAM_4	String
EventParameter.PARAM_5	String
EventParameter.PARAM_6	String
EventParameter.PARAM_7	String
EventParameter.PARAM_8	String
EventParameter.PARAM_9	String
EventParameter.PARAM_10	String

5. Additional Configuration (Optional)

5.1 Setting Permissions

SDK will collect data types to which it has permission.

IMPORTANT: On Android >= 6.0 your application must also request for some permissions at runtime.
MobigateSDK doesn’t request for any permissions on its own.(Learnmore)

5.2 Configuring data Collectors

By default, when calling startService() MobigateSDK will collect all kinds of data supported by the SDK and allowed by the permissions from Android manifest (and runtime permissions on Android >=6.0). To ensure that you collect as much data as possible add the following permissions into your application:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" ></uses-permission>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" ></uses-permission>
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" ></uses-permission>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" ></uses-permission>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" ></uses-permission>
<uses-permission android:name="android.permission.READ_PHONE_STATE" ></uses-permission>
<uses-permission android:name="android.permission.GET_PACKAGE_SIZE" ></uses-permission>
<uses-permission android:name="com.android.browser.permission.READ_HISTORY_BOOKMARKS" ></uses-permission>
<uses-permission android:name="android.permission.GET_TASKS" ></uses-permission>
<uses-permission android:name="android.permission.READ_CALENDAR" ></uses-permission>
<uses-permission android:name="android.permission.READ_CONTACTS" ></uses-permission>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" ></uses-permission>
<uses-permission android:name="android.permission.READ_USER_DICTIONARY" ></uses-permission>
<uses-permission android:name="android.permission.BLUETOOTH" ></uses-permission>
<uses-permission android:name="android.permission.NFC" ></uses-permission>
<uses-permission android:name="android.permission.PACKAGE_USAGE_STATS" ></uses-permission>
<uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION" ></uses-permission>

You may specify subset of data types to be collected:

sdk.enableDataCollector(true, new int[] { DataCollector.GEOLOCATION,DataCollector.MEDIA_FILES, DataCollector.BROWSER, … });
sdk.startService(context);

Or add them one by one:

sdk.enableDataCollector(true, DataCollector.BROWSER);
sdk.enableDataCollector(true, DataCollector.GEOLOCATION);
......
sdk.startService(context);

Collectors list:

package pl.spicymobile.mobience.sdk;
/***
* Data collectors
*/
public class DataCollector {
/**
* Collect all application's info on device
* Optional permission:
* android.permission.GET_PACKAGE_SIZE
*/
public final static int APPS_LIST = 0;
/**
* Class collect time active an application
* Required permissions:
* android.permission.PACKAGE_USAGE_STATS (obligatory on android sdk >= Lollipop 5.0)
* android.permission.GET_TASKS (obligatory on android sdk <= Kitkat 4.4)
*/
public final static int APPS_USAGE = 1;
/**
* BatteryInfoCollector collects battery info: level; and charge event
*/
public final static int BATTERY = 2;
/**
* Collecting data on browser history, bookmarks, pharses
* Required permissions:
* com.android.browser.permission.READ_HISTORY_BOOKMARKS (Removed since android sdk >= Marshmallow 6.0) on Android api level < Lollipop 5.0
* turned on accessibility for application on Android api level >= Lollipop 5.0
*/
public final static int BROWSER = 3;
/**
* Collects calendar events data of a device, with a range of days : before 100 days and after 100 days with the collecting day
* Required permissions:
* android.permission.READ_CALENDAR
*/
public final static int CALENDAR_EVENTS = 4;
/**
* Collect process running cpu on device at time request
*/
public final static int CPU_PROCESS = 6;
/**
* Collect all data Dictionary of user on device
* Required permissions:
* android.permission.READ_USER_DICTIONARY
*/
public final static int DICTIONARY = 7;
/**
* Geolocalization coordinates of a device, information of current GSM cell and GSM signal strength
* Required permissions:
* android.permission.ACCESS_FINE_LOCATION or android.permission.ACCESS_COARSE_LOCATION
*/
public final static int GEOLOCATION = 8;
/**
* Collect all data about headset plugin's information
*/
public final static int HEADSET_PLUG = 9;
/**
* Gather Media files information of device
* Required permissions:
* android.permission.WRITE_EXTERNAL_STORAGE3
* android.permission.READ_EXTERNAL_STORAGE3 (on Android api level >= Jelly Bean 4.1)
*/
public final static int MEDIA_FILES = 10;
/**
* Collect used memory info
*/
public final static int MEMORY_USEAGE = 11;
/**
* Collect about connection information: "wifi" or "mobile data" or "no connection"
* Required permissions:
* android.permission.ACCESS_NETWORK_STATE
*/
public final static int NETWORK_CONNECTION = 13;
/**
* Collect all network usage data from all application on device
*/
public final static int NETWORK_USEAGE = 14;
/**
* Collect all package change event (install new app, remove app, data clear, restart app)
*/
public final static int PACKAGE_CHANGE = 15;
/**
* Collect informations of a device, such as: Identifiers of device model, system version, IMSI, IP, network operator of SIM card and mobile network, WiFi network data, etc.
* Optional permission:
* android.permission.READ_PHONE_STATE
* android.permission.ACCESS_NETWORK_STATE
* android.permission.ACCESS_WIFI_STATE
*/
public final static int PHONE_INFO = 16;
/**
* Catch event roaming
* Required permissions:
* android.permission.ACCESS_NETWORK_STATE
*/
public final static int ROAMING = 17;
/**
* Collect data about device's orientation
*/
public final static int SCREEN_ORIENTED = 18;
/**
* Collect phone signal info
*/
public final static int SIGNAL_STRENGTH = 19;
/**
* Collect time change profile mode
*/
public final static int PROFILE_MODE = 20;
/**
* Gather list of visible WiFi networks, information of each wifi
* Required permission:
* android.permission.ACCESS_WIFI_STATE
* Android <= 8.1 (sdk level <= 27):
* android.permission.ACCESS_FINE_LOCATION or android.permission.ACCESS_COARSE_LOCATION
* android.permission.CHANGE_WIFI_STATE
* Android 9.0, 10 (sdk level 28, 29)
* enabled location services
* Applications targeting Android 10 (API level 29) SDK or higher, has the android.permission.ACCESS_FINE_LOCATION
*/
public final static int WIFI_DATA_CONNECTION = 21;
/**
* SDKApp
* ion gathers every week list of all the Android permissions that it have and list of enabled data collectors from MobienceSDK
*/
public final static int PERMISSION_COLLECTOR = 22;
/**
* NFC collector collects information of NFC funtion of that device, contains normal NFC NFED information
* Required permissions:
* android.permission.NFC
*/
public final static int NFC_COLLECTOR = 23;
/**
* Bluetooth collector collects information of Bluetooth funtion of that device, contains normal Bluetooth information
* Required permissions:
* android.permission.BLUETOOTH
*/
public final static int BLUETOOTH_COLLECTOR = 24;
/**
* Bluetooth device collector collects information of detecting connected devices via bluetooth
* Required permissions:
* android.permission.BLUETOOTH
*/
public final static int BLUETOOTH_DEVICES_COLLECTOR = 26;
/**
* Activity recognition collector collects information about detected user activities (walking, running, driving, etc.)
* Required permission:
* com.google.android.gms.permission.ACTIVITY_RECOGNITION
*/
public final static int MOVEMENT_COLLECTOR = 27;
/**
* Facebook collector collect informationabout user
*/
public final static int FACEBOOK_NETWORK_COLLECTOR = 28;
/**
* Root data collector collects information if device is rooted
*/
public final static int ROOT_COLLECTOR = 29;
/**
* Total collectors size
*/
public final static int TOTAL_SIZE = 27;
}

5.3 Set email

To set user’s email, call:

MobigateSDK.get().setEmail("your_email");

Or with builder method:

SDK sdk = new MobigateSDK.Builder(getApplicationContext(),"Api_key").setEmail("your_email").build();

5.4 Custom user ID

You may use your custom userID for marking data. By default we are using device ID and emails for matching. Set it before starting the service using MobigateSDk.Builder method.

MobigateSDK.Builder(getApplicationContext(),"Api_key").setCustomUserID("customID").build();

5.5 User and device identification

MobigateSDK is gathering following user/device identifiers:

ANDROID_ID,

Android AdvertisingID (AAID) - requires Google Play Services implemented in app and available on device,

Mobigate own device ID (random UUID stored permanently on the device),

custom user ID, if set by method setCustomUserID(),

e-mail - provided by setEmail() method or read automatically if GET_ACCOUNTS permission is granted. This is usually user’s e-mail from Google Play account,

Wi-Fi MAC address - when Wi-Fi is enabled and ACCESS_WIFI_STATE permission is granted,

device’s „serial” number, as provided by Android,

IMEI - if device has telephony module. Requires READ_PHONE_STATE permission.

By default MobigateSDK is gathering all identifiers, which it can read. You can indicate which fields gather to comply with your privacy policy. To specify gathering of given identifier, call Builder:

MobigateSDK.Builder().enableUserField(SDK.UserField... fields)

Identifiers that can be disabled are: EMAIL, MAC, SERIAL, IMEI, IMSI.

5.6 Logging and debugging

Logging is enabled only while application is in DEBUG mode and is on by default.

5.7 SDK information

To get SDK info (version):

MobigateSDK.get().getSDKInfo();

5.8 Data gather policy

By default, on Android phones with sdk level lower than 26 MobigateSDK does not display a persistent notification when the service starts, but gathers data in the background
On Android phones with sdk level >= 26 Google Play rules prohibit collecting data in background, without notification for user (Learn more). In that case MobigateSDK by default block data gathering in background. You can change the default behavior by use the Builder following method:

MobigateSDK.Builder().setDataGatherPolicy(SDK.MONITOR_STATE.DEFAULT,"optional_notification_text")

Possible monitor states:

SDK.MONITOR_STATE.DEFAULT,

SDK.MONITOR_STATE.HIDE_TRAY,

SDK.MONITOR_STATE.BLOCK_DATA_BG.

5.9 Advertising systems

Method that returns the IDs user profiles

Software MobigateSDK based on data collected assigns user IDs profile. IDs can be use to send to an ad server.
To enable functionality (only once, necessarily before the first call Mobigate.startService()):

MobigateSDK.get().enableIDsProfiles(true);

To get the IDs profiles for the user (at any time and anywhere in the application):

MobigateSDK.get().getIDsProfiles();

List of IDs profiles in the application memory is updated (synchronized with the server) at specified intervals.

Optional integration with AdOcean module from GemiusSDK

Map<String, Long> MobigateSDK.get().getAdOceanTargeting();

This method is intended for use with "setNumericalVariables" method from GemiusSDK (AdOcean module).
Sample usage:

FullScreenAd interstitial1 = new FullScreenAd(context, INTERSTITIAL1_PLACEMENT_ID);
interstitial1.setNumericalVariables(MobigateSDK.getAdOceanTargeting());
interstitial1.open();

Same applies to billboard adds.

This way user identifiers are passed to AdOcean AdServer as „numerical variables”, that can be used for ads targeting.

getAdOceanTargeting() method returns 3 different identifiers of a user, encoded into a map of AdOcean numerical variables.

Mobigate user identifier,

ANDROID_ID,

Android Advertising ID (requires Google Play Services implemented in app and available on device).

Please ask our representative for instructions on configuring targeting in AdOcean panel.

6. Testing SDK integration

Integrating our SDK is easy and straightforward. Nevertheless, we highly recommend that you test the integration before submitting the app to the app store.
The easiest way to test integration is to install our testing application from the play store. You can find it here

Testing application is very simple. After installation, point your application from list and run the test. The result will appear in a new application window. If no warning signs have appeared, it means that the library is well integrated into your application.