Event dispatchers

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.

Google Analytics

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

  • Cocoapods
  • Carthage
pod 'BatchGoogleAnalyticsDispatcher'

Note: Google is sunsetting its Google Analytics SDK on October 31, 2019 (except if you're a Google Analytics 360 customer). If you're using the free plan of Google Analytics, please migrate to Firebase immediately.

Firebase

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

  • Cocoapods
  • Carthage
pod 'BatchFirebaseDispatcher'

AT Internet

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

  • Cocoapods
  • Carthage
pod 'BatchATInternetDispatcher'

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

[Batch-Internal] EventDispatcher - Adding event dispatcher: BatchFirebaseDispatcher

If you can't find the line in your log, it's may 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].

  • Objective-C
  • Swift
// MYAppDelegate.h

@interface MYAppDelegate : UIResponder <UIApplicationDelegate,
                                        BatchEventDispatcherDelegate>

[...]

@end

// MYAppDelegate.m

@implementation MYAppDelegate

- (BOOL)application:(UIApplication *)application 
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [Batch startWithAPIKey:@"MY_API_KEY"];
    
    [...]

    [BatchEventDispatcher addDispatcher:self];
    return YES;
}

- (void)dispatchEventWithType:(BatchEventDispatcherType)type 
                   andPayload:(nonnull id<BatchEventDispatcherPayload>)payload { 
    NSLog(@"Dispatcher: I'm dispatching an event");
}

@end

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.

  • Objective-C
  • Swift
- (void)dispatchEventWithType:(BatchEventDispatcherType)type 
                   andPayload:(nonnull id<BatchEventDispatcherPayload>)payload {
    NSLog(@"Dispatcher: I'm dispatching an event with ID: %@", payload.trackingId);
}