Skip to content

Kotlin SDK for integrating with an Optable Data Connectivity Node from an Android application.

License

Notifications You must be signed in to change notification settings

Optable/optable-android-sdk

Repository files navigation

Optable Android SDK

Kotlin SDK for integrating with optable-sandbox from an Android application.

Installation

This SDK is published using JitPack, so to add it to your application build, follow the JitPack How To.

If you're using gradle, add the following in your root build.gradle at the end of repositories:

allprojects {
    repositories {
        ...
        maven {
            url 'https://jitpack.io'
            credentials { username authToken }
        }
    }
}

In order to allow JitPack to access this private GitHub repository, add the following authToken to your gradle.properties:

authToken=jp_usu041v753rg6asheri00bjihl

Finally, add the dependency to the SDK in your app build.gradle:

dependencies {
    implementation 'com.github.Optable:optable-android-sdk:VERSION_TAG'
}

Remember to replace VERSION_TAG with the latest or desired SDK release.

Using (Kotlin)

To configure an instance of the SDK integrating with an Optable sandbox running at hostname sandbox.customer.com, from a configured application origin identified by slug my-app, you can instantiate the SDK from an Activity Context, such as for example the following application MainActivity:

import co.optable.android_sdk.OptableSDK
...

class MainActivity : AppCompatActivity() {
    companion object {
        var OPTABLE: OptableSDK? = null
    }
    ...
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        ...
        MainActivity.OPTABLE = OptableSDK(this, "sandbox.customer.com", "my-app")
        ...
    }
}

You can then call various SDK APIs on the instance as shown in the examples below. It's also possible to configure multiple instances of OptableSDK in order to connect to other (e.g., partner) sandboxes and/or reference other configured application slug IDs.

Note that all SDK communication with Optable sandboxes is done over TLS. The only exception to this is if you instantiate the OptableSDK class with a fourth optional boolean parameter, insecure, set to true. For example:

MainActivity.OPTABLE = OptableSDK(this, "sandbox.customer.com", "my-app", true)

However, since production sandboxes only listen to TLS traffic, the above is really only useful for developers of optable-sandbox running the sandbox locally for testing.

Identify API

To associate a user device with an authenticated identifier such as an Email address, or with other known IDs such as the Google Advertising ID, or even your own vendor or app level PPID, you can call the identify API as follows:

import co.optable.android_sdk.OptableSDK
import my.org.app.MainActivity
import android.util.Log
...

val emailString = "[email protected]"
val sendGoogleAdIDBoolean = true
val ppid = "my-id-123"

MainActivity.OPTABLE!!
    .identify(emailString, sendGoogleAdIDBoolean, ppid)
    .observe(viewLifecycleOwner, Observer
    { result ->
        if (result.status == OptableSDK.Status.SUCCESS) {
            Log.i("Identify API Success")
        } else {
            // result.status is OptableSDK.Status.ERROR
            // result.message is the error message
            Log.e("Identify API Error: ${result.message}")
        }
    })

The SDK identify() method will asynchronously connect to the configured sandbox and send IDs for resolution. The second (sendGoogleAdIDBoolean) and third (ppid) arguments to identify() are optional. You can register an observer to understand successful completion or errors.

⚠️ Client-Side Email Hashing: The SDK will compute the SHA-256 hash of the Email address on the client-side and send the hashed value to the sandbox. The Email address is not sent by the device in plain text.

Since the sendGoogleAdIDBoolean value provided to identify() is true, the SDK will fetch and send the Google Advertising ID in the call to identify too, unless the user has turned on "Limit ad tracking" in their Google device advertising settings.

The frequency of invocation of identify is up to you, however for optimal identity resolution we recommended to call the identify() method on your SDK instance every time you authenticate a user, as well as periodically, such as for example once every 15 to 60 minutes while the application is being actively used and an internet connection is available.

Targeting API

