Analytics

17 Analytics

Oracle Mobile Cloud Service (MCS) provides an Analytics API to help you measure patterns in app performance and usage. As a business development manager or mobile program manager, you can use analytics to find out how to improve your apps.

Description of analytics_api_arch.png follows

Description of the illustration analytics_api_arch.png

What Can I Do With Analytics?

Use Analytics to gain insight into how (and how often) users use a mobile app at any given time. The analytics reports generated enable you to see an application's adoption rate, and find out which functions are used the most (or the least).

How Does MCS Create Analytics Reports?

MCS creates analytics reports from events, which describe how users interact with the mobile app.

A mobile app developer can track the mobile app’s entire usage by raising events in the mobile app code. For example, a mobile app for repair technicians might track events like Work Order Dispatched, Work Order Accepted, Work Order Resolved, and Work Order on Hold. To add further detail to an event, you can define properties that describe an event’s characteristics. For the Work Order on Hold event, for example, you might add properties for Customer Not Home or Parts on Order.

Tip:

Mobile program managers should decide which aspects of an app to track by events early in the app development process.

Mobile backends receive events from the REST calls made from mobile apps. A mobile app makes a single call, which includes a JSON payload that describes the events along with such contextual information like a user’s location, the start and end of a user session, and details about the user’s mobile device. You can craft the payload yourself if you use straight REST calls, or use the mobile client SDK to construct one for you. The SDK defines the user session and automatically applies the user and system context that allows MCS to generate reports that describe the number of users of the app, and how (and from where) they’re using it.

Description of analytics_overview.png follows

Description of the illustration analytics_overview.png

Note:

While the SDK enables Analytics to automatically generate reports that tell you how many users your app has, or how much time they’re spending on it, you must define events in the mobile app’s code if you want to see these reports.

Enabling Your Mobile Apps to Report Event Data

MCS creates analytics reports from information conveyed in JSON payloads. The calls that deliver the JSON payload to the Analytics API, which records event data, can be either straight REST calls or REST calls made through the mobile client SDK. In either case, MCS uploads and stores the JSON payload and then graphs it in a report.

Describing Analytics Events in JSON

The JSON payload describes the context for mobile app users in terms of both their mobile devices and the events that track user interactions. These types of events are known as custom events. A JSON payload has one or more of these custom events, and is also constructed from a context event that provides user and system details, a start session event, and end session event. The custom events are grouped within the session events to describe an analytic session.

Within the mobile app code, developers can determine the point at which the app flushes the custom events that have accumulated on the mobile device to the MCS server. This content is considered to be a session that can be logged. Theoretically, an analytic session can remain open for longer than a single batch update to the MCS server. In other words, sessions can vary in length according to your event logging use case: a session might be created to track event data for a single action or a set of actions that comprise a task. You can also use a session to log the entire span of user interactions within a user session. That said, the length of an analytic session generally does not, and should not, equal that of a user session. Instead, create analytic sessions that are short and concise. By keeping these sessions crisp, you’ll maintain system performance and accurate event reporting.

Note:

The mobile client SDK tracks analytic sessions on a file system, which means that a file grows as you add more events to a session. The MAFMCS Utility, which allows mobile apps built using Oracle Mobile Application Framework (MAF) to access MCS , enables sessions to be saved in memory. However, saving sessions in memory might degrade memory consumption when there are a large number of custom events (say, more than 1000). Consequently, you might lose some event logging, because the mobile app may crash before it can post events to MCS . See MAF Utility Developer Guide.

Taking a Look at the JSON Payload

Within a JSON payload, events have the following properties:

A name of fewer than 100 characters.
A unique string defined for the sessionID property, which associates an event with a particular session. If you create your own JSON, you must assign a unique string to this property. The mobile client SDK ensures uniqueness by adding a text string punctuated by hyphens known as a Universally Unique Identifier (UUID).
A time stamp: Events are ordered by time stamp (though not strictly, because events can share the same time stamp). The mobile client SDK generates the time stamp automatically.

A JSON payload posted toMCS may look something like this:

