Automatic Events Guide

Analytics - Automatic Events Guide Document

In its default configuration, the Webtrends SDK will fire some events automatically. Once the SDK has been added to your project and configured (see the Getting Started Guide for more information), the following events will begin automatically logging:

Toggling Automatic Events

Automatic (lifecycle) events are disabled by default. They may be enabled by setting the wt_dc_automatics_enabled to “true”. You can enable the collection of automatic events with the following line of code:

Swift

WTDataCollector.sharedCollector().setValue("true", forConfigKey:kWTConfigAutomaticsEnabled, persists: true)

Objective-C

[[WTDataCollector sharedCollector] setValue:@"true" forConfigKey:kWTConfigAutomaticsEnabled persists:YES];

Alternatively, you can enable automatic events from webtrends.plist. See Advanced Configuration Guide for instructions.

Once enabled, the following events will begin automatically logging:

• Application Start
• Application Terminate
• Application Entering Background
• Application Entering Foreground
• Notification Received
• View Controller Appearance
• View Controller Disappearance

Requirements for Automatic Events

Automatic events are attached to your existing App Delegate methods, if you have implemented them. The UIApplicationDelegate protocol has several optional methods that are associated with Webtrends automatic events. In order for these events to be fired, your app must implement the associated method, even if your implementation is empty. In these cases, you’ll find that associated method listed under “Required Protocol Method” in the next section.

In most cases, you’ll want these methods implemented (and in the default template for a new project, Xcode will have already placed most of this code for you) in your AppDelegate class. If you subclass or change the name of your AppDelegate class, you must set the wt_dc_app_delegate_class_name config setting with the name of your AppDelegate class. See the Advanced Configuration Guide for details.

Swift

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    //Your extra code here.    
    return true
}

func applicationDidEnterBackground(application: UIApplication) {
    //Your extra code here.
}

func applicationWillEnterForeground(application: UIApplication) {
    //Your extra code here.
}

func applicationWillTerminate(application: UIApplication) {
    //Your extra code here.
}

// These next three methods are only needed if your app receives notifications
func application(application: UIApplication, didReceiveLocalNotification notification: UILocalNotification) {
    //Your extra code here.
}

func application(application: UIApplication, didReceiveRemoteNotification userInfo: [NSObject : AnyObject]) {
    //Your extra code here.
}

func application(application: UIApplication, didReceiveRemoteNotification userInfo: [NSObject : AnyObject], fetchCompletionHandler completionHandler: (UIBackgroundFetchResult) -> Void) {
    //Your extra code here.
}

// This method is only required if your app is using WatchKit
func application(application: UIApplication, handleWatchKitExtensionRequest userInfo: [NSObject : AnyObject]?, reply: (([NSObject : AnyObject]!) -> Void)!) {
    //Your extra code here.
}

Objective-C

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    //Your extra code here.
    return YES;
}

- (void)applicationDidEnterBackground:(UIApplication *)application
{
    //Your extra code here.
}

- (void)applicationWillEnterForeground:(UIApplication *)application
{
    //Your extra code here.
}

- (void)applicationWillTerminate:(UIApplication *)application
{
    //Your extra code here.
}

// These next three methods are only needed if your app receives notifications
- (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification
{
    //Your extra code here.
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
{
    //Your extra code here.
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
{
    //Your extra code here.
}

// This method is only required if your app is using WatchKit
- (void)application:(UIApplication *)application handleWatchKitExtensionRequest:(NSDictionary *)userInfo reply:(void (^)(NSDictionary *))reply
{
    //Your extra code here.
}

Additionally, if you have a hybrid application, you’ll need the following method:

Swift

func application(application: UIApplication, openURL url: NSURL, sourceApplication: String?, annotation: AnyObject?) -> Bool {
    //Your extra code here.
    return true;
}

Your app can do whatever additional legwork it needs to do inside these methods; the SDK will attach itself and log events behind the scenes.

Objective-C

-(BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
{
    //Your extra code here.
    return YES;
}

For more information on hybrid apps, see the Hybrid Application Guide

Automatic Event Definitions

Application Lifecycle events

Application Start
Description: Fires an event on application launch. The event includes boilerplate information for an app launch, plus the name of the application.
Required Protocol Method: UIApplicationDelegate’s application:didFinishLaunchingWithOptions:
Manual Equivalent: [WTDataCollector triggerEventForApplication:startWithCustomParams:]

Application Terminate
Description: Fires an event on application termination (application:willTerminate: lifecycle callback method). The event includes boilerplate information for an app termination, plus the name of the application.
Required Protocol Method: UIApplicationDelegate’s applicationWillTerminate:
Manual Equivalent: [WTDataCollector triggerEventForApplication:terminateWithCustomParams:]

Application Entering Background
Description: Fires an event when the application enters the background. The event includes boilerplate information for an app entering the background, plus the name of the application.
Required Protocol Method: UIApplicationDelegate’s applicationDidEnterBackground:
Manual Equivalent: [WTDataCollector triggerEventForApplication:didEnterBackgroundWithCustomParams:]

Application Entering Foreground
Description: Fires an event when the application enters the foreground. The event includes boilerplate information for an app entering the foreground, plus the name of the application.
Required Protocol Method: UIApplicationDelegate’s applicationWillEnterForeground:
Manual Equivalent: [WTDataCollector triggerEventForApplication:willEnterForegroundWithCustomParams:]

Notification Received
Description: Fires an event when the application receives a notification (can include both local and remote notifications, depending on which of the required protocol methods are implemented). The event includes the notification’s payload, plus the name of the application.
Required Protocol Method: UIApplicationDelegate’s application:didReceiveLocalNotification: or application:didReceiveRemoteNotification: or application:didReceiveRemoteNotification:fetchCompletionHandler:
Manual Equivalent: [WTDataCollector triggerEventForNotification:withCustomParams:]

View Controller Lifecycle Events

View Controller Lifecycle events are handled automatically for all classes that inherit from UIViewController. There are a few exceptions to this rule. The following native iOS UIViewController subclasses will not trigger automatic events:

• UICompatibilityInputViewController
• UIInputWindowController
• UIAlertController
• UINavigationController
• UIPageViewController
• UITabBarController
• UISplitViewController
• UISearchContainerViewController

Any direct subclasses of these will trigger automatic events.

View Controller Appearance
Description: Fires an event when any view controller appears. The event includes boilerplate information for a view controller appearing, plus the title of the view controller.
Required Protocol Method: none
Manual Equivalent: [WTDataCollector triggerEventForViewDidAppear:withCustomParams:]

View Controller Disappearance
Description: Fires an event when any view controller disappears. The event includes boilerplate information for a view controller disappearing, plus the title of the view controller.
Required Protocol Method: none
Manual Equivalent: [WTDataCollector triggerEventForViewDidDisappear:withCustomParams:]