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.
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.
Tip:
Mobile program managers should decide which aspects of an app to track by events early in the app development process.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.
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
-
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.
[
{
"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
-
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
, orusername
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
andsessionEnd
events just likePurchaseFailed
in the preceding example, as noted by“type”:”custom”
.Note:
Ensure that these events share the samesessionID
value. When events have the samesessionID
value, theMCS server can approximate the session even if part of the payload (like theendSession
definition) isn’t recorded by the database.
Why Should I Use 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
, andlongitude
for context events.Note:
On the server, thelongitude
andlatitude
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) orsystem
for session or context events. The SDK also adds atimeStamp
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.
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 includelongitude
and latitude
in the context
event if you define any of these properties.
{
"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 |
---|---|
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. |
|
Track app usage and performance, as well as how apps use MCS . |
|
Enables you to answer such questions about engagement as:
|
|
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.
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.
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 theAnalytics_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.
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.
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.
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
-
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.
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.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.
Improving User Retention with Funnel Analysis
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.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.
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.
Analyzing Funnels
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.
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.
-
Select the environment for your reports and then click to open the side menu.
-
Click Analytics to open the reports drawer.
-
Select My Reports.
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.
-
Select the environment.
Description of the illustration pick_env.pngNote:
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.
-
Complete the Save to My Reports dialog by entering a name and optionally, a description. Click Save.
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.
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.
Each tile has a menu which enables you to run, edit, or delete a report.
Description of the illustration tile_menu.png
-
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.
How Do I Run a Custom Report?
To run a report, first click and then click Run.
Description of the illustration tile_menu.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 the illustration tile_menu_edit.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
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 theflush
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:
ThestartSession
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.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
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;
-
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.
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.
|
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 theflush
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.
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();
}
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. |
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);
...
...
mbe.getServiceProxy(Analytics.class).
logEvent(new Event(this, "ShoppingCartCanceled").
addProperty("cartSize", "2").
addProperty("cartValue", "$50,000"));
...
-
Add a reference to the
MobileBackendManager
class to access to the default moblie backend (which is specified in theoracle_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, callendSession
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
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:
|
The start and end of the reporting period, expressed as YYYY-MM-DD .
|
|
exportType |
Yes | The type of data that you want to export: API calls or custom events. |
|
name |
No | Depends on the value for exportType :
|
|
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 |
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
}
{
"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.
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.
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.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.
-
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 |
---|---|
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 |