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 registering them in your AppDelegate, 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.

github "BatchLabs/Batch-iOS-firebase-dispatcher"

Don't forget to register the dispatcher:

@import BatchFirebaseDispatcher

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        BatchEventDispatcher.add(BatchFirebaseDispatcher.instance())
        
        [...]

        BatchSDK.start(withAPIKey: "YOUR_API_KEY")
        return true
    }
}

Piano Analytics

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

github "BatchLabs/Batch-iOS-piano-dispatcher"

By default the dispatcher will handle UTM tracking and will send events only as Piano On-site Ads events.

Register the dispatcher and update the configuration as following:

@import BatchPianoDispatcher

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    let pianoDispatcher = BatchPianoDispatcher.instance
    
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        // PA Configuration
        pa.setConfiguration(ConfigurationBuilder()
            .withCollectDomain("logsx.xiti.com")
            .withSite(123456789)
            .build()
        )
        // Uncomment if you want to enable custom event sending (default: false)
        //pianoDispatcher.enableCustomEvents = true

        // Uncomment if you want to disable On-Site Ads event sending (default: true)
        //pianoDispatcher.enableOnSiteAdsEvents = false

        // Uncomment if you want to disable UTM tracking (default: true)
        //pianoDispatcher.enableUTMTracking = false
        
        BatchEventDispatcher.add(pianoDispatcher)
        
        [...]

        BatchSDK.start(withAPIKey: "YOUR_API_KEY")
        return true
    }
}

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

github "BatchLabs/Batch-iOS-atinternet-dispatcher"

Then, register the dispatcher:

import BatchATInternetDispatcher

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        BatchEventDispatcher.add(BatchATInternetDispatcher.instance())
        
        [...]

        BatchSDK.start(withAPIKey: "YOUR_API_KEY")
        return true
    }
}

≥ 1.1.0 Batch will automatically instantiate Tracker instances using the default AT Internet configuration, which comes in a plist.
If you're not using plist-based configuration and would like to manually configure your Tracker in code, you can tell Batch which tracker instance to use:

// Put this right after BatchEventDispatcher.add(BatchATInternetDispatcher.instance())
let tracker = <your ATInternet tracker initialization code>
BatchATInternetDispatcher.instance().trackerOverride = tracker

Mixpanel

The Mixpanel dispatcher automatically dispatches events to the Mixpanel SDK, using UTM tags when available.

Two flavors of the dispatcher are available, depending on which flavour of the Mixpanel SDK you're using:

• One for the Objective-C Mixpanel SDK
• One for the Swift Mixpanel SDK

github "BatchLabs/Batch-iOS-mixpanel-objc-dispatcher"

# or

github "BatchLabs/Batch-iOS-mixpanel-swift-dispatcher"

Don't forget to register the dispatcher:

import Batch
import BatchMixpanelSwiftDispatcher
// or import BatchMixpanelObjcDispatcher
import Mixpanel

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Find your mixpanel setup line, which looks like this:
        let mixpanel = Mixpanel.initialize(token: "MIXPANEL_TOKEN")
        // Objective-C Mixpanel SDK users: let mixpanel = Mixpanel.sharedInstance(withToken: "MIXPANEL_TOKEN")

        let mixpanelDispatcher = BatchMixpanelSwiftDispatcher.instance
        // If you're using BatchMixpanelObjcDispatcher, comment the previous lines and uncomment the next one
        // let mixpanelDispatcher = BatchMixpanelObjcDispatcher.instance()
         
        // Tell Batch about your Mixpanel instance to enable tracking
        mixpanelDispatcher.mixpanelInstance = mixpanel
        BatchEventDispatcher.add(mixpanelDispatcher)

        [...]

        BatchSDK.start(withAPIKey: "YOUR_API_KEY")
        return true
    }
}

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

[Batch] EventDispatcher - Adding event dispatcher: BatchFirebaseDispatcher

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.

Create a custom dispatcher

If for some reason, you need to implement your own dispatcher, you must create a BatchEventDispatcherDelegate and register it to the SDK using [BatchEventDispatcher addDispatcher].

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.

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate, BatchEventDispatcherDelegate {
    
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        BatchSDK.start(withAPIKey: "YOUR_API_KEY")
        
        [...]

        BatchEventDispatcher.add(self)
        return true
    }
    
    func dispatchEvent(with type: BatchEventDispatcherType,
                         payload: BatchEventDispatcherPayload) {
        NSLog("Dispatcher: I'm dispatching an event");
    }
}

Note: If the Batch SDK happens to be opt-out from, 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 or landing message 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 event comes a BatchEventDispatcherPayload 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.

func dispatchEvent(with type: BatchEventDispatcherType,
                     payload: BatchEventDispatcherPayload) {
    NSLog("Dispatcher: I'm dispatching an event with ID: %@", payload.trackingId);
}