Application Life Cycle Events Guide Document

In the world of e-commerce, marketers often seek to report on the performance of their advertising tools such as websites or mobile apps so they can adjust their efforts to improve the results. To get an analysis of user behavior from your application, you may want to find out which views are more often viewed over others or how users ended up viewing a particular UI. In iOS, views, e.g., UI's are generally created by storyboard or xib layouts and are driven by either a UIView or a Controller. Therefore, we may say that view life cycle events are a direct representation of user navigation, which holds the key to building marketing strategy.

To track UI views on your iOS app, the easiest way would be simply following the app and view life cycle events. In order to get your data collector setup within any one of these life cycle events, you should set your collection mode on either automatic or manual. Note that app life cycle events can be tracked under either automatic or manual mode.

Once your application is published out to the iTunesConnect and finally downloaded by app users, it is critically important to find out how your application really behaves in their hands. Whether the app runs without crashing on their handset or how frequently your app is being viewed once it's been installed is vitally important information to be fed into the next development cycle of your application. To find out how your application get started, comes in and out of foreground, or get terminated on a device, there are number of methods available to monitor. These methods can be implemented either automatically or manually, depending upon the state of application you would like to monitor.

When configured properly, the Oracle CX Core SDK will fire some events automatically. Once the SDK has been added to your project and configured (see the Basic Installation Guide for more information), the following events will begin automatically logging. Please note, we need to set the respective config to true to track the events automatically.

Toggling Automatic Events

Automatic (lifecycle) events are disabled by default. You can enable certain events automatic tracking by setting the corresponding config to "true". See the configs list below:

  • ora_dc_app_start_auto_enabled
  • ora_dc_foreground_auto_enabled
  • ora_dc_push_auto_enabled
  • ora_dc_view_controller_auto_enabled
  • ora_dc_error_auto_enabled

Usage Example
You can enable the collection of application foreground/background automatic events with the following line of code:

ORACoreDataContainer *container = [[ORACoreDataContainer alloc]init]; ORAConfigForegroundAutoEnabled *setting = [[ORAConfigForegroundAutoEnabled alloc]init]; [container putValue:@"true" forKey:setting];

var container = ORACoreDataContainer() var setting = ORAConfigForegroundAutoEnabled() container.putValue("true", forKey: setting)

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 Oracle Infinity Core 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 ora_dc_app_delegate_class_name config setting with the name of your AppDelegate class. See the Core Configuration Guide for details.

- (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 methods are only needed if your app receives notifications
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
{
    //Your extra code here.
}

// <= iOS 9.x
- (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification
{
    //Your extra code here.
}

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

// >= iOS 10.x
- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void(^)())completionHandler {
    //Your extra code here.
}
						
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> 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 methods are only needed if your app receives notifications
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    //Your extra code here.
}

// <= iOS 9.x
func application(_ application: UIApplication, didReceive notification: UILocalNotification) {
    //Your extra code here.
}

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any]) {
    //Your extra code here.
}

// >= iOS 10.x
func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
    //Your extra code here.
}

Additionally, if you want to have a hybrid support for your application and want to open it in the device browser URL, which using Oracle Infinity JavaScript tag library for the transferring visitor's session information between native application and web page, you'll need the following method:

-(BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options { //Your custom code here return YES; }

func application(_ application: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
        // Your custom code here
        return true
}
Note: For iOS 8 OS version you'll need the following method:

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

func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
        // Your custom code here
        return true
}

Your app can do any additional legwork necessary inside these methods; the SDK will attach itself and log events behind the scenes.

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: [ORACoreDataCollector triggerEventForApplication:startWithCustomParams:]

Application Terminate

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

Required Protocol Method: UIApplicationDelegate's applicationWillTerminate:
Manual Equivalent: [ORACoreDataCollector triggerEventForApplication:terminateWithCustomParams:]

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. 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: [ORACoreDataCollector 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: [ORACoreDataCollector 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:didReceiveRemoteNotification:fetchCompletionHandler: or
iOS <= 9.x
application:didReceiveLocalNotification: or application:didReceiveRemoteNotification:
iOS >= 10.x
userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler:
Manual Equivalent: [ORACoreDataCollector triggerEventForNotification:withCustomParams:]
Discussion: This event is triggered from the application notification delegate methods. When Push Notifications are enabled in an application, the user will be asked if they would like to receive Push Notifications when the app is installed. At this point, Push Notifications are handled as follows:

  • User Accepts Push Notifications on App Install

When a user accepts Push Notifications, the SDK will trigger the event when the notification is received, regardless of whether the app is active or inactive.

  • User Declines Push Notifications on App Install

If push notifications are declined, this event may still be triggered when the application is open and active on the device. The user will not be alerted, but the method will be triggered when new data is received by the app. This behavior is by design and enables content to be received in the background by an app without alerting the user. To disable this behavior, the user could disable Background App Refresh in the Settings. When this is disabled, the Push Notification will not be received and the event will not be triggered.

Application Error

Description: Fires an event when the application error occurs or application receives a memory warning from the system.
Required Protocol Method: UIApplicationDelegate's applicationDidReceiveMemoryWarning:
Manual Equivalent: [ORACoreDataCollector triggerEventForApplication:withErrorMessage:customParams:]

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: [ORACoreDataCollector 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: [ORACoreDataCollector triggerEventForViewDidDisappear:withCustomParams:]