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:

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):

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:

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:

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:

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.

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.

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:

•  You may specify subset of data types to be collected:

•  Or add them one by one:

• Collectors list:

5.3 Set email

• To set user’s email, call:

• Or with builder method:

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. 

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:

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):

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:

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

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

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

• Optional integration with AdOcean module from GemiusSDK

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

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.