DASOMAN Mobile SDK

The DASOMAN Mobile SDK is available for Android. The DASOMAN Mobile SDK allows the tracking of user data and provides functionality that allows the enduser to allow / disallow tracking of specific items.

Preparation

Download the DASOMAN Keygenerator for Linux or macOS and use it to generate a key pair. Your server will need the private key and we will need the public key. To generate the key pair use:

java -classpath PalisadeWrapper.jar de.dasoman.Main ./where/to/put/keys

First please request access via e-mail to DASOMAN Middleware to register your Application. This will allow you to create the necessary configuration to be able to use the DASOMAN Mobile SDK. In this wizard you are asked to define which data your application wants to track. You can only track data defined here.

You should end up with two pieces of information. First the tracking_config.json and second a hash off the first. Save the file and copy the hash, you will need these values later on.

Setup

Getting the DASOMAN Mobile SDK

You can either download the latest release from here or simply integrate the DASOMAN Mobile SDK using gradle. Using gradle you can simply include the DASOMAN Mobile SDK as a dependency:

repositories {
    maven {
        url  "https://dl.bintray.com/letsdev/public"
    }
}
dependencies {
    implementation 'de.dasoman:Dasoman:2.2.1'
}

Please consider that the DASOMAN Mobile SDK currently supports only x86_64 and arm64 processor architectures.

Integrating the DASOMAN Mobile SDK

Initialization

Before any other calls to the DASOMAN Mobile SDK are made it has to be initialized by calling:

DasomanXPActivity.getInstance().doInitialize(application)

Where application is your app Application. If done in an Activity it can be retrieved by calling getApplication().

Next a callback has to be registered that allows the DASOMAN Mobile SDK to receive the information which we obtained while registering the App on the DASOMAN website. Your application has to implement the LDAnalyticsManagerCallbackInterface. The callback forces your App to implement two methods:

override fun getKeyConfigPath(): String {   
    return "/path/to/tracking_config.json"
}

override fun getConfigHash(): String {
    return "theHashValue"
}

Here the return value of getKeyConfigPath is an absolute path to the config file we created earlier. The second method getConfigHash has to return the corresponding hash value.

Getting user consent

The user has to consent to the data tracking and encrypted transmission to DASOMAN. This is not yet the data being sent to the provider, your backend. Make sure to explain to your user, that the data is only sent encrypted to DASOMAN and it can not be decrypted.

LDAnalyticsManager.getInstance().isTrackingAllowed = true

Again this does not the consent to transfer the data to your backend. This is only to consent to the encrypted data tracking and transmission. To get consent on transferring the data see below. The DASOMAN Mobile SDK will not take any actions if this consent is not given.

Tracking Values

The LDAnalyticsManager allows you to track data. We have two different types of tracked elements. The first being tracking of data:

val result = LDAnalyticsManager.getInstance()
                .trackDataString("myTrackingKey", "myTrackedData");
when(result){
    LDTrackingResult.OK -> TODO()
    LDTrackingResult.INVALID_KEY -> TODO()
    LDTrackingResult.INVALID_TYPE -> TODO()
    LDTrackingResult.INVALID_FORMAT -> TODO()
}

The myTrackingKey has to be a key that was registered when creating the configuration. The data is the string data tracked. The possible return values are:

  • OK: The data was successfully tracked. This does not necessarily mean it has already been uploaded. Data ist first recorded locally and uploaded ASAP when a internet connection exists.
  • INVALID_KEY: The passed first argument is a key not present in the configuration.
  • INVALID_TYPE: The tracked data was configured with a different datatype as was tracked.
  • INVALID_FORMAT: Only applicable for type DATE. The passed format was not recognized and the data could not be tracked.

There is similar tracking functions for all supported datatypes.

The second possible tracking element is what we call event. It is for tracking things that happened without data. This can be used to e.g. track the click of a button. The tracking itself is very similar to data tracking by calling:

val result = LDAnalyticsManager
                .getInstance()
                .trackEvent("myEventTrackingKey")
    when(result){
        LDTrackingResult.OK -> TODO()
        LDTrackingResult.INVALID_KEY -> TODO()
        LDTrackingResult.INVALID_TYPE -> TODO()
        LDTrackingResult.INVALID_FORMAT -> TODO()
    }

The key again has to be a valid key that was registered for tracking when creating the configuration. Here only OK or INVALID_KEY is returned.

Showing Tracking selection to user

Per default all tracked data is recorded, but kept encrypted at the DASOMAN middleware. Only user approved data is being transmitted to the actual provider backend (your backend!). There is two ways your App can approve data for tracking. Both variants should only be done through user interaction. The first is a call to:

LDAnalyticsManager.getInstance().setEnableAllKeys(true)

This allows the tracking of all data and events. It has to actively be approved by the user!

The second way is to show the DASOMAN Mobile SDK's tracking selection screen. This screen shown the user which data is being tracked and a way to deactivate / activate tracking for each data individually. The screen can be shown as follows:

val preferencesController = AnalyticsPreferencesControllerFactory
                                .createPreferencesController()

val controllerKey = "show-tracking-preferences-controller"

ObjectCache.getInstance().setObject(controllerKey, preferencesController)

val preferencesFragment = PreferencesFragment.newInstance(controllerKey)

The fragment can then be shown as usual for Android.

If you do this right now you will see a controller with a lot of missing strings, but the general structure should fit all the data you are tracking in your add with the possibility for the user to activate / deactivate each value individually.

Localization

There are a handful of localizations the App has to provide for each tracked value. These have to be added as usual to the strings.xml. Which keys are necessary depends on the type of the tracked data or event.

For tacking events:

We assume a key my_tracking_key is being tracked:

Key Description
my_tracking_key Give your key a descriptive name. E.g. "Home screen visible event"
my_tracking_key_description A detailed description of when and why this event is being tracked

For data input:

Valid for all of the following types: String, Double, Integer, Date.

We assume a key my_tracking_data is being tracked:

Key Description
my_tracking_data Give your key a descriptive name. E.g. "Date of Birth"

For selection:

We assume a key my_tracking_selection is being tracked and the possible values are my_value_1, my_value_2, my_value_3:

Key Description
my_tracking_selection Give your key a descriptive name. E.g. "Sex"
my_value_1 The value that is supposed to show when for this key is shown. E.g. "Female"
my_value_2 The value that is supposed to show when for this key is shown. E.g. "Male"
my_value_3 The value that is supposed to show when for this key is shown. E.g. "Other"

For selection a localization for each possible value has to exist.