Ketch Smart Tag for an Android app

This document demonstrates the Ketch Smart Tag usage for the Kotlin based native Android application.

It handles the storage of the corresponding policy strings to SharedPreferences,
as per standards requirements for the in-app support:

Prerequisites

Registered Ketch organization account
Configured application property record
Custom identity space
index.html containing the Ketch Smart Tag integration bridge and Kotlin utility classes.

Quick Start

Before we start, take a look at the fully functional sample Android app, where the following steps are implemented, integrating the Ketch Smart Tag into your Kotlin based Android project.

Step 1. Copy the integration bridge into the app

Create [module]/app/src/main/assets folder and put the index.html file there.

The index.html file makes use of Android WebView and JavascriptInterface to
communicate back and forth with the native runtime of the Android application.

Step 2. Create the activity with the WebView

Copy the following files to your module package:

These helper classes cover the communication with the JavaScript SDK running inside the webview and storage of the corresponding policy strings.

Step 3. Initialize the activity and helper classes

Initialize the KetchSharedPreferences instance

class MainActivity : AppCompatActivity() {
    
    ...

    private val sharedPreferences: KetchSharedPreferences by lazy {
        KetchSharedPreferences(this)
    }

    ...
}

Add the private member for storing the advertising ID and loading routines.

AAID is the suitable way to identify anonymous users,
and we use it in this example for the sake of simplicity.

There are other ways to provide the user's identity information.

class MainActivity : AppCompatActivity() {

    ...

    private val advertisingId = MutableStateFlow<String?>(null)

    @OptIn(DelicateCoroutinesApi::class)
    private fun loadAdvertisingId() {
        GlobalScope.launch(Dispatchers.IO) {
            try {
                AdvertisingIdClient.getAdvertisingIdInfo(applicationContext).id
            } catch (e: Exception) {
                e.printStackTrace()
            } finally {
                launch(Dispatchers.Main) {
                    progressBar.isVisible = false
                }
            }
        }
    }

    ...

}

Step 4. Setup the intent with the Ketch JS SDK configuration

Create the webview class or use KetchWebView from this sample. Add ths view to your your main activity layout. In works in a similar way to The Ketch Smart Tag on the HTML page that expects an organization code and app property code to be passed in to it.

Organization code ORG_CODE could be found on the Organization Settings

App property code PROPERTY could be found on the Properties Management

Advertising ID code ADVERTISING_ID_KEY is available on the Identity Spaces

The preferences screen is triggered on the button click in this example, but it could also be triggered automatically on application start.

class MainActivity : AppCompatActivity() {

    ...

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        supportActionBar?.hide()

        ketchWebView.listener = object : KetchWebView.KetchListener {
            override fun onCCPAUpdate(ccpaString: String?) {
                sharedPreferences.saveUSPrivacyString(ccpaString)
            }

            override fun onTCFUpdate(tcfString: String?, tcfApplies: Int?) {
                sharedPreferences.saveTCFTCString(tcfString)
                sharedPreferences.saveTCFGdprApplies(tcfApplies)
            }

            override fun onSave() {
                mainLayout.isVisible = false
            }

            override fun onCancel() {
                mainLayout.isVisible = false
            }

        }

        button.setOnClickListener {
            ketchWebView.show()
            mainLayout.isVisible = false
        }

        collectState(advertisingId) {
            button.isVisible = it != null

            it?.let { aaid ->
                progressBar.isVisible = false

                // identities to be passed to the WebView displaying the Ketch Preference Center
                val identities = ArrayList<Identity>()
                identities.add(Identity(ADVERTISING_ID_CODE, aaid))

                ketchWebView.init(ORG_CODE, PROPERTY, identities)
            }
        }

        progressBar.isVisible = true

        loadAdvertisingId()
    }

    ...

    companion object {
        private const val ORG_CODE = "<organization code>"
        private const val PROPERTY = "<property>"
        private const val ADVERTISING_ID_CODE = "<advertising field code>"
    }
    ...
}

Now when you run your application and have the Ketch account properly setup, you will see the corresponding policy strings added to your default SharedPreferences.

DONE!

Check out our Android samples repo for a full example.