SDK-Android | Vpon - Data SDK Link Search Menu Expand Document
Data SDK

Android SDK

Dive into the world of Data SDK integration with this comprehensive guide!

Here, we break down how to supercharge your App with key features such as Auto Events, Custom Events, and Background Geolocation Collection. Follow these simple steps:

  1. Check the Prerequisites
  2. Download Data SDK
  3. Set up App Configurations
  4. Initialize Data SDK
  5. Set up Background Geolocation Collection (Optional)
  6. Set up Custom Events (Optional)
  7. Test in Debug Mode

Upon completing first four steps, you’ll have fulfilled the minimum requirements and enabled Auto Events tracking in your App.

Step 5 involves the optional setup of Background Geolocation Collection. This powerful feature allows continuous gathering of geolocation data from users, even when your App runs in the background, to provide more personalized experiences and services.

Step 6 allows you to set up Custom Events according to your App’s design and user needs. While optional, we highly recommend creating suitable custom events to obtain a comprehensive view of your App users.

Lastly, in step 7, use the Debug Mode to verify your integration status. Debug Mode facilitates testing of all SDK configurations, including Background Geolocation Collection, Auto & Custom events, before launching your App on various platforms. We recommend enabling Debug Mode to ensure everything is functioning as expected, and then disabling it before your App’s publication.

This guide is designed to make the integration process intuitive and efficient, letting you focus on building and enhancing your App.

Check the Prerequisites

Ensure that your App supports Android version 5.0 or later before proceeding with the Data SDK integration.

Download Data SDK

Start by downloading the Data SDK HERE. Once downloaded, include the aar file in your Android Studio project.

Set up App Configurations

Build dependencies

In your module (app-level) Gradle file (usually <project>/<app-module>/build.gradle ), modify dependencies as below.

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
    ...
    implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0'

    //coroutines
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.9'
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.9'
}

If you choose to activate background geolocation data collection, also add Google Play Service Location dependency

dependencies {
    ...
    //for background gelocation collection
    implementation 'com.google.android.gms:play-services-location:21.0.1'
}

Adjust Permissions

To ensure the maximum functionality of the Data SDK, it’s essential to modify your AndroidManifest.xml file to include specific permissions. Here’s the suggested way to do it:

Required Permissions

These permissions are necessary for the SDK to operate effectively. Make sure to include these in your AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE"/>

We recommend adding these additional permissions to your AndroidManifest.xml file to enable data collection for network information and geolocation:

<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

While these permissions are technically optional, adding them is strongly advised to take full advantage of the SDK’s features.

Background Geolocation Permission

If you choose to activate background geolocation data collection, add this optional permission:

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>

For more details about these permissions, refer to the Permission.

Initialize Data SDK

Initialize Data SDK in your main Application. This ensures the Auto Events feature operates correctly.

You’ll also manage the License Key, Opt-in, and Debug Mode in this step.

License Key

Upon approval of your application, you’ll receive a unique license key. If you encounter any issues or haven’t received your key, please refer to the Integration Process for further details or email Vpon’s support team for additional support.

Opt-In

Data SDK respects user privacy by only collecting data with the user’s explicit consent, meaning data is gathered only when a user agrees to your App’s terms of use or privacy policy.

To help you manage this consent effectively, Data SDK offers three Opt-In options: DEFAULT, CONSENT, and NOCONSENT.

  • DEFAULT: neither granted nor declined
  • CONSENT: granted
  • NOCONSENT: declined

We recommend determining the status of user consent in the initialization step, then updating the Opt-In option and forwarding it to Data SDK depending on the latest permission status. If Opt-In is set to either NOCONSENT or DEFAULT, warning messages will display on the developer console.

Here’s a setup example of License Key and Opt-in:

  • vpdataAnalytics.initialize(this, licenseKey, customerId, VpdataAnalytics.OptIn.CONSENT);

  • vpdataAnalytics!!.initialize(this, licenseKey, customerId, VpdataAnalytics.OptIn.CONSENT)

Debug Mode

Debug Mode allows you to interactively test your App events, including Auto, Custom, and Background Geolocation Collection.

We recommend enabling Debug Mode and providing the Debug Mode log to Vpon Vpon’s support team before submitting your App to various marketplaces, ensuring correct integration settings. If everything is working as expected, disable Debug Mode before publishing your App.

