Skip to main content

Android

This guide shows you how to integrate with Kevel Audience's HTTP API on Android using Kotlin with the built-in javax.net.ssl and org.json packages. If using Java or other libraries, adapt accordingly.

Keep in mind these are simple examples without error handling, retry logic, or other production considerations that should be included in your final implementation. Additionally, the code snippets reference variables and objects that are not instantiated here but should be provided by you based on your specific implementation requirements.

Setup​

Permissions​

Make sure you give your application internet access by extending your AndroidManifest.xml with:

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

For more information, see:

Usage​

Collecting IDs​

In Android, User IDs should always be explicitly provided when executing requests to the HTTP API (along with the cookies query parameter set to false, when applicable to the endpoint). We recommend taking a look at Android's documentation about Best practices for unique identifiers.

Using Your Own First-Party IDs​

You can use any ID in our list of supported IDs. If you would like to use one not present in the list, please contact our support in order for it to be added.

Using the GAID​

Google Advertising ID (GAID) is a user-resettable identifier that uniquely identifies a particular user for advertising use cases.

This ID can be fetched using Google Play Service's ads identifier library. A comprehensive guide with examples on how to get the GAID can be found in Android's documentation in Get a user-resettable advertising ID. Once its obtained, it can be used like any other ID.

User ID Matches​

Match requests are used to link multiple identifiers in Kevel Audience. This way, any action made with any of the identifiers, across multiple channels (browser, mobile app, CRM, etc), can be associated to the same user.

A typical use case for this is, for example, during the login action, to associate the user's email with Google's Advertising ID.

To send a match request, provide the provider ID which will be associated with the match event along with the two (or more) User IDs to merge via the request's query parameters.

import androidx.core.net.toUri
import java.net.URL
import javax.net.ssl.HttpsURLConnection

val matchUri = "https://match.cdp.$websiteDomain/match".toUri().buildUpon()
    .appendQueryParameter("providerId", providerId)
    .appendQueryParameter("id_$idType1", id1)
    .appendQueryParameter("id_$idType2", id2)
    .appendQueryParameter("cookies", "false")

// Network requests aren't allowed in main thread. Get adequate scope from context.
// See https://kotlinlang.org/docs/coroutines-guide.html for more info.
coroutineScope.launch(Dispatchers.IO) {
    val conn = (URL(matchUri.toString()).openConnection() as HttpsURLConnection).apply {
        requestMethod = "GET"
        setRequestProperty("User-Agent", userAgent)
    }

    try {
        // Trigger the request
        conn.responseCode
    } finally {
        conn.disconnect()
    }
}

For more information refer to Cross-Channel Matches.

Collecting Events​

A tracking event will log a user action in Kevel Audience, allowing you to collect activity performed in your application.

In order to send a tracking event, provide the event via the POST's JSON body and the User ID to associate the event to via the request's query parameters.

import androidx.core.net.toUri
import org.json.JSONObject
import java.net.URL
import javax.net.ssl.HttpsURLConnection

val event = """{
    "clientId": "velocidi",
    "siteId": "velocidi.com",
    "type": "pageView",
    "title": "My page",
    "pageType": "homepage",
    "category": "Shopping"
}"""

val trackUri = "https://tr.cdp.$websiteDomain/events".toUri().buildUpon()
    .appendQueryParameter("id_$idType", id)
    .appendQueryParameter("cookies", "false")

// Network requests aren't allowed in main thread. Get adequate scope from context.
// See https://kotlinlang.org/docs/coroutines-guide.html for more info.
coroutineScope.launch(Dispatchers.IO) {
    val conn = (URL(trackUri.toString()).openConnection() as HttpsURLConnection).apply {
        requestMethod = "POST"
        setRequestProperty("User-Agent", userAgent)
        setRequestProperty("Content-Type", "application/json")
        doOutput = true
    }

    conn.outputStream.use { os ->
        os.write(event.toByteArray(Charsets.UTF_8))
    }

    try {
        // Trigger the request
        conn.responseCode
    } finally {
        conn.disconnect()
    }
}

For more information check our list of supported events.

Last updated on