14 Analytics
Oracle Mobile Hub 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 the Analytics Reports Are Created
Mobile Hub 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.Enable Your Mobile Apps to Report Event Data
Mobile Hub 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, Mobile Hub 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 Mobile Hub 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 Mobile Hub 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.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.
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. 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
Ensure that these events share the samesessionStart
andsessionEnd
events just likePurchaseFailed
in the preceding example, as noted by“type”:”custom”
.sessionID
value. When events have the samesessionID
value, the 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. On the server, thelongitude
andlatitude
values are translated into city, country, postal code, and street. -
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 Mobile Hub 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).
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"
}
Integrate 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 Connect Your App to a Mobile Backend. .
Understand 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 Mobile Hub. |
|
Enables you to answer such questions about engagement as:
|
|
Stores your saved report definitions. |
Access the Analytics Reports
Click to open the side menu and then Mobile Hub 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 Mobile Hub 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.
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 Mobile Hub 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.
Mobile Hub 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.
API Calls Response Time
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.
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, Mobile Hub 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.
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
Mobile Hub 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.
Mobile Hubapplies 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 is then applied 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, Mobile Hub 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
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
Mobile Hub approximates user counts through user IDs and device IDs.
For the events sent from mobile apps, Mobile Hub 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 Mobile Hub 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 Mobile Hub 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.
Active Users
Mobile Hub 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.
Improve 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. 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_amce.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.
Create 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.
Analyze 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.
Create 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. Mobile Hub.
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. Mobile Hub 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.
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. 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:
You can also create a report from the My Reports page. Click New Report and then complete the dialog.
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.
-
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.
Track Sessions and Log 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.
Create 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.
Call 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 Call the APIs Using the iOS SDK.
Designate 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
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.
Associate 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.
Add Custom Properties to Events
You can describe an event more fully by adding one or more custom properties as key-value pairs.
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
Receive 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
Create 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 Mobile Hub 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 Mobile Hub’s server. Calling the endSession or flush methods uploads all of the buffered events to the Mobile Hub 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 Mobile Hub server, but also keeps the 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. Take 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 Mobile Hub server.Tip:
To end the session and post all of the events to the Mobile Hub server, callendSession
instead.
Define 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 Create Events and Sessions Using the Android Library and the Purchase Start
and Purchase Failed
events in Create 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.
Export 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 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 Authenticate with HTTP Basic in Direct REST Calls.
-
If you have OAuth enabled as the authentication mechanism for the mobile backend, see Authenticate 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 Mobile Hub Mobile Hub 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 Mobile Hub 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
}
Purge Analytics Data
You can purge analytics data through either the service 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.
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 Mobile Hub analytics data with the ADM API. You access this API through the mobile client SDK, or directly through REST calls. To avoid server conflicts, you can run only one purge job at a time. The service 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.
Troubleshoot Analytics Reports
Mobile Hub generates analytics reports based on artifacts created on the Mobile Hubserver, 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 Mobile Hub, 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. |
Mobile Hub 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, Mobile Hub can’t chart session or events reports because these calls don’t originate from a registered mobile app, whose code defines event and sessions. Mobile Hub 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, Mobile Hub 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. |
Mobile Hub 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 |