Legacy Analytics API

E Legacy Analytics API

This chapter provides documentation for the legacy Analytics API.

Enabling Your Mobile Apps to Report Event Data

With the legacy analytics features, OMCe 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 client SDK for your mobile platform. In either case, OMCe 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 OMCe server. OMCe considers this content as a session that it can log. Theoretically, an analytic session can remain open for longer than a single batch update to the OMCe 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 client SDK tracks analytic sessions on a file system, which means that a file grows as you add more events to a session. The MAF MCS Utility, which allows mobile apps built using Oracle Mobile Application Framework (MAF) to access OMCe, 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 OMCe. See MAF MCS 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 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 client SDK generates the time stamp automatically.

A JSON payload posted to OMCe 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 client SDK adds both session and device context information to the payload automatically.

Creating Your Own JSON Payload

If you don’t use the 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, the OMCe server can approximate the session even if part of the payload (like the endSession definition) isn’t recorded by the database.

OMCe 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.

How the Client SDK Fits In

You can enable analytics for an app through OMCe’s client SDK for the app’s platform. Each client SDK has a configuration file where you can enable analytics either for the mobile backend that the app is using for the OMCe analytics app that it specifies.

The 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.
Marks events raised in mobile app code as custom or system for session or context events. It also adds a timeStamp to each event.

For specifics on each platform, see:

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 OMCe 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 Client SDK

The client SDKs that OMCe provides for each mobile platform enable mobile apps deployed on those platforms to post events to the Analytics API.

Enabling Your Mobile Apps to Report Event Data

Adding Location Properties to the context Event

Integrating Analytics into a Mobile App Using the Client SDK

Adding Location Properties to the `context` Event