Firebase dispatcher

The Firebase dispatcher is a Tealium Prism module that forwards events to the Firebase Analytics SDK on the device. You track an event once with Prism and the dispatcher calls the native Firebase API. You configure mappings from your data layer to Firebase events, parameters, user properties, and consent settings in your Tealium mobile profile.

Requirements

The Firebase dispatcher requires the following:

Install

pluginManagement {
    repositories {
        google()
        gradlePluginPortal()
        mavenCentral()
    }
}

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://maven.tealiumiq.com/android/releases/") }
    }
}

plugins {
    id("com.google.gms.google-services") version "4.4.2"
}

dependencies {
    implementation("com.tealium.prism:firebase:0.2.0")
    implementation(platform("com.google.firebase:firebase-bom:34.6.0"))
    implementation("com.google.firebase:firebase-analytics")
}

.package(url: "https://github.com/Tealium/tealium-prism-ios-firebase-dispatcher.git", from: "0.2.0")

pod 'TealiumPrismFirebase'

Initialize

No code is needed when your remote or local settings include the Firebase module. The dispatcher registers itself when the app starts and stays inactive until settings for it exist. For more information, see Remote and local settings.

The dispatcher initializes Firebase for you. On iOS, the dispatcher calls FirebaseApp.configure() on first use and skips it if your app already did. On Android, the firebase-analytics content provider initializes Firebase at startup.

When the device is offline, the Firebase SDK queues events and delivers them when connectivity is restored.

If your app configures modules in code, add the module to the modules list in TealiumConfig:

import com.tealium.prism.core.api.Tealium
import com.tealium.prism.core.api.TealiumConfig
import com.tealium.prism.core.api.Modules
import com.tealium.prism.core.api.misc.Environment
import com.tealium.prism.firebase.firebase

val config = TealiumConfig.Builder(
    application = this,
    accountName = "my_account",
    profileName = "my_profile",
    environment = Environment.PROD,
    modules = listOf(
        Modules.collect(),
        Modules.firebase()
    )
)
    .setSettingsUrl("https://tags.tiqcdn.com/dle/my_account/my_profile/mobile_settings_prod.json")
    .build()
val tealium = Tealium.create(config)

import TealiumPrismCore
import TealiumPrismFirebase

let config = TealiumConfig(account: "my_account",
                           profile: "my_profile",
                           environment: "prod",
                           modules: [
                            Modules.collect(),
                            Modules.firebaseDispatcher()
                           ],
                           settingsUrl: "https://tags.tiqcdn.com/dle/my_account/my_profile/mobile_settings_prod.json")
let tealium = Tealium.create(config: config)

To lock a setting so that remote changes cannot override it, pass a builder closure. For more information, see Advanced configuration.

Modules.firebase { builder ->
    builder.setAnalyticsEnabled(true)
}

Modules.firebaseDispatcher { builder in
    builder.setAnalyticsEnabled(true)
}

Configure the module

1. In your Tealium mobile profile, go to Modules, and add the Firebase module.
2. Set the module settings. Each is optional. If omitted, Firebase applies its own default.
3. Add mappings from your data layer variables to Firebase destinations. See Data mappings.
4. Optionally restrict the module with load rules. For more information, see Rules.
5. Save and publish the mobile settings. The SDK fetches the published file at startup and on each remote settings refresh. See publish mobile settings.

session_timeout_seconds and analytics_collection_enabled are also available as commands. Module settings apply when the module starts and again whenever the SDK fetches updated settings. The matching command applies at event time.

Data mappings

A mapping copies a data layer variable to a destination in the Firebase command payload. The following mapping runs logevent when tealium_event is purchase, uses the event name as the Firebase event name, and sends order_total as the Firebase value parameter:

The available mappings are:

Firebase Config

Standard

E-Commerce

Consent settings

Events

To trigger Firebase events, use data mappings in the Firebase module in your mobile profile to map the values of tealium_event to their matching Firebase event names. For example, in this mapping, when tealium_event="purchase" it triggers the Firebase events for purchase and logEvent:

initiateconversionmeasurement

logevent

resetdata

setanalyticscollectionenabled

setconsent

setdefaultparameters

setsessiontimeout

setuserid

setuserproperty

Verify

Enable Firebase debug mode on your test device, then track an event that maps to logevent. The event appears in DebugView within seconds with the mapped parameters.

• View events in Xcode debug console (iOS)
• View events in debug log (Android)

If the event does not appear, use Trace to confirm the event reached Prism with the expected data layer values.

Troubleshooting

Command errors

When a command fails, the dispatcher logs a warning, skips that command, and continues. Other commands you mapped on the same event still run, and the event still reaches your other dispatchers. Search the device log for Command '<name>' failed:. The message wording differs slightly between iOS and Android. The error types are the same on both.

The less common errors emptyParameter, emptyArray, and noValidParameters occur when a mapped value is empty or when no supported destination is mapped for the command.

Limitations

• initiateconversionmeasurement and log_level are iOS only.
• Only one Firebase dispatcher can be active in an app.

Reference

• Prism iOS Firebase API reference
• Prism Android Firebase API reference