[
    {
        "name":"context",
        "type":"system",
        "timestamp":"2013-04-12T23:20:54.345Z",
        "properties":{
            "userName":"jimSmith",
            "model":"iPhone5,1",
            "longitude":"-122.11663", 
            "latitude":"37.35687",
            "timezone":"-14400",
            "manufacturer":"Apple",
            "osName":"iPhone OS",
            "osVersion":"7.1",
            "osBuild":"13E28",
            "carrier":"AT&T"
                      }
    },
    {
        "name":"sessionStart",
        "type":"system",
        "timestamp":"2013-04-12T23:20:55.052Z",
        "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce"
    },
    {
        "name":"PurchaseFailed",
        "type":"custom",
        "timestamp":"2013-04-12T23:20:56.523Z",
        "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
        "properties":{
            "cartContent":"WIDGET",
            "cartPrice":"$50,000"
     }

     {
        "name":"sessionEnd",
        "type":"system",
        "timestamp":"2013-04-12T23:25:55.052Z",
        "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce"
     }    

]

Every JSON payload must begin with a context event. In the preceding example, this event is indicated by "name":"context" and includes properties that describe the current context of the mobile app, such as user name and the longitude and latitude. The context event is associated with each event that follows it, such as the session start and end events that demarcate a session. It is also associated with events raised in the mobile app code, such as PurchaseFailed in the preceding example.

Note:

Although you can add this context to events using straight REST calls, the mobile client SDK adds both session and device context information to the payload automatically.

Creating Your Own JSON Payload

If you don’t use the mobile client SDK, keep these tips in mind when composing the JSON payload:

Start each payload with a context event (indicated by "name":"context").
Add a context event whenever the device's context changes — typically when the longitude, latitude, or username properties need to change.
You can randomly add the events within the payloads, but you must associate every event raised in the mobile app code with sessionStart and sessionEnd events just like PurchaseFailed in the preceding example, as noted by “type”:”custom”.

Note:
Ensure that these events share the same sessionID value. When events have the same sessionID value, theMCS server can approximate the session even if part of the payload (like the endSession definition) isn’t recorded by the database.

MCS responds with a 202 status code (Accepted) when it receives a complete and syntactically correct REST call. Otherwise, it returns 400 (Bad Request) or 405 (Method not Allowed) responses.

Why Should I Use the Mobile Client SDK?

The mobile client SDK:

Automatically defines the start and end of sessions and manages them using the UUIDs that it assigns to the sessionID property.
Adds the context event at the beginning of each payload.
Adds such device properties as the username, latitude, and longitude for context events.

Note:
On the server, the longitude and latitude values are translated into city, country, postal code, and street. See Integrating Analytics into a Mobile App Using the Mobile Client SDK.
Marks events raised in mobile app code as custom (which is described in Tracking Sessions and Logging Events for Mobile Apps) or system for session or context events. The SDK also adds a timeStamp to each event.

Adding Location Properties to the `context` Event

The Oracle eLocation Service (maps.oracle.com) derives location from the longitude and latitude properties in the JSON request body. These properties only work if your mobile apps are used in countries where Oracle eLocation Service is available. For countries where Oracle eLocation Services is unavailable, you can still enable MCS to record the location data that allows countries to display in the Dashboard map by adding location-related properties to the context event.

To enable requests to support country data, add any combination for the following properties to the context event:

locality — The mobile device's locality, such as city, township, or village.
region — The mobile device's region, such as state, canton, or province.
postalCode — The mobile device’s postal code.
country — The mobile device’s GPS country. For some countries in the Asia-Pacific region, you can use a two-letter identifier, such as JP (Japan), CN (China), or KR (South Korea).

Note:

Do not include longitude and latitude in the context event if you define any of these properties.

For example:

{         
     "name":"context",
         "type":"system",
         "timestamp":"2013-04-12T23:23:34.345Z",
         "properties":{
         "userName":"GDoe321",
         "locality":"Aomi",
         "region":"Kanto",
         "postalCode":"135-0064",
         "country":"JP", 
         "timezone":"-14400",
         "carrier":"AT&T",
         "model":"iPhone5,1",
         "manufacturer":"Apple",
         "osName":"iPhone OS",
         "osVersion":"7.1",
         "osBuild":"13E28"
         }

Integrating Analytics into a Mobile App Using the Mobile Client SDK

The oracle-cloud-mobile-analytics.jar and the libOMCAnalytics.a libraries included in the mobile client SDK enable mobile apps deployed on Android and iOS devices to post events to the Analytics API. These libraries become available to your mobile app when you download the mobile client SDK and integrate it into the mobile app. See Connecting Your Application to a Mobile Backend.

Understanding Different Types of Analytics Reports

The Analytics reports plot the frequency of incoming events against specified time periods. These reports enable you to spot patterns in mobile app usage and performance.

Reports	Uses
Events	Find out how users use your app. You select which events you want to track in the mobile app code. You can add additional events by calling the Analytics API from custom code. See Tracking Sessions and Logging Events for Mobile Apps. You can build conversion funnels that let you trace user participation through a workflow path. See Improving User Retention with Funnel Analysis.
API Calls Count API Calls Response Time	Track app usage and performance, as well as how apps use MCS .
New Users Active Users Session Count Session Duration	Enables you to answer such questions about engagement as: Is the app gaining or losing users? How often do users use the app and how long are the user sessions?
My Reports	Stores your saved report definitions.

Accessing the Analytics Reports

Click to open the side menu and then to open the dashboard. From here, you can quickly explore the following:

API Calls: See the number of calls to your app and the response times over various time periods.
Events: Track customer events, like putting an item into a cart and checking out.
Funnels: Discover what events customers complete on their way to a goal, like making a purchase or signing up for promos.
Users: Find out who your new and active users are, and group them by properties such as their zip code or country.
Sessions: Learn how often and how long users are in your app.
My Reports: Save analytics data insights as a report so you can return to it later.

While MCS displays data gathered from all of the mobile backends by default, you can use the menus to isolate the activity for all versions of a selected mobile backend or API.

Note:

Unless you have mobile cloud administrator privileges, you can see only the analytics reports generated in environments to which you have been granted access. For example, if you have access to only the Development environment, then you can't see the usage and traffic data for mobile backends in the Production environment.

Description of home_analyics.png follows

Description of the illustration home_analyics.png

The dashboard summarizes the user base and activity on a per-day basis. Click the bar charts to access more detailed reports that help you draw conclusions about the API traffic or app adoption rate. Accessing these reports from the menu lets you also view detailed data on app use.

Description of the illustration reports_menu.png

Tip:

For each report type (except funnels), you can view data plotted as a line graph or as a grouped bar chart by toggling the display options at the bottom of the page.

API Calls Reports

Click the API Calls menu to access the API endpoint reports. The API endpoint reports track all of the APIs, or a particular API, over a specified period of time. The volume of received calls indicates how much an app utilizes the MCS platform (and consequently, how widely used the app may be). Selecting a time frame allows you to see when traffic picks up or drops off. You can also drill down to specific endpoints to see how frequently they have been called and the corresponding response times.

Note:

MCS automatically generates analytics data whenever an API is called. This data accumulates over time and can use up all the available database space, which can severely affect service. To mitigate the issue, have your mobile cloud administrator modify the Analytics_ApiCallEventCollectionEnabled policy in the policies.properties in your environment. Setting this policy to false turns off automatic event generation. To avoid losing service, set this policy to false before your storage capacity reaches full.

API Calls Count

The reports for API Calls Count let you view the traffic for one, or many, APIs for a selected period of time. The report includes both successful and failed calls.

Description of the illustration api_calls.png

API Calls Response Time

MCS measures the response time (in milliseconds) for an API call as starting when the server receives the request and ending when the call returns the data to the mobile app. The response time includes the time dispatching the call. You can compare the response time for one (or all), APIs for a selected period of time. The bar graph compares the response time against the number of calls.

Description of repsonse_analytics.png follows

Description of the illustration repsonse_analytics.png

Events Report

The Events report lets you focus on how to improve the mobile app user experience and how to explore business opportunities. For example, the Events report can show you not only how frequently users use an app's search function, but how frequently users perform searches on specific devices and operating systems. By filtering an event with the device and operating system properties, you can see when usage of the app on a specific platform or device has outpaced usage on another. Declining usage across an entire platform may indicate that the application requires optimization for that platform.

Events reports aren’t limited to assessments of how a mobile app performs. You can also use them to spot inefficiencies in your company’s processes, such as its supply chain orchestration. To get an idea, say you are part of a mobile project team for an appliance repair company. Its repair technicians use mobile apps to accept or reject the work orders dispatched to them. They can also update the status of the work order from open to closed, or from open to on hold. You need to investigate why orders are left pending, or closed by frustrated customers. To do this, you can draw some conclusions by viewing an event and filtering it by its properties. Because your mobile app developer raised events in the app’s code to reflect the workflow outlined by your work order processing use case, MCS can graph the occurrence of work orders on hold. From this report, you can also see the reasons that prevent the fulfillment of an order from the properties defined for this event, such as Parts Ordered.

Description of events_report.png follows

Description of the illustration events_report.png

To gain business intelligence, you can filter a report using the properties specific to an event to discover user behavior and trends. For example, filters let you find out which products customers search for most often. By cross-referencing this against the location-specific reports for a mobile app, you can target your workforce, training, or marketing efforts accordingly.

Events

MCS plots the events against time. You can select from among events and then segment your search reports by creating filters. After you create a filter, click Done.

MCS applies the event name and the time-stamp properties as the default properties for the Events report. You can filter events by the following properties, which MCS applies automatically to events that are raised in the mobile app code:

Device-related properties
- Operating system
- Operating system name
- Operating system version
- Operating system build
- Device model
- Device manufacturer
- Carrier
Location Properties:
- Country
- State
- City
- Postal code

Description of custom_filter.png follows

Description of the illustration custom_filter.png

User and Session Reports

The user and session reports not only show you how many customers use a mobile app, but also how long they use it. Are applications gaining users? Does the time users spend using the app reflect its purpose?

When users authenticate, MCS gathers the events and plots the data points for these reports that you use to spot trends both over time and by location. You can group the data in these reports using the following properties:

Client application
Country
State
City
Postal code

Note:

Analytics creates reports for users only when sessions are used in the mobile app code.

User Reports

If you have a number of mobile apps deployed in the field, you can use the New User and Active User reports to find out which ones are gaining traction with new users, which are sustaining their user base, and which are losing users.

Why User Counts Can Vary

MCS approximates user counts through user IDs and device IDs.

For the events sent from mobile apps, MCS identifies a user through a user ID (a property provided by the OAuth token) or the mobile client SDK's Device ID header (Oracle-Mobile-DEVICE-ID) when the user ID is not known (for example, for mobile apps that do not require authentication). Although the Device ID reflects a user (not the device manufacturer) it isn’t always interchangeable with the user ID: a single user might access the same app using different devices (that is, a single user logging in from two devices will be counted as two users). Because MCS uses the Device ID in the absence of a user ID, the user counts are an approximation for mobile apps that allow both authenticated and unauthenticated (that is, anonymous) users.

User Session Reports

The Session Count and Session Duration reports describe user engagement.

These reports reveal the time users spend on a mobile app, not only in terms of the number of sessions, but also how much time users spend on the app. Although a session may be seen as starting when a user brings an app to the front on the device's springboard and ending when it's sent to the back, the concept of session may differ in terms of platform and implementation, as described in Defining Sessions.

The user session reports let you assess if the app elicits the appropriate level of user interaction. In other words, are user sessions intended to be short, as they are for apps giving time and weather updates, or long, as they would be for shopping apps?

New Users

The New Users report lets you see the number of users (authenticated or anonymous) for any (or all) mobile apps over a selected period of time.

When MCS receives an event from a previously unknown user (or from a device if the user is anonymous), it notes the existence of a new user. Keep in mind that the New Users report may not reflect the exact number of users if it includes both mobile apps that require user authentication along with ones that allow users to access services anonymously. See Why User Counts Can Vary.

Description of the illustration new_users.png

Active Users

MCS considers a user as active if it has previously received event data from the user or the device.

The Active Users report lets you see the number of active users for any (or all) mobile apps over a selected period of time. To find out the usage rate for a mobile app, you first select it from the dropdown list and then select the Mobile Application property. This property lets you compare the usage of two or more mobile apps. For reports that include mobile apps which require authentication along with those that don't, the number of actual users may not be accurate. See Why User Counts Can Vary.

Tip:

You can use the Mobile Application property to compare the adoption rate for different versions of a mobile app.

Description of the illustration active_users.png

Session Count

The Session Count report lets you see how many times a mobile app has been used over a selected period of time and location.

Description of the illustration session_count.png

Session Duration

The Session Duration report lets you see the minimum, maximum, and average session times for one, or all, mobile apps over a selected period of time and location.

Description of the illustration session_duration.png

Improving User Retention with Funnel Analysis

Conversion funnels let you compare how many users start a workflow (say, a checkout process, a user registration process, or a lead generation) against how many actually complete it. A funnel segments a workflow into a sequence of steps designed to guide users to some goal (or conversion). Typically, users drop off at each step of a workflow; many may begin a checkout process, for example, but comparatively few complete it. Funnel analytics show you the conversion rate for a workflow by showing the number of users who drop off at various points.

Note:

For funnel analysis to be meaningful, you need to think about how events can be assembled into work flows early in the development process. Defining the appropriate events allows the right data to be collected.

Description of the illustration funnels.png

Because funnels show you where users lose interest, you can use them to improve a process or identify bugs in a workflow. Further, because you construct funnels from the events raised for a mobile app, you can see where and why users are dropping off by analyzing the event properties.

Description of the illustration funnel_props.png

Creating a Funnel

To create a funnel, you first select a mobile app that has been released long enough so that a meaningful amount of event data can be collected. After you select the app, the events defined for it become available so that you can build a funnel from them.

Description of funnel_events.png follows

Description of the illustration funnel_events.png

Select a date range.
Add the events in sequential order to form the funnel steps.

Note:
MCS automatically displays the conversion rate for each event that you select. By selecting these events, you can view their properties. Use the filter and group by functions to analyze these properties.

Analyzing Funnels

After you've selected all of events for the process, take a look at the conversion rate. You can select an event and then drill down on the property.

Description of funnel_prop_grp.png follows

Description of the illustration funnel_prop_grp.png

Tip:

If the conversion rates indicate a large decrease, select more events to find out why.

For example, for a user registration workflow, select a signup failed event and then select the detail view for the event. Use the filter and group by options in the detailed report. You can group by system and custom properties. For example, grouping the data by the property, reason, lets you to see event data sorted by the attributes defined for this property, Duplicate User ID and Incomplete Data.

You can take an iterative approach to refining your funnel. For example, deploy your app long enough to collect a significant amount of data and then tweak the app accordingly. Redeploy for a second round of adjustments and then select another date range.

Description of funnel_workflow.png follows

Description of the illustration funnel_workflow.png

Creating Custom Analytics Reports

As a mobile program manager, you can keep an eye on the usage and health of your mobile app on an ongoing basis by creating a suite of custom reports that you can run whenever you want. MCS .

Say that you’ve launched the Fix-It-Fast (FiF) app in three cities. For each locale, you also want to find out daily peak usage times and also segment the user data by age group. To do this, you’d create a set of reports for the FiF app that include a New Users report, an Active Users report as well as a daily Session Duration report and an API calls report. MCS enables you to keep these reports on hand, organize them, update them, or delete reports that you no longer need. And you can create new reports as needed.

MCS organizes your custom reports into My Reports. To open My Reports:

Select the environment for your reports and then click to open the side menu.
Click Analytics to open the reports drawer.
Select My Reports.

Description of the illustration my_reports_drawer.png

The My Reports page lists all of the reports that you’ve created for a particular environment. That is, this page shows only the reports that you’ve created, not those created by someone else.

Note:

Not only do your reports belong only to you, but they also belong to the environment in which you created them. You can’t share a report across environments. Instead, you have to replicate a report for each environment.

How Do I Create a Custom Analytics Report?

You can save your custom report definitions while you’re looking at an analytics page, or from the My Reports page.

To create a report directly from a report page:

Select the environment.

Description of the illustration pick_env.png

Note:
You need to create separate sets of reports for each environment.
If needed, open Reports by clicking and then Analytics.
Choose the report type and apply any filters you need. Click Save.

Description of the illustration save_report.png
Complete the Save to My Reports dialog by entering a name and optionally, a description. Click Save.

Description of the illustration save_reports_dialog.png

Note:
Keep in mind that you’re saving everything in page; not just the filter criteria, but also the environment (Development, Staging, Production) and also the chart style (line or bar).

You can run, edit, or delete the report from the My Reports page.

You can also create a report from the My Reports page. Click New Report and then complete the dialog.

Description of my_reports_newrpt.png follows

Description of the illustration my_reports_newrpt.png

Complete the dialog by giving the report definition a name and an optional description. You also need to choose the type of report and the mobile backend (either All Backends or a specific mobile backend).

Description of saverpts_dialog_myreports.png follows

Description of the illustration saverpts_dialog_myreports.png

If you have no report definitions saved in My Reports, you can use this same dialog to create one. To access this dialog, click New Report.

Description of the illustration no_rpt_defs.png

My Reports

The My Reports page displays all the report definitions (reports) that you’ve created for a specific environment. From this page, you can organize your reports, run them, update them, and delete them.

MCS creates a tile for each report definition. The front of each tile lists the information that you provided when you created the report definition. Clicking

flips the tile over to reveal some additional information provided by MCS , such as the name of the mobile app, the reporting period, and the type of report. The information on the back of the tile varies depending on the type of report that you’ve defined. For example, an event report includes not only the mobile app name and the reporting period, but the selected endpoint as well.

Description of the illustration flip_card.png

Each tile has a menu which enables you to run, edit, or delete a report.
Description of tile_menu.png follows
Description of the illustration tile_menu.png

You can rearrange the reports to suit your needs by dragging and dropping the tiles. For example, if you have a report you want to run first thing every morning, you can drag it to the first position (right next to the New Report tile). You can also adjust the display using these options:

Any Backend—Displays all of the reports that you’ve created (including those created using the All Backends filter).
All Backends—Narrows the display to only the reports created using the All Backends filter.
By mobile backend—Displays only the reports created for a specific mobile backend.

Description of the illustration sort_reports.png

How Do I Run a Custom Report?

To run a report, first click and then click Run.
Description of tile_menu.png follows
Description of the illustration tile_menu.png

The report opens on the My Reports page. Depending on the number of tiles in the page, you may need to scroll down to see it.

Description of the illustration run_report.png

How Do I Edit a Custom Report?

If you need to change something about your report, first click and then click Edit.
Description of tile_menu_edit.png follows
Description of the illustration tile_menu_edit.png

You can’t change the report type, or the environment, but you can change the report name, description, reporting period and any filtering criteria. When you’ve made your changes, click Save. Click Reset to revert the report definition to its original state.

Description of the illustration edit_report.png

You can’t change the report type, but you can change the report name, description, reporting period and any filtering criteria. When you’ve made your changes, click Save. Click Reset to revert the report definition to its original state.

Tracking Sessions and Logging Events for Mobile Apps

The analytics libraries of the mobile client SDK enable the monitoring and measuring of any event that has been defined for the mobile app.

Knowing which item the user added to a shopping cart is better than just knowing that a user put some unnamed item in the cart. Likewise, you'd want to know which products users search for rather than just knowing that they've performed a search. To add this level of detail to your analysis, you can create events. You can further segment reports by adding properties that describe these events in terms of something that characterizes the event itself or an activity related to the event. Here’s an example of what an event looks like in JSON form (which is the payload format for the underlying REST calls that send event data to the service).

[
  ...
    {
        "name":"PurchaseFailed",
        "type":"custom",
        "timestamp":"2013-04-12T23:20:56.523Z",
        "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
        "properties":{
            "cartContent":"WIDGET",
            "cartPrice":"$50,000"
        }
   ...
 
]

The mobile client SDK provides you with a shorter route to generating analytics reports than does writing a straight REST call. After you’ve linked the mobile app to the platform-specific SDK, you can enable analytics reporting for your app by adding code that calls the analytics library and designates the beginning of the session before flushing the events to the server.

Creating Events and Sessions Using the iOS Library

The libOMCAnalytics.a library includes classes for logging the events and sessions from an iOS mobile app. You can also use the classes from this library to track successful and failed posts.

Sessions provide a means of grouping the events raised in the mobile app code, as the events logged between the start and end of a particular session belong to that session. As discussed further in Designating Sessions, you can call instance methods for starting and ending sessions as well as logging events to the service’s server.

Calling the Analytics Service

To call the Analytics service, import the OMCMobileBackend+OMC_Analytics.h and the OMCAnalytics.h header files in addition to the ones noted in Calling APIs Using the iOS SDK.

Designating Sessions

You can designate sessions by calling the startSession and endSession methods on the OMCAnalytics object. The endSession method automatically flushes events, but you can flush events explicitly by calling the flush method, which will post the currently outstanding events to the service’s server.

Tip:

Use the flush method if you have a large number of events that are logged between the start and end of a session.

The signatures for the startSession and endSession methods are as follows:

@interface OMCAnalytics : OMCServiceProxy
 
/** The Analytics service's delegate. */
@property (nonatomic, weak) id<OMCAnalyticsDelegate> delegate;
 
/**
 Starts an Analytics service session. If a session is already in progress, then it continues. A new session is not created.
  */
[analytics startSession];
 
/**
 Stops the current Analytics service session. Does nothing if a session is not in progress.
 */
 [analytics endSession]; 
/**
 Logs an Analytics service event with the specified name. If a session is not in progress,
it starts a session. Copies the specified name before returning.
 @param name the event name
 */
- (void)logEvent:(NSString*)name;
 
/**
 Logs an Analytics service event with the specified name and properties.
 If a session is not in progress, then it starts a session.
 Copies the specified name and properties before returning.
 @param name the event name
 @param properties a dictionary of arbitrarily named properties for the event
 */
- (void)logEvent:(NSString*)name properties:(NSDictionary*)properties;
 
/**
 Uploads all the posted events to the OMC Mobile Analytics REST service.
 */
- (void)flush;
 
@end

Note:

The startSession begins with the first logged event (even if no session has been started). The endSession method flushes events to the service’s server.

Associating a Session With Your Mobile App Being in the Foreground

A user session might correspond to the length of time that a user spends on the mobile app when it runs in the foreground. To associate Analytics sessions when your mobile app is running in the foreground, your app delegate should subclass OMCAnalyticsApplicationDelegate. Doing this will automatically log the start of a session when the mobile app moves the foreground and log the end of the session when the mobile app moves to the background. In general, you don’t need to call either startSession or endSession, as these are added automatically.

Adding Custom Properties to Events

You can describe an event more fully by adding one or more custom properties as key-value pairs.

Note:

Both the key and the value must be strings.

You can add custom properties to an event by calling the logEvent:properties: method and by passing a dictionary of property key-value pairs. For example:

[Analytics logEvent:@"Event name"]; 
properties:@{"customProp1":"value1", @"customProp2":@"value2"}];

Caution:

The following custom property names are reserved and can't be used for your event property names.

Carrier
Count
Country
Day
Hour
Locality
Manufacturer
Minutes
MobileAppKey
Model
Month
OS
OSVersion
OSBuild
PostalCode
Region
Week
Year

Receiving the Status of Event Posts

As an optional feature, you can implement the OMCAnalyticsDelegate protocol to receive notifications when the OMCAnalytics object posts events to the Analytics REST service successfully or encounters errors. To do this, you must register a delegate, an object that implements OMCAnalyticsDelegate with the OMCAnalytics object. For example:

OMCAnalytics* analytics = [[OMCMobileBackendManager sharedManager].defaultMobileBackend analytics];

analytics.delegate = myDelegate;

You can implement one or both of the following instance methods to receive event status:

Notifies the delegate that the OMCAnalytics object successfully posted events to the Analytics REST service.

(void)analytics:(OMCAnalytics*)analytics
  didPostEvents:(NSURLRequest*)request
       response:(NSHTTPURLResponse*)response 
   responseData:(NSData*)responseData;

Notifies the delegate that the OMCAnalytics object encountered a specified error.
```
 (void)analytics:(OMCAnalytics*)analytics
didFailWithError:(NSError*)error
```

Creating Events and Sessions Using the Android Library

The oracle-cloud-mobile-analytics.jar library includes the Analytics and Event classes that enable mobile apps to post events.

To enable the MCS to record your mobile app’s event data, this JAR must be placed in the libs directory of your project.

The Analytics class is a singleton client object that exposes the Analytics API and has the startSession, endSession, logEvent, and flush methods. To start and end the sessions, which group events, and upload the events to the server, call these methods in your mobile app’s code.

Method	Description
`startSession (Context context)`	Creates a new session.
`logEvent (String name)`	Adds a new event. The `logEvent` method starts a session automatically if one doesn’t already exist.
`logEvent (Event Event)`	Adds an existing event.
`endSession (Context context)`	Ends the current session.
`flush`	Uploads events to the MCS ’s server. Calling the `endSession` or `flush` methods uploads all of the buffered events to the MCS server. All event data is stored locally in JSON file until one of these methods is called. If a mobile app is offline, then it posts this file when it reconnects with the service’s server.

The Context parameter in the startSession and endSession methods is the Android Context class. See the Android Developers website http://developer.android.com.

Tip:

For long-running mobile apps, calling the flush method periodically not only reduces the size of the payload in the JSON file posted to the MCS server, but also keeps the MCS server up to date.

The following code snippet shows how to call the Analytics class methods.

public final class Analytics extends ServiceProxy {
    // Creates a new session and generates an $sessionStart Event.
    public void startSession(Context context);
 
    // Ends the current session and generates a $sessionEnd Event.
    public void endSession(Context context);
 
    // Adds a new Event object.
    public Event logEvent(String name);
 
    // Adds an existing Event object.
    public Event logEvent(Event event);

    // Forces the upload of buffered Events.
    public void flush();
}

The Event class’ methods create new events and their properties. As listed in the following table, this class also has events for returning information about an event, like its timestamp or its name.

Method	Description
`Event(String name, Date timestamp, Map<String, String> properties)`	Creates the new event.
`addProperty (String name, String value)`	The key-value pairs are managed by the `HashMap` interface. Call this method to add the key-value for a property to the existing map of event properties.
`getProperty`	Returns the properties associated with the event.
`getProperties`	Returns a property.
`getName`	Returns the name of the event.
`getTimeStamp`	Returns the date on which the event was recorded.

The following code snippet shows how to call these methods.

public final class Event {
    // Creates a new Event. Time stamp and properties can be null.
    public Event(String name, Date timestamp,  Map<String, String> properties)

    // Sets a key/value property for the Event.
    public Event addProperty(String name, String value);
     
    // Returns the Event's name.
    public String getName();
 
    // Returns the Event's properties.
    public HashMap<String, String> getProperties();
 
    // Returns the timestamp of the Event.
    public Date getTimestamp();

See Taking a Look at Events and Sessions in Android Apps for examples of using these methods, as well as guidelines on how the mobile app code can reference a mobile backend and the Analytics service.

Taking a Look at Events and Sessions in Android Apps

The following code samples show how to call the Analytics class’ method to add an event called “ShoppingCartCancelled” to your mobile app code:

...

Analytics analytics = mbe.getServiceProxy(Analytics.class);
 
client.startSession(this); // "this" is the Android View.
//...
client.logEvent("ShoppingCartCanceled");
//...
client.endSession(this);

...

Instead of adding a series of lines, you can add an event as well as properties as a single, fluent line of code:

...
mbe.getServiceProxy(Analytics.class).
    logEvent(new Event(this, "ShoppingCartCanceled").
         addProperty("cartSize", "2").
         addProperty("cartValue", "$50,000"));
...

Some general steps to follow when adding events to your Android app:

Add a reference to the MobileBackendManager class to access to the default moblie backend (which is specified in the oracle_mobile_cloud_config.xml file):
```
try {

     MobileBackendManager mbem = mobileBackendManager.getmanager();
     MobileBackend mbe = mbem.getDefaultMobileBackend(this);
```
Because you need to log a custom event, you must reference the Analytics service:
```
Analytics analytics = mbe.getServiceProxy(Analytics.class);
```
Create the event by calling the event constructor and pass in the name of the event, such as "Work Order on Hold":
Call the logEvent method and pass the event:
Call the flush method to post events to the MCS server.

Tip:
To end the session and post all of the events to the MCS server, call endSession instead.

Defining Sessions

Sessions, which can group events together, can vary in length: a session may represent the entire lifespan of an application, or a function within the application. Within your code, you can specify the start and end of sessions, as illustrated by the ShoppingCartCancelled event shown in Creating Events and Sessions Using the Android Library and the Purchase Start and Purchase Failed events in Creating Events and Sessions Using the iOS Library. If you don't specify the start of a session, the analytics libraries in the mobile client SDK create an implied session.

Exporting Event Data

The Analytics Export API lets you return event data or API call metadata as a JSON object, which you can then import into a third-party tool. You may also want to export event data before you permanently delete it by purging it from one or more mobile backends.

For details on how to query the API and information about the responses, see REST APIs for Oracle Mobile Cloud Service.

For details on how to query the API and information about the responses, see REST APIs for Oracle Autonomous Mobile Cloud

For example, say you want to export data for a custom event called MeanTimeResolution, which measures performance data for your team. To find out how your team stacks up against an industry benchmark, you’d post a call to the Analytics Export API to return the custom event data. Using a third-party tool, you can mash up the MeanTimeResolution event data with the benchmark data and create reports.

How Do I Request Event and API Logging Data?

You can return data as a JSON object by issuing a POST call to {baseUri}/mobile/system/analyticsExport.

If you are using basic authentication to connect to the mobile backend, see Authenticating with HTTP Basic in Direct REST Calls.
If you have OAuth enabled as the authentication mechanism for the mobile backend, see Authenticating with OAuth in Direct REST Calls.

If you plan to use a third-party tool to pull the analytic data on a nightly basis, you could use cURL or some other tool to run the automated job. Here’s some example cURL code for basic authentication:

curl -i
-X POST
-u team.user@example.com:Welcome123
-d @export.json
-H "Content-Type: application/json; charset=utf-8"
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce"
http://fif.cloud.oracle.com/mobile/system/analyticsExport

In the request body, you can specify whether you want to return custom events, or data from the API History Log by defining the required parameter, exportType. You can also limit the number of items returned in the JSON object and set the date range for the reporting period. A request body might look like this:

{
    "startDate": "2015-04-12",
    "endDate": "2015-05-12", 
    "exportType": "Events",
    "name": "IncidentRaised",
    "offset": 0,
    "limit": 1000
}

Here are the request body properties.

Request Body Parameters	Mandatory?	Description	Example
`startDate` and `endDate`	No. If you don’t define these values, then MCS applies these default values: `startDate` —The first timestamp of the first event or API call record. `endDate` —The current system time and date.	The start and end of the reporting period, expressed as `YYYY-MM-DD`.	`"startDate": "2015-04-12", "endDate": "2015-05-12",`
`exportType`	Yes	The type of data that you want to export: API calls or custom events.	`"exportType": "APICalls", "exportType": "Events",`
`name`	No	Depends on the value for `exportType`: For `APICalls`, refer to the names listed in the menus for the API Endpoint reports. For `Events`, the name of a custom event. Use the menus in Events report.	For an API: `“name”: “Analytics Collector”,` For a custom event: `“name”: “IncidentRaised”,`
`offset`	No	The zero-based index of the first item that’s returned. The default value is zero (`0`).	`"offset": 0`
`limit`	No	The maximum number of items returned by your call. If you set a limit that’s too high, then MCS substitutes a limit of 1000 (the default value).	`"limit": 500`

A portion of the thousand items in the JSON payload that’s returned by the call in the preceding example (a request for a custom event called IncidentsRaised) might look like this:

{ 
   "items":[ 
      { 
         "name":"IncidentRaised",
         "type":"custom",
         "timestamp":"2013-04-12T23:20:56.523Z",
         "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
         "component":"Incidents",
         "mobileApplicationKey":"cd4b13b5-608c-4a18-9ef4-341fe4873063",
         "deviceId":"cd4b13b5-608c-4a18-9ef4-asdfasd",
         "backendName":"FixitFastCustomer",
         "backendversion":"1.0",
         "userName":"JDoe123",
         "locality":"San Francisco",
         "region":"CA",
         "country":"US",
         "postalCode":"95549",
         "timezone":"-14400",
         "carrier":"Verizon",
         "model":"iPhone5,1",
         "manufacturer":"Apple",
         "osName":"iPhone OS",
         "osVersion":"7.1",
         "osBuild":"13E28",
         "customProperties":{ 
            "Appliance Manufacturer":"Abc Corp",
            "Model Number":"M1234"
         }
      },
      ...
   ],
   "hasMore":true
}

The request body for a platform API (the Analytics Collector) might look like this:

{
    "startDate": "2015-04-12T01:20:55.052Z",
    "endDate": "2015-05-12T01:20:55.052Z",
    "exportType": "APICalls",
    "name": "Analytics Collector",
    "offset": 0,
    "limit" : 1000
}

A portion of the returned JSON payload might look like this:

{
  "items": [
    {
        "backendName": "FixItFastTechnician",
        "backendVersion": "1.0",
        "apiName":"analytics",
        "apiVersion": "1.0",
        "apiImplementationName": "analytics",
        "apiImplementationVersion": "1.0",
        "resourcePath": "/events",
        "requestMethod": "POST",
        "requestTime": "2013-04-12T23:20:56.523Z",
        "executionTime": 20,
        "responseCode": "202",
        "responseMessage": "",
        "responseErrorId": "",
        "responseErrorMessage": "",
        "type": "ServiceableREST",
        "ecid": "f2cd201e-535b-48d7-afe2-e85a1f30406b-00007b19",
        "rid": "0",
        "parameters" : {
            "x": "x1",
            "y": "y1"
        }
    }
    ...
  ],
  "hasMore": true
}

Purging Analytics Data

You can purge analytics data through either the MCS UI or your application. Whichever method you choose, note that purging analytics data permanently removes it from the selected mobile backend(s). Data that has been purged can not be restored.

Purging Data through the MCS UI

First, export your data using the Export Data API before performing the purge. See Exporting Event Data for details.

Administrators must be assigned to the Mobile Deploy role to purge analytics data through the UI. To avoid server conflicts, you can run only one purge job at a time. Any purge request made while a purge is in progress is ignored.

On the side menu, select Administration , then Data Management.
Select the date range to purge analytics data.
Click the calendar icon to select the date. The default time is 12 am, but you can change it by clicking the clock icon.
Select All mobile backends, or individual backends.

Description of the illustration purge_analytics_data_dialog.png
Once you enter a date range and at least one mobile backend, click Purge.

Look for the results of the purge action under Purge History.

Note:

The time to complete a purge action varies depending on the size of the purge job. Large purge jobs can take some time to complete. Wait at least five to ten minutes before refreshing (

) the purge history to see the latest purge information.

Purging Data from an Application

Use the Analytics Data Management (ADM) API to make calls from your application to permanently purge data from selected backends. Purge means this API both deletes the data and “shrinks” the database that stores it in order to free up more space.

Like the purging feature you can use from the UI, the ADM API uses authentication, roles, and realms for security. Administrators assigned to the Mobile System role can purge MCS analytics data with the ADM API. You access this API through the mobile client SDK, or directly through REST calls. To avoid MCS server conflicts, you can run only one purge job at a time. MCS ignores purge requests made while a purge is in progress.

To access the Analytics Data Management API through the mobile client SDK, use a backend manager class.

For Android apps, you use the MobileManager class as described in .
Calling Platform APIs Using the SDK for Android
For iOS apps, you use the OMCMobileBackendManager class as described in .
Calling Platform APIs Using the SDK for iOS
For Cordova and JavaScript apps, you use the mobileBackendManager class as described in Calling Platform APIs Using the SDK for Cordova and Calling Platform APIs Using the SDK for JavaScript.

For detailed information about the platform APIs, see REST APIs for Oracle Mobile Cloud Service.

Troubleshooting Analytics Reports

MCS generates analytics reports based on artifacts created on the MCS server, events defined in the mobile app code, and by the mobile client SDK. Depending on these factors, none, or all, of the reports may be available.

Problem Solution

Problem	Solution
No reports	When you first log into MCS , there aren’t any reports because you have yet to create a mobile backend for the mobile app.
Only the API Calls Count and API Calls Response Time appear, but there are no user, session, or event reports.	MCS creates two sets of mobile analytics reports: reports for server activity and reports for sessions and events defined in the mobile app’s code. In this case, only the calls from testing the endpoints are recorded, because no data has yet been sent from the mobile app. Only the endpoint reports are available if you’ve just created a mobile backend, but haven’t yet registered a mobile app as its client app. While you can call the endpoints of Custom Code APIs directly by testing them, MCS can’t chart session or events reports because these calls don’t originate from a registered mobile app, whose code defines event and sessions. MCS creates user, session, and event reports when a registered mobile app that uses the mobile client SDK (or has sessions defined in its code) calls the Analytics API. Keep in mind that if there isn't a mobile app to provide events, then there will be no data for funnel reports. In this case, MCS displays a page that says, “You have no analytics data for this mobile backend.”
API calls generate analytics data, eventually using up database space resulting in system issues or loss of service.	MCS automatically generates analytics data for every API invocation. This data accumulates over time and can use up all available database space, which can result in system instability or even complete loss of service. Before storage capacity reaches full, modify the `Analytics_ApiCallEventCollectionEnabled` policy by setting the policy to `false` to prevent automatic generation of analytics data with each API call.

No reports

When you first log into MCS , there aren’t any reports because you have yet to create a mobile backend for the mobile app.

Only the API Calls Count and API Calls Response Time appear, but there are no user, session, or event reports.

MCS creates two sets of mobile analytics reports: reports for server activity and reports for sessions and events defined in the mobile app’s code. In this case, only the calls from testing the endpoints are recorded, because no data has yet been sent from the mobile app.

Only the endpoint reports are available if you’ve just created a mobile backend, but haven’t yet registered a mobile app as its client app. While you can call the endpoints of Custom Code APIs directly by testing them, MCS can’t chart session or events reports because these calls don’t originate from a registered mobile app, whose code defines event and sessions.

MCS creates user, session, and event reports when a registered mobile app that uses the mobile client SDK (or has sessions defined in its code) calls the Analytics API. Keep in mind that if there isn't a mobile app to provide events, then there will be no data for funnel reports. In this case, MCS displays a page that says, “You have no analytics data for this mobile backend.”

API calls generate analytics data, eventually using up database space resulting in system issues or loss of service.

MCS automatically generates analytics data for every API invocation. This data accumulates over time and can use up all available database space, which can result in system instability or even complete loss of service.

Before storage capacity reaches full, modify the Analytics_ApiCallEventCollectionEnabled policy by setting the policy to false to prevent automatic generation of analytics data with each API call.

What Can I Do With Analytics?

How Does MCS Create Analytics Reports?

Enabling Your Mobile Apps to Report Event Data

Adding Location Properties to the context Event

Integrating Analytics into a Mobile App Using the Mobile Client SDK

Understanding Different Types of Analytics Reports

Accessing the Analytics Reports

API Calls Reports

API Calls Count

API Calls Response Time

Events Report

Events

User and Session Reports

User Reports

Why User Counts Can Vary

User Session Reports

New Users

Active Users

Session Count

Session Duration

Improving User Retention with Funnel Analysis

Creating a Funnel

Analyzing Funnels

Creating Custom Analytics Reports

How Do I Create a Custom Analytics Report?

My Reports

How Do I Run a Custom Report?

How Do I Edit a Custom Report?

Tracking Sessions and Logging Events for Mobile Apps

Creating Events and Sessions Using the iOS Library

Calling the Analytics Service

Designating Sessions

Associating a Session With Your Mobile App Being in the Foreground

Adding Custom Properties to Events

Receiving the Status of Event Posts

Creating Events and Sessions Using the Android Library

Taking a Look at Events and Sessions in Android Apps

Defining Sessions

Exporting Event Data

Purging Analytics Data

Troubleshooting Analytics Reports

Adding Location Properties to the `context` Event