Available in Batch 1.15.0 and higher

In this article, we'll go through the process of improving your external analytics by either installing a premade event dispatcher or making your own one.

What is an event dispatcher?

Batch can trigger with a number of analytics-oriented events that might be of interest in external analytic tools. An event dispatcher is the code that listens to those events, and dispatches them to the solution of your choice.

Add a "ready-to-go" dispatcher

Batch provide you with premade dispatchers for specific use cases (aka ready-to-go dispatcher). They are enabled by simply adding them in your dependency, and will automatically track events into your analytics solution with a predetermined structure

Firebase

The Firebase dispatcher automatically dispatches events to the Firebase SDK, including UTM tags when they are available.

To install simply add in your app's build.gradle:

implementation 'com.batch.android:firebase-dispatcher:3.0.1'

Piano Analytics

The Piano Analytics dispatcher automatically dispatches events to the Piano SDK, including AT tags when they are available.

To install simply add in your app's build.gradle:

implementation 'io.piano.android:analytics:3.3.5'
implementation 'com.batch.android:piano-dispatcher:2.0.0'

By default the dispatcher will handle UTM tracking and will send events only as Piano On-site Ads events. You can update this configuration from your Android's manifest as following:

<application>
    ...
    <!-- Enable custom event sending -->
    <meta-data android:name="com.batch.android.dispatcher.piano.enable_custom_events" 
               android:value="true"/>

    <!-- Disable On-Site Ads event sending -->
    <meta-data android:name="com.batch.android.dispatcher.piano.enable_onsite_ad_events"
               android:value="false"/>
    
     <!-- Disable UTM tracking -->
    <meta-data android:name="com.batch.android.dispatcher.piano.enable_utm_tracking" 
               android:value="false"/>
</application>

If you enable custom events, you also need to define them in your Piano Data Model. If so, please refer to the custom event/property list.

AT Internet

The AT Internet dispatcher automatically dispatches events to the AT Internet SDK, including the XTOR tag when it's available.

Note: This dispatcher should not be used in new integrations in favor of Piano Analytics

To install simply add in your app's build.gradle:

implementation 'com.batch.android:atinternet-dispatcher:3.0.1'

Once your dispatcher is installed, restart your app and you should see something like this in your logcat:

D/Batch: Batch.EventDispatcher: Adding event dispatcher: com.batch.android.dispatcher.firebase.FirebaseDispatcher

If you can't find the line in your log, it may be due to missing dependencies, be sure to add the AT Internet and/or Firebase Analytics SDKs to your project.

≥ 1.1.0 Batch will automatically instantiate Tracker instances using the default AT Internet configuration, automatically added in the aar you get from AT Internet.
If you're not using their AAR but another distribution of the AT Internet (for example, a maven one) and would like to manually configure your Tracker in code, you can tell Batch which instance to use:

// Put this in your Application's onCreate()
AtInternetRegistrar().getDispatcher(this).setTrackerOverride()

Mixpanel

The Mixpanel dispatcher automatically dispatches events to the Mixpanel SDK, including UTM tags when they are available.

To install simply add in your app's build.gradle:

implementation 'com.batch.android:mixpanel-dispatcher:2.0.0'

And don't forget to initialize the dispatcher using your tracking ID:

class MyKotlinApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        Batch.start("MY_API_KEY")
        registerActivityLifecycleCallbacks(BatchActivityLifecycleHelper())

        [...]

        // Here is your Mixpanel instance
        val mixpanel = MixpanelAPI.getInstance(this, MIXPANEL_TOKEN)
        // Register it to the dispatcher
        MixpanelDispatcher.setMixpanelInstance(this, mixpanel)
    }
}

Create a custom dispatcher

If for some reason, you need to implement your own dispatcher, you must create a BatchEventDispatcher and register it to the SDK using Batch.EventDispatcher.addDispatcher(BatchEventDispatcher).

Note: You don't need to add a dispatcher if you're using one of the previous "ready-to-go" library ! It will be automatically registered.

class MyKotlinApplication : Application(), BatchEventDispatcher {

    override fun onCreate() {
        super.onCreate()

        Batch.start("MY_API_KEY")
        registerActivityLifecycleCallbacks(BatchActivityLifecycleHelper())

        [...]

        Batch.EventDispatcher.addDispatcher(this)
    }

    override fun dispatchEvent(type: Batch.EventDispatcher.Type,
                               payload: Batch.EventDispatcher.Payload) {
        Log.d("Dispatcher", "I'm dispatching : " + type.name)
    }
}

Note: If the Batch SDK happens to be opt-out (from the user or because the SDK is opt-out by default), dispatchers won't receive any events.

Access data from the event

The Batch SDK will inform you when one of the following event happen:

• Push notification displayed : Triggered when a push notification is displayed (only available on Android).
• Push notification clicked : Triggered when a push notification is clicked.
• Push notification dismissed : Triggered when a push notification is dismissed (only available on Android).
• Message showed : Triggered when an in-app or landing message appear on the screen.
• Message closed : Triggered when an in-app or landing message is explicitly closed by the user (using the close button or a dismiss CTA/Global tap).
• Message auto-closed : Triggered when an in-app message or landing is closed by the auto-close timer.
• Message clicked : Triggered when an in-app or landing Click-To-Action is clicked or when the in-app/landing is global tapped (except if the CTA/Global Tap is a dismiss, then a closed event is triggered).

With every events come a Payload object, allowing you to access data associated with the event, such as a push notification custom payload value, or the tracking ID of an in-app or landing campaign.

override fun dispatchEvent(type: Batch.EventDispatcher.Type,
                           payload: Batch.EventDispatcher.Payload) {
    Log.d("Dispatcher", "I'm dispatching : " + type.name + ", " + payload.trackingId)
}