Application Lifecycle Events Guide - iOS

Marketers seek to track data points to monitor the efficacy of their advertising strategy so they can adjust their efforts to improve their targeting. For example, in an e-commerce mobile app, marketers would like to track the products that are viewed more often than others or the journey that led end users in viewing a particular screen. In addition to this, an app developer might also want to track information about the performance of the app, such as crashes, application hangs and so on. Information from these types of events can be used to define or modify the product strategy.

While setting up your mobile app to collect the lifecycle events, you could set your collection on automatic or manual mode.

Note: The view controller and app life cycle events can be tracked with automatic or manual mode.

When configured properly, the Core module triggers some events automatically.

Toggling Automatic Events

Though you set up application tracking as defined in the previous section, automatic tracking of app life cycle events are disabled by default. You can enable automatic tracking by setting the corresponding config to "true" in the oracle.json file.

The oracle.json file with above configurations will be appear as follows.

{
"config_version": "1.0",
"ORACORE": {
"ora_dc_app_start_auto_enabled": "true",
"ora_dc_error_auto_enabled": "true",
"ora_dc_view_controller_auto_enabled": "true",
"ora_dc_push_auto_enabled": "true",
"ora_dc_foreground_auto_enabled": "true"
}
}

The above configuration(s) can also be set programmatically at run time with the help of ORACoreDataContainer API.

• Objective-C
• Swift

//To monitor app foreground and background events
ORACoreDataContainer *container = [[ORACoreDataContainer alloc]init];
ORAConfigForegroundAutoEnabled *setting = [[ORAConfigForegroundAutoEnabled alloc]init];
[container putValue:@"true" forKey:setting];					

//To monitor app foreground and background events
var container = ORACoreDataContainer()
var setting = ORAConfigForegroundAutoEnabled()
container.putValue("true", forKey: setting)				

Automatic Event Definitions

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 the Core module automatic events. In order for these events to be fired, your app must implement the associated method, even if the 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 would like to subclass or change the name of your AppDelegate class, you must set the ora_dc_app_delegate_class_name configuration setting with the name of your AppDelegate class. See the Core Configuration Guide for details.

Automatic Event Definitions

Application Lifecycle events

All application lifecycle events can be triggered automatically and/or manually.

Application Start

Fires an event on application launch.

Syntax

- (NSDictionary *)triggerEventForApplication:(NSString *)appName
                       startWithCustomParams:(NSDictionary *)customParams;

Example

// Send custom key/value pairs as arguments to event methods (optional)
    NSDictionary *customParams = @{@"custom_key": @"custom_value"};
    [[ORACoreDataCollector sharedCollector] triggerEventForApplication:@"Hello World Application" startWithCustomParams:customParams];

Parameters

Infinity Parameters

Additional parameters that are passed with every event are listed here.

Application Terminate

Fires an event on application termination. The event includes boilerplate information for an app termination, plus the name of the application.

Syntax

- (NSDictionary *)triggerEventForApplication:(NSString *)appName
                   terminateWithCustomParams:(NSDictionary *)customParams;

Example

// Send custom key/value pairs as arguments to event methods (optional)
  NSDictionary *customParams = @{@¿custom_key¿: @¿custom_value¿};
  [[ORACoreDataCollector sharedCollector] triggerEventForApplication:@¿Hello World Application¿ terminateWithCustomParams:customParams];

Parameters

Infinity parameter

Additional parameters that are passed with every event are listed here.

Note: This event must be generated under normal application termination. See Apple’s ApplicationWillTerminate page for details.

Application Entering Background

Description: Fires an event when the application enters the background.

Syntax

- (NSDictionary *)triggerEventForApplication:(NSString *)appName
          didEnterBackgroundWithCustomParams:(NSDictionary *)customParams;

Example

// Send custom key/value pairs as arguments to event methods (optional)
    NSDictionary *customParams = @{@"custom_key": @"custom_value"};
    [[ORACoreDataCollector sharedCollector] triggerEventForApplication:@"Hello World Application" didEnterBackgroundWithCustomParams:customParams];

Parameters

Infinity parameters

Additional parameters that are passed with every event are listed here.

Application Entering Foreground

Fires an event when the application enters the foreground.

Syntax

- (NSDictionary *)triggerEventForApplication:(NSString *)appName
         willEnterForegroundWithCustomParams:(NSDictionary *)customParams;

Example

// Send custom key/value pairs as arguments to event methods (optional)
    NSDictionary *customParams = @{@"custom_key": @"custom_value"};
    [[ORACoreDataCollector sharedCollector] triggerEventForApplication:@"Hello World Application" willEnterForegroundWithCustomParams:customParams];

Parameters

Infinity parameters

Additional parameters that are passed with every event are listed here.

Application Error

Fires an event when the application error occurs or the application receives a memory warning from the system.

Syntax

- (NSDictionary *)triggerEventForApplication:(NSString *)appName
                            withErrorMessage:(NSString *)errorMessage
                                customParams:(NSDictionary *)customParams;

Example

// Send custom key/value pairs as arguments to event methods (optional)
    NSDictionary *customParams = @{@"custom_key": @"custom_value"};
    [[ORACoreDataCollector sharedCollector] triggerEventForApplication:@"Hello World Application" withErrorMessage:@"Error message goes here" customParams:customParams];

Parameters

Infinity parameters

Additional parameters that are passed with every event are listed here.

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

Fires an event when any view controller appears.

Syntax

- (NSDictionary *)triggerEventForViewDidAppear:(NSString *)controllerTitle
                              withCustomParams:(NSDictionary *)customParams;

Example

// Send custom key/value pairs as arguments to event methods (optional)
    NSDictionary *customParams = @{@"custom_key": @"custom_value"};
    [[ORACoreDataCollector sharedCollector] triggerEventForViewDidAppear:@"View controller name" withCustomParams:customParams];

Parameters

Infinity parameters

Additional parameters that are passed with every event are listed here.

View Controller Disappearance

Fires an event when any view controller disappears.

Syntax

- (NSDictionary *)triggerEventForViewDidDisappear:(NSString *)controllerTitle
                                 withCustomParams:(NSDictionary *)customParams;

Example

// Send custom key/value pairs as arguments to event methods (optional)
    NSDictionary *customParams = @{@"custom_key": @"custom_value"};
    [[ORACoreDataCollector sharedCollector] triggerEventForViewDidDisappear:@"View controller name" withCustomParams:customParams];

Parameters

Infinity parameters

Additional parameters that are passed with every event are listed here.