For more detailed information, you can refer to the sections on Debug Mode and Integration Process.

Here’s how to toggle Debug Mode:

  • // Turn Debug Mode on
vpdataAnalytics.setDebugMode(true);

// Turn Debug Mode off
vpdataAnalytics.setDebugMode(false);

  • // Turn Debug Mode on
vpdataAnalytics!!.setDebugMode(true)

// Turn Debug Mode off
vpdataAnalytics!!.setDebugMode(false)

Here’s a complete example that demonstrates how to initialize the Data SDK:

In your main Application

  • import com.vpon.sdk.VpdataAnalytics;

// Opt-In options: 
// VpdataAnalytics.OptIn.DEFAULT 
// VpdataAnalytics.OptIn.CONSENT
// VpdataAnalytics.OptIn.NOCONSENT

// Debug Mode options: true/false

public class MainApplication extends Application {
    // Set your license_key & customer_id
    private String licenseKey = "testKey";
    private String customerId = "";

    // Configure Opt-In as VpdataAnalytics.OptIn.CONSENT when a user gives consent
    // Turn Debug Mode on
    @Override
    public void onCreate() {
        super.onCreate();
        VpdataAnalytics vpdataAnalytics = VpdataAnalytics.INSTANCE;

        // Set up before vpdataAnalytics.initialize
        vpdataAnalytics.setDebugMode(true);

        // Set up license_key and opt-in
    	// If a user gives their consent, configure Opt-In as CONSENT
        vpdataAnalytics.initialize(this, licenseKey, customerId, VpdataAnalytics.OptIn.CONSENT);  
    }
}

  • import com.vpon.sdk.VpdataAnalytics

// Opt-In options: 
// VpdataAnalytics.OptIn.DEFAULT 
// VpdataAnalytics.OptIn.CONSENT
// VpdataAnalytics.OptIn.NOCONSENT

// Debug Mode options: true/false

class MainApplication : Application() {
    // set up your license_key & customer_id
    private val licenseKey = "testKey"
    private val customerId = ""
    
    // Configure Opt-In as VpdataAnalytics.OptIn.CONSENT when a user gives consent
    // Turn Debug Mode on
    override fun onCreate() {
        super.onCreate()
        val vpdataAnalytics = VpdataAnalytics
	
        // Set up before vpdataAnalytics.initialize
        vpdataAnalytics!!.setDebugMode(true)
	
        // Set up license_key and opt-in
        vpdataAnalytics!!.initialize(this, licenseKey, customerId, VpdataAnalytics.OptIn.CONSENT)
    }
}

Set up Background Geolocation Collection

Background Geolocation Collection is a powerful feature that allows continuous geolocation data collection, even when your App is running in the background. However, it’s essential to respect user privacy and adhere to Google’s guidelines when implementing this feature.

Before using this function, ensure that your project settings and permissions are properly set up. You can refer to the Background Geolocation Collection and Permission sections for more details on this.

To integrate the Background Geolocation Collection feature into your Android App, follow these steps:

  1. Initialization: Make sure the Data SDK is properly initialized in your App before you start using the background geolocation collection feature.

  2. Start/Stop Interface: Data SDK provides an interface that allows App developers to easily call and control the geolocation tracking. When calling the startBackgroundLocationUpdate method to begin collecting geolocation data, remember to set up the frequency for data collection as needed. Use the stopBackgroundLocationUpdate method to stop the data collection when it’s no longer required.

  3. Accuracy Level Configuration: The SDK allows you to set the level of accuracy for geolocation data collection. There are three options available: high, mid, and low accuracy respectively. Note that the accuracy level and the frequency of updates may affect the App’s battery usage, so choose your settings carefully.

Here is a sample code snippet to use these methods:

  • // to start geolocation collection with mid accuracy
VpdataAnalytics.INSTANCE.startBackgroundLocationUpdate(VpdataAnalytics.Frequency.MID);

// to stop geolocation collection
VpdataAnalytics.INSTANCE.stopBackgroundLocationUpdate();

// three accuracy options: high/mid/low
// high accuracy 
VpdataAnalytics.INSTANCE.startBackgroundLocationUpdate(VpdataAnalytics.Frequency.HIGH);
// mid accuracy
VpdataAnalytics.INSTANCE.startBackgroundLocationUpdate(VpdataAnalytics.Frequency.MID);
// low accuracy
VpdataAnalytics.INSTANCE.startBackgroundLocationUpdate(VpdataAnalytics.Frequency.LOW);

  • // to start geolocation collection with mid accuracy