To get the targeting key values associated by the configured sandbox with the device in real-time, you can call the targeting API as follows:

import co.optable.android_sdk.OptableSDK
import my.org.app.MainActivity
import android.util.Log
...
MainActivity.OPTABLE!!
    .targeting()
    .observe(viewLifecycleOwner, Observer { result ->
        if (result.status == OptableSDK.Status.SUCCESS) {
            Log.i("Targeting API Success... ")

            // result.data!! can be iterated to get targeting key values:
            result.data!!.forEach { (key, values) ->
                Log.i("Targeting KV: ${key} = ${values}")
            }
        } else {
            // result.status is OptableSDK.Status.ERROR
            // result.message is the error message
            Log.e("Targeting API Error: ${result.message}")
        }
    })

On success, the resulting key values are typically sent as part of a subsequent ad call. Therefore we recommend that you either call targeting() before each ad call, or in parallel periodically, caching the resulting key values which you then provide in ad calls.

Witness API

To send real-time event data from the user's device to the sandbox for eventual audience assembly, you can call the witness API as follows:

import co.optable.android_sdk.OptableSDK
import co.optable.android_sdk.OptableWitnessProperties
import my.org.app.MainActivity
import android.util.Log
...
MainActivity.OPTABLE!!
    .witness("example.event.type", hashMapOf("example" to "value"))
    .observe(viewLifecycleOwner, Observer { result ->
        if (result.status == OptableSDK.Status.SUCCESS) {
            Log.i("Witness API Success... ")
        } else {
            // result.status is OptableSDK.Status.ERROR
            // result.message is the error message
            Log.e("Witness API Error: ${result.message}")
        }
    })

The specified event type and properties are associated with the logged event and which can be used for matching during audience assembly.

Note that event properties are of type OptableWitnessProperties which is an alias for HashMap<String,String>, and should consist only of string keyvalue pairs.

Integrating GAM360

We can further extend the above targeting example to show an integration with a Google Ad Manager 360 ad server account:

import co.optable.android_sdk.OptableSDK
import my.org.app.MainActivity
import android.util.Log
import com.google.android.gms.ads.doubleclick.PublisherAdRequest
import com.google.android.gms.ads.doubleclick.PublisherAdView
...
MainActivity.OPTABLE!!
    .targeting()
    .observe(viewLifecycleOwner, Observer { result ->
        // Build GAM360 ad request:
        var adRequest = PublisherAdRequest.Builder()

        if (result.status == OptableSDK.Status.SUCCESS) {
            Log.i("Targeting API Success... ")

            // result.data!! can be iterated to get targeting key values:
            result.data!!.forEach { (key, values) ->
                // Add key values to GAM360 ad request:
                adRequest.addCustomTargeting(key, values)
                Log.i("Targeting KV: ${key} = ${values}")
            }
        } else {
            // result.status is OptableSDK.Status.ERROR
            // result.message is the error message
            Log.e("Targeting API Error: ${result.message}")
        }

        // Assuming pubAdView refers to a pre-configured instance of
        // com.google.android.gms.ads.doubleclick.PublisherAdView:
        pubAdView.loadAd(adRequest.build())
    })

A working example is available in the demo application.

Demo App

The demo application shows a working example of both identify and targeting APIs, as well as an integration with the Google Ad Manager 360 ad server, enabling the targeting of ads served by GAM360 to audiences activated in the Optable sandbox.

By default, the demo application will connect to the Optable demo sandbox at sandbox.optable.co and reference application slug android-sdk-demo. The demo app depends on the GAM Mobile Ads SDK for Android and loads ads from a GAM360 account operated by Optable.

Building

From Android Studio, navigate to File > Open and open the DemoApp/DemoAppKotlin directory. You should be able to build and run the resulting project directly, since it will automatically download the co.optable.android_sdk library from JitPack Maven repository.

About

Kotlin SDK for integrating with an Optable Data Connectivity Node from an Android application.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published