Moments API Module

The Moments API module enables you to retrieve detailed information about visitor profiles from Tealium AudienceStream. This information can be used to enhance the customer experience in your app by accessing various attributes such as audiences, badges, strings, booleans, dates, and numbers.

Supported Platforms

The following platforms support the Moments API module:

• Android (Kotlin)

Install

Install the Moments API module using Maven.

Maven

To install the module using Maven:

1. In your project’s top-level build.gradle file, add the following Maven repository:

   maven {
       url "https://maven.tealiumiq.com/android/releases/"
   }
   

2. In your project module’s build.gradle file, add the Maven dependencies for the Tealium library and Moments API Module:

   dependencies {
       implementation 'com.tealium:kotlin-core:1.6.0'
       implementation 'com.tealium:kotlin-momentsapi:1.0.0'
   }
   

Usage

Initialize

Initialize the Tealium instance with the Moments API module included in the configuration, as follows:

val config = TealiumConfig(
    application,
    "tealiummobile",
    "demo",
    Environment.DEV,
    modules = mutableSetOf(
        Modules.Lifecycle,
        Modules.VisitorService,
        Modules.MomentsApi
    ),
    dispatchers = mutableSetOf(
        Dispatchers.Collect,
        Dispatchers.TagManagement,
        Dispatchers.RemoteCommands
    )
).apply {
    momentsApiRegion = MomentsApiRegion.UsEast // See possible region options below
    // momentsApiRegion = MomentsApiRegion.Custom("myRegion")
}

Tealium.create("your_instance_name", config)

Setting the region is mandatory. The Moments API module will not initialize if it’s missing.

Fetch Visitor Data

Use the fetchEngineResponse method to retrieve the visitor profile information. This method accepts an engine ID and a response listener to handle the API response.

fun fetchMoments(engineId: String, responseListener: ResponseListener<EngineResponse>) {
    val tealiumInstance = Tealium["your_instance_name"]
    tealiumInstance?.momentsApi?.fetchEngineResponse(engineId, responseListener)
}

Example: Fetch and Handle Moments API Data

fun fetchMoments(engineId: String) {
    val tealiumInstance = Tealium["your_instance_name"]
    tealiumInstance?.momentsApi?.fetchEngineResponse(engineId, object : ResponseListener<EngineResponse> {
        override fun success(data: EngineResponse) {
            Log.d("MomentsAPI", "String attributes: ${data.strings}")
            Log.d("MomentsAPI", "Boolean attributes: ${data.booleans}")
            Log.d("MomentsAPI", "Audiences: ${data.audiences}")
            Log.d("MomentsAPI", "Date attributes: ${data.dates}")
            Log.d("MomentsAPI", "Badges: ${data.badges}")
            Log.d("MomentsAPI", "Numbers: ${data.numbers}")
        }

        override fun failure(errorCode: ErrorCode, message: String) {
            Log.e("MomentsAPI", "Error fetching moments: $errorCode - $message")
        }
    })
}

Visitor Profile Data

The EngineResponse object contains various types of attributes returned by the Moments API. The following table shows the available properties and their data types:

Configuration Options

Region

Configure the Moments API region according to where your AudienceStream profile resides. If uncertain, consult your account manager.

config.momentsApiRegion = MomentsApiRegion.UsEast

The custom option allows for future expansion and should not be used unless directed.

config.momentsApiRegion = MomentsApiRegion.Custom("custom_region_placeholder")

Referrer

For added security, you can specify a referrer URL. This URL must match the “Domain Allow List” in the Tealium UI, or the Moments API will not return any data. The default referrer URL is:

https://tags.tiqcdn.com/utag/<account>/<profile>/<environment>/mobile.html

If the provided referrer is not in the allow list, Moments API will not return any data.

config.momentsApiReferrer = "https://yourcustomreferrer.com"

Troubleshooting

Common Errors

You may encounter errors when requesting data from the Moments API. The following table shows the errors that could occur: