Application Lifecycle Events Guide - Android
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.
In Android, the user interface of the mobile app, is generally created by using XML layouts and presented to the user with the help of either an activity or a fragment. So, life cycle events of activities and fragments are a representation of user journey. Hence, the easiest way to track user journey is by tracking the life cycle events of activities and fragments.
While setting up your mobile app to collect the lifecycle events, you could set your collection on automatic or manual mode.
Once you have configured the Core module as highlighted here you can now start tracking events from the mobile.
Initialize application tracking
This section guides you to enable tracking application launch(es) and exit(s) and uncaught exceptions. You can also track user session initiation and termination. You can initialize the app tracking feature to capture both online and offline events. You can do this by extending the ORABaseApplication class, if your mobile application is created by extending the Base Application class. This class has multiple methods that can be used to capture mobile application performance metrics.
public class HelloWorld extends ORABaseApplication {
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate();
...
}
...
}
Note: If you do not decide to initialize the mobile app for automatic tracking, then you must call the ORABaseDataCollector.setApplication() method to initialize the Core module before calling any of the event methods. Add a call to the setApplication method as the first line for the onCreate method.
public class HelloWorld extends Application {
@Override
public void onCreate(Bundle savedInstanceState) {
// programmatically configure the Library
ORABaseDataCollector.setApplication(this);
...
}
...
}
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.
| Configuration | Description | |
| 1 | ora_dc_app_start_auto_enabled | Track app start and terminate events |
| 2 | ora_dc_error_auto_enabled | Track application error/crash events |
| 3 | ora_dc_activity_auto_enabled | Track activity life cycle events |
| 4 | ora_dc_fragment_auto_enabled | Track fragment life cycle events |
| 5 | ora_dc_push_auto_enabled | Track push notification events |
| 6 | ora_dc_foreground_auto_enabled | Track app foreground and background events |
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_activity_auto_enabled": "true",
"ora_dc_fragment_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.
ORACoreDataContainer container = new ORACoreDataContainer(this);
//To monitor app start and terminate events
container.putValue(ORABaseConfigSettings.APP_START_AUTO_ENABLED, "true");
//To monitor application error/crash events
container.putValue(ORABaseConfigSettings.ERROR_AUTO_ENABLED, "true");
//To monitor activity life cycle events
container.putValue(ORABaseConfigSettings.ACTIVITY_AUTO_ENABLED, "true");
//To monitor fragment life cycle events
container.putValue(ORABaseConfigSettings.FRAGMENT_AUTO_ENABLED, "true");
//To monitor push notification events
container.putValue(ORABaseConfigSettings.PUSH_AUTO_ENABLED, "true");
//To monitor app foreground and background events
container.putValue(ORABaseConfigSettings.FOREGROUND_AUTO_ENABLED, "true");
Automatic Event Definitions
Application Lifecycle events
All application lifecycle events can be triggered automatically and/or manually.
Application Start
Collects data when Application.onCreate() method is executed.
Syntax
Map<String, String> triggerApplicationStartEvent(final String applicationName, final Map<String, String> customData);
Example
// Send custom key/value pairs as arguments to event methods (optional)
Map <String, String> customData = new HashMap<String, String>();
customData.put("custom_key", "custom_value");
ORABaseDataCollector.getInstance().triggerApplicationStartEvent("Hello World Application", customData);
Parameters
| Parameter | Mandatory/Optional | Description | |
| 1 | applicationName | Mandatory | Specifies an application name associated with application startup, application termination, application foreground, application background, or application error. |
| 2 | customData | Optional | Specifies a series of custom key-value parameters used to pass data that is not included in the method. |
Infinity Parameters
| Parameter | Value | Notes | |
| 1 | data.page-uri | /application/start | Mobile app specific parameter is dcsuri |
| 2 | wt.ti | applicationName | |
| 3 | wt.pi | applicationName | |
| 4 | wt.sys | startup | |
| 5 | wt.dl | 61 |
Additional parameters that are passed with every event are listed here.
Application Background State
This event collects data when the Application.onStopped() method is executed.
Syntax
Map<String, String> triggerApplicationEnterBackgroundEvent(final String applicationName, final Map<String, String> customData);
Example
// Send custom key/value pairs as arguments to event methods (optional)
Map <String, String> customData = new HashMap<String, String>();
customData.put("custom_key", "custom_value");
ORABaseDataCollector.getInstance().triggerApplicationEnterBackgroundEvent("Hello World Application", customData);
Parameters
| Configuration | Mandatory/Optional | Description | |
|---|---|---|---|
| 1 | applicationName | Mandatory | Specifies an application name associated with application startup, application termination, application foreground, application background, or application error. |
| 2 | CustomData | Optional | Specifies a series of custom key-value parameters used to pass data that is not included in the method. |
Infinity Parameters
| Parameter | Value | Notes | |
|---|---|---|---|
| 1 | data.page-uri | /application/start | Mobile app specific parameter is dcsuri |
| 2 | wt.ti | applicationName | |
| 3 | wt.pi | applicationName | |
| 4 | wt.sys | startup | |
| 5 | wt.dl | 61 |
Additional parameters that are passed with every event are listed here.
Application Foreground State
This event collects data when Application.onResume() method is executed.
Syntax
Map<String, String> triggerApplicationEnterForegroundEvent(final String applicationName, final Map<String, String> customData)
Example
// Send custom key/value pairs as arguments to event methods (optional)
Map <String, String> customData = new HashMap<String, String>();
customData.put("custom_key", "custom_value");
ORABaseDataCollector.getInstance().triggerApplicationEnterForegroundEvent("Hello World Application", customData);
Parameters
| Configuration | Mandatory/Optional | Description | |
|---|---|---|---|
| 1 | applicationName | Mandatory | Specifies an application name associated with application startup, application termination, application foreground, application background, or application error. |
| 2 | CustomData | Optional | Specifies a series of custom key-value parameters used to pass data that is not included in the method. |
Infinity Parameters
| Parameter | Value | Notes | |
|---|---|---|---|
| 1 | data.page-uri | /application/start | Mobile app specific parameter is dcsuri |
| 2 | wt.ti | applicationName | |
| 3 | wt.pi | applicationName | |
| 4 | wt.sys | startup | |
| 5 | wt.dl | 61 |
Additional parameters that are passed with every event are listed here.
Application Error
This event collects data when ORABaseApplication encounters an uncaught exception.
Syntax
Map<String, String> triggerApplicationErrorEvent(final String applicationName, final Map<String, String> customData);
Example
// Send custom key/value pairs as arguments to event methods (optional)
Map <String, String> customData = new HashMap<String, String>();
customData.put("custom_key", "custom_value");
ORABaseDataCollector.getInstance().triggerApplicationErrorEvent("Hello World Application", customData);
Parameters
| Configuration | Mandatory/Optional | Description | |
|---|---|---|---|
| 1 | applicationName | Mandatory | Specifies an application name associated with application startup, application termination, application foreground, application background, or application error. |
| 2 | CustomData | Optional | Specifies a series of custom key-value parameters used to pass data that is not included in the method. |
Infinity Parameters
| Parameter | Value | Notes | |
|---|---|---|---|
| 1 | data.page-uri | /application/start | Mobile app specific parameter is dcsuri |
| 2 | wt.ti | applicationName | |
| 3 | wt.pi | applicationName | |
| 4 | wt.sys | startup | |
| 5 | wt.dl | 61 |
Additional parameters that are passed with every event are listed here.
Application Terminate
This event collects data when Application.onTerminate() method is executed.
Note: This event can not be generated/tracked automatically. This limitation is due to the manner in which the Application.onTerminate() method is handled by Android. See here for details.
Syntax
Map<String, String> triggerApplicationTerminateEvent(final String applicationName, final Map<String, String> customData);
Example
// Send custom key/value pairs as arguments to event methods (optional)
Map <String, String> customData = new HashMap<String, String>();
customData.put("custom_key", "custom_value");
ORABaseDataCollector.getInstance().triggerApplicationTerminateEvent("Hello World Application", customData);
Parameters
| Configuration | Mandatory/Optional | Description | |
|---|---|---|---|
| 1 | applicationName | Mandatory | Specifies an application name associated with application startup, application termination, application foreground, application background, or application error. |
| 2 | CustomData | Optional | Specifies a series of custom key-value parameters used to pass data that is not included in the method. |
Infinity Parameters
| Parameter | Value | Notes | |
|---|---|---|---|
| 1 | data.page-uri | /application/start | Mobile app specific parameter is dcsuri |
| 2 | wt.ti | applicationName | |
| 3 | wt.pi | applicationName | |
| 4 | wt.sys | startup | |
| 5 | wt.dl | 61 |
Additional parameters that are passed with every event are listed here.
Activity Lifecycle Events
Activity Start
This event collects data when an activity starts in the mobile application. This is allowed when the mobile application is extended with “ORABaseApplication” and Activity.onCreate() or Activity.onStart() method is executed.
Syntax
Map<String, String> triggerActivityStartEvent(final String activityName, final Map<String, String> customData);
Example
// Send custom key/value pairs as arguments to event methods (optional)
Map <String, String> customData = new HashMap<String, String>();
customData.put("custom_key", "custom_value");
ORABaseDataCollector.getInstance().triggerActivityStartEvent("Home Screen", customData);
Parameters
| Configuration | Mandatory/Optional | Description | |
|---|---|---|---|
| 1 | applicationName | Mandatory | Specifies an activity name associated with the end of user activity. |
| 2 | CustomData | Optional | Specifies a series of custom name-value parameters used to pass data that is not included in the method. |
Infinity Parameters
| Parameter | Value | Notes | |
|---|---|---|---|
| 1 | data.page-uri | /application/start | Mobile app specific parameter is dcsuri |
| 2 | wt.ti | applicationName | |
| 3 | wt.pi | applicationName | |
| 4 | wt.sys | startup | |
| 5 | wt.dl | 61 |
Additional parameters that are passed with every event are listed here.
Activity Resume
This event collects data when an activity resumes in the mobile application. This is allowed when the mobile application is extended with “ORABaseApplication” and onActivityResumed() method is executed.
Syntax
Map<String, String> triggerActivityResumeEvent(final String activityName, final Map<String, String> customData);
Example
// Send custom key/value pairs as arguments to event methods (optional)
Map <String, String> customData = new HashMap<String, String>();
customData.put("custom_key", "custom_value");
ORABaseDataCollector.getInstance().triggerActivityResumeEvent("Login Screen", customData);
Parameters
| Configuration | Mandatory/Optional | Description | |
|---|---|---|---|
| 1 | applicationName | Mandatory | Specifies an activity name associated with the end of user activity. |
| 2 | CustomData | Optional | Specifies a series of custom name-value parameters used to pass data that is not included in the method. |
Mobile app specific parameters
| Parameter | Value | Notes | |
|---|---|---|---|
| 1 | data.page-uri | /application/start | Mobile app specific parameter is dcsuri |
| 2 | wt.ti | applicationName | |
| 3 | wt.pi | applicationName | |
| 4 | wt.sys | startup | |
| 5 | wt.dl | 61 |
Additional parameters that are passed with every event are listed here.
Activity Pause
This event collects data when an activity pauses in the mobile application. This is allowed when the mobile application is extended with “ORABaseApplication” and Activity.onPause() method is executed.
Syntax
Map<String, String> triggerActivityPauseEvent(final String activityName, final Map<String, String> customData);
Example
// Send custom key/value pairs as arguments to event methods (optional)
Map <String, String> customData = new HashMap<String, String>();
customData.put("custom_key", "custom_value");
ORABaseDataCollector.getInstance().triggerActivityPauseEvent("Login Screen", customData);
Parameters
| Configuration | Mandatory/Optional | Description | |
|---|---|---|---|
| 1 | applicationName | Mandatory | Specifies an activity name associated with the end of user activity. |
| 2 | CustomData | Optional | Specifies a series of custom name-value parameters used to pass data that is not included in the method. |
Infinity Parameters
| Parameter | Value | Notes | |
|---|---|---|---|
| 1 | data.page-uri | /application/start | Mobile app specific parameter is dcsuri |
| 2 | wt.ti | applicationName | |
| 3 | wt.pi | applicationName | |
| 4 | wt.sys | startup | |
| 5 | wt.dl | 61 |
Additional parameters that are passed with every event are listed here.
Activity Stop
This event collects data when an activity stops in the mobile application. This is allowed when the mobile application is extended with “ORABaseApplication” and Activity.onStop() method is executed.
Syntax
Map<String, String> triggerActivityStopEvent(final String activityName, final Map<String, String> customData);
Example
// Send custom key/value pairs as arguments to event methods (optional)
Map <String, String> customData = new HashMap<String, String>();
customData.put("custom_key", "custom_value");
ORABaseDataCollector.getInstance().triggerActivityStopEvent("Login Screen", customData);
Parameters
| Configuration | Mandatory/Optional | Description | |
|---|---|---|---|
| 1 | applicationName | Mandatory | Specifies an activity name associated with the end of user activity. |
| 2 | CustomData | Optional | Specifies a series of custom name-value parameters used to pass data that is not included in the method. |
Infinity Parameters
| Parameter | Value | Notes | |
|---|---|---|---|
| 1 | data.page-uri | /application/start | Mobile app specific parameter is dcsuri |
| 2 | wt.ti | applicationName | |
| 3 | wt.pi | applicationName | |
| 4 | wt.sys | startup | |
| 5 | wt.dl | 61 |
Additional parameters that are passed with every event are listed here.