VpdataAnalytics.startBackgroundLocationUpdate(VpdataAnalytics.Frequency.MID)

// to stop geolocation collection
VpdataAnalytics.stopBackgroundLocationUpdate()

// three accuracy options: high/mid/low
// high accuracy 
VpdataAnalytics.startBackgroundLocationUpdate(VpdataAnalytics.Frequency.HIGH)    
// mid accuracy
VpdataAnalytics.startBackgroundLocationUpdate(VpdataAnalytics.Frequency.MID)
// low accuracy
VpdataAnalytics.startBackgroundLocationUpdate(VpdataAnalytics.Frequency.LOW)

Once you have integrated the feature, you should test it to ensure it’s working correctly. We recommend using the Debug Mode for this purpose. This mode allows you to interactively test your App events, including the geolocation collection, with messages displayed in the developer console.

Set up Custom Events

Custom events are a powerful tool to gain insights into user behavior, and Data SDK makes it simple to set them up.

By utilizing the tracker method, you can set up events that carry unique names and contain additional data you wish to gather. The strength of this feature lies in its flexibility - there’s no cap on the number of events you can set up, making it adaptable to your App’s specific design and business goals.

Below, you will find examples of how to set up these custom events, along with representations of how the collected data may appear in a JSON string format on a mobile device. It’s crucial to note that this data is encrypted for user privacy and cannot be directly accessed via the App developer console.

Let’s consider an example where you’re running an e-commerce App and you want to establish a conversion funnel. In this case, tracking user interactions with various product items becomes essential. By leveraging the tracker method, you can swiftly set up an item_view event that collects details such as the product’s ID, size, color, and price.

  • public void onClick(View v) {
	JSONObject payloadJsonObj = new JSONObject();
	try {
		payloadJsonObj.put("id", "payloadJsonObj");
		payloadJsonObj.put("name", "Coat");
		payloadJsonObj.put("price", 100);
		payloadJsonObj.put("color", "Blue");
		payloadJsonObj.put("size", "XL");
		payloadJsonObj.put("currency", "NTD");
		} catch (JSONException e) {
		e.printStackTrace();
	    }
	tracker.sendEvent("item_view", payloadJsonObj);
}

  • val sendClickListener = View.OnClickListener {
        val payloadJsonObj = JSONObject();
        try {
            payloadJsonObj.put("id", "payloadJsonObj");
            payloadJsonObj.put("name", "Coat");
            payloadJsonObj.put("price", 100);
            payloadJsonObj.put("color", "Blue");
            payloadJsonObj.put("size", "XL");
            payloadJsonObj.put("currency", "NTD");
        } catch (e: JSONException) {
            e.printStackTrace();
        }
        tracker?.sendEvent("item_view", payloadJsonObj);
    }

  • {
    "event_name": "item_view"
    "id": "03356",
    "name": "Coat", 
    "price": 100, 
    "color": "Blue", 
    "size": "XL", 
    "currency": "NTD"
}

Similarly, if you’re operating an Online Travel Agency (OTA) App and want to optimize the user experience by understanding their browsing history, the tracker method can assist. It enables the configuration of a page_view event, tracing the user’s navigation journey through your App.

  • public void onClick(View v) {
	JSONObject payloadJsonObj = new JSONObject();
	try {
		payloadJsonObj.put("previous", "URL of Last Page");
		payloadJsonObj.put("current", "URL of Current Page");
	} catch (JSONException e) {
		e.printStackTrace();
	}
	tracker.sendEvent("page_view", payloadJsonObj);
}

  • val sendClickListener = View.OnClickListener {
        val payloadJsonObj = JSONObject()
        try {
            payloadJsonObj.put("pervious", "URL of Last Page")
            payloadJsonObj.put("current", "URL of Current Page")
        } catch (e: JSONException) {
            e.printStackTrace()
        }
        tracker?.sendEvent("page_view", payloadJsonObj)    
    }

  • {
    "event_name": "page_view"
    "previous": "URL of Last Page", 
    "current": "URL of Current Page"
}

Sample Code

See also Sample Code for a complete integration reference.

Download

Data SDK 2.0.5
Download