Android SDK

The Velocidi Android SDK is open-source and can be found at github.com/velocidi/velocidi-android-sdk.

Installation#

Velocidi SDK is published to Maven central as a single module. Please reference the badge above or go to the release page to check our latest version.

To install the SDK in your application you just need to add the following dependency to the app/build.gradle file.

dependencies {
    implementation 'com.velocidi:velocidi-android-sdk:0.5.0'
}

You also need to add the following permissions to ensure the good functioning of the SDK.

In your application AndroidManifest.xml:

<!-- Required for internet. -->
<uses-permission android:name="android.permission.INTERNET"/>

Usage#

Initialize the SDK#

We highly recommend initializing the SDK on the onCreate method in your Application subclass. If you don't already have an Application subclass, you can also instantiate it in your MainActivity although it is not recommended.

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        val config = Config(URL("https://cdp.test.com"))

        Velocidi.init(config, this)
    }
}

Track#

The track method allows you to collect user activity performed in your application. This method is expecting a tracking event, in the format of a JSON string or a org.json.JSONObject with the event details. For more information check our documentation

// Using a JSON String
val eventJsonString =
    """
    {
      "clientId": "velocidi",
      "siteId": "velocidi.com",
      "type": "appView",
      "title": "Welcome Screen"
    }
    """

Velocidi.getInstance().track(UserId("<Advertising ID>", "gaid"), eventJsonString)

// Using a JSONObject
val eventJsonObj = mapOf(
    "clientId" to "velocidi",
    "siteId" to "velocidi.com",
    "type" to "appView",
    "title" to "Welcome Screen"
)

Velocidi.getInstance().track(UserId("<Advertising ID>", "gaid"), JSONObject(eventJsonObj))

Match#

The match method allows you to identify a user across multiple channels (Browser, Mobile App, CRM, ...). By performing a match between multiple ids you are telling Velocidi CDP that these are the same user and all the information retrieved with either one of these IDs belongs to the same user. A typical use case for this is, during the login action, to associate the user's email with Google's Advertising ID.

Please note that Velocidi SDK is not responsible for managing opt-in/opt-out status or ensuring the Google's privacy policy are respected. That should be your app's responsibility.

// Match the device Advertising Id with the user's email hash

Velocidi.match("someProvider", listOf(UserId("<Advertising ID>", "gaid"), UserId("<User Email Hash>", "email_sha256")))

For more information about Cross-Channel Matches go to https://docs.velocidi.com/collect/matches/ .

Collecting IDs#

Velocidi's SDK does not collect any user ID by default. These IDs have to be explicitly provided when executing the requests. 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 with com.velocidi.UserId. If you would like to use an ID not present in our list of supported IDs, please contact our support so that we can add it.

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 Android's Adversiting ID 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 we have the GAID, it can be used like any other ID.

val userId = UserId(gaid, "gaid")