1. REST API for Oracle Mobile Cloud Service
  2. Tasks
  3. Analytics Collector

Add Events to the Analytics Database

post

/mobile/platform/analytics/events

This operation accepts a batch of events and validates them. If they are valid, they are sent to the Analytics database. If one or more events in a batch are not valid, then no events are sent to the Analytics database.

Note that you can use the mobile client SDK to post events to this API. When you use the SDK, it adds the necessary system events to the request body along with your custom events, and it arranges the events in the correct order.

If you aren't using the mobile client SDK, keep the following in mind:

  • There are two types of events--custom and system. Use the custom events to record the events that you want to analyze. Use the system events to group your custom events. Note that if you don't specify the event type, then the event defaults to custom.
  • Events are JSON objects. All events must have a name and a timestamp, and component and properties are optional.
  • If you want to provide context to a session, then precede the sessionStart event with a system event named context. You can also intersperse context events with custom events to indicate changes in context, such as a location change.
  • You can group events by session. For example, a session can mark the beginning and ending of a function within the application or when an application starts and stops. You start a session by adding a system event with the name sessionStart. You use a sessionEnd event to end the session. You use a session ID to associate events with a session. You have two ways to specify a session ID for an event. You can add a sessionId property to an event, and you can set the Oracle-Mobile-Analytics-Session-ID header.
  • To associate the batch of events with an application, include the Oracle-Mobile-Application-Key header set to the application's key.

Permissions

The request can be performed anonymously or by a user who's a member of the realm that's associated with the mobile backend.

Request

Supported Media Types
Header Parameters

  • You can use this header to specify a default session ID. Use a session ID to group all events in the request body by a user-defined session. When present, the sessionID value in the event object overrides this value.

  • You can use this header to identify the application key that MCS assigns to your application when you register it with the mobile backend. You can find this key in the Clients tab for the mobile backend.

    Example

    9a5b4150-c756-4758-87c3-ec2814289799

  • You can use this header to identify the device ID. This is the ID that is returned when you register the device with MCS using the Devices API. This is typically performed by the mobile client SDK when the app starts.
Body ()
Root Schema : eventArray
Type: array
Minimum Number of Items: 1
An array of events.
Show Source
Nested Schema : event
Type: object
The event metadata.
Show Source
  • An optional attribute for custom use.
  • A client or system-defined event name. This name can be up to 100 characters long. System event names are `context`, `sessionStart`, and `sessionEnd`.
  • properties
    Additional Properties Allowed: additionalProperties
    In addition to the properties described here, you can include your own custom properties. The property names can't be reserved names and the properties values must be strings. See Adding Custom Properties to Events in Using Oracle Mobile Cloud Service for the list of reserved names.
  • Identifies the session that this event is for. This value overrides the `Oracle-Mobile-Analytics-Session-ID` header value, if it is present.
  • The time of the event specified in RFC 3339 format as UTC. **Note**: If this timestamp is formatted incorrectly, MCS will reject the event and not log it.
  • The type of event. Use `custom` for custom events and use `system` for `context`, `sessionStart`, and `sessionEnd` events. If omitted, the event is considered to be a `custom` event.
Nested Schema : properties
Type: object
Additional Properties Allowed
Show Source
In addition to the properties described here, you can include your own custom properties. The property names can't be reserved names and the properties values must be strings. See Adding Custom Properties to Events in Using Oracle Mobile Cloud Service for the list of reserved names.
Show Source
Example Request (application/json)
[
    {
        "timestamp":"2013-04-12T23:20:54.345Z",
        "name":"context",
        "properties":{
            "model":"iPhone5,1",
            "timezone":"-14400",
            "osVersion":"7.1",
            "manufacturer":"Apple",
            "userName":"GDoe321",
            "carrier":"AT&T",
            "longitude":"-122.11663",
            "latitude":"37.35687",
            "osName":"iPhone OS",
            "osBuild":"13E28"
        },
        "type":"system"
    },
    {
        "timestamp":"2013-04-12T23:20:55.052Z",
        "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
        "name":"sessionStart",
        "type":"system"
    },
    {
        "timestamp":"2013-04-12T23:20:56.523Z",
        "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
        "component":"ShoppingCartActivity",
        "name":"PurchaseFailed",
        "properties":{
            "cartContent":"sweater",
            "cartPrice":"32.99"
        },
        "type":"custom"
    },
    {
        "timestamp":"2013-04-12T23:20:59.052Z",
        "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
        "name":"PushNotificationReceived",
        "properties":{
            "notificationType":"Discount Promotion"
        }
    },
    {
        "timestamp":"2013-04-12T23:23:34.345Z",
        "name":"context",
        "properties":{
            "region":"Ontario",
            "model":"iPhone5,1",
            "timezone":"-14400",
            "osVersion":"7.1",
            "postalCode":"K1A0A1",
            "manufacturer":"Apple",
            "userName":"JDoe123",
            "locality":"Ottawa",
            "carrier":"AT&T",
            "osName":"iPhone OS",
            "country":"Canada",
            "osBuild":"13E28"
        },
        "type":"system"
    },
    {
        "timestamp":"2013-04-12T23:23:58.525Z",
        "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
        "name":"PictureSaveFailed",
        "properties":{
            "source":"camera",
            "size":"5MB"
        }
    },
    {
        "timestamp":"2013-04-12T23:25:55.052Z",
        "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
        "name":"sessionEnd",
        "type":"system"
    }
]
Back to Top

Response

Supported Media Types

202 Response

The events were logged successfully.

Body ()
Root Schema : Success
Type: object
Title: Success
Show Source

400 Response

The request failed because the request body is not well-formed JSON, or because an exception occurred during processing.

Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by Mobile Cloud Service.
Show Source
Nested Schema : o:errorDetails
Type: array
Minimum Number of Items: 0
List of the issues that cause the error. Included when the error is caused by multiple issues.
Show Source
Nested Schema : Error Detail
Type: object
Title: Error Detail
Show Source

405 Response

The request failed because it uses a method that is not supported by the resource.

Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by Mobile Cloud Service.
Show Source
Nested Schema : o:errorDetails
Type: array
Minimum Number of Items: 0
List of the issues that cause the error. Included when the error is caused by multiple issues.
Show Source
Nested Schema : Error Detail
Type: object
Title: Error Detail
Show Source
Back to Top

Examples

The following example shows how to report event data by submitting a POST request on the REST resource using cURL.

curl -i \
-X POST \
-d @events.json \
-u mobile.user@example.com:password \
-H "Content-Type: application/json" \
-H "Oracle-Mobile-Application-Key: e25b7dce-d392-403d-b5c6-bf06c0fd3586" \
-H "Oracle-Mobile-Backend-ID: 7fd145da-5807-46a5-b9da-783ba20885cc" \
-H "Oracle-Mobile-Device-ID: ABC-123-45-67890" \
https://fif.cloud.oracle.com/mobile/platform/analytics/events

Example of Request Body

The following shows an example of the request body in JSON format. This example illustrates an array of events.

[
  {
    "name":"context",
    "type":"system",
    "timestamp":"2015-04-12T23:20:54.345Z",
    "properties":{
      "userName":"GDoe321",
      "latitude":"37.35687",
      "longitude":"-122.11663",
      "timezone":"-14400",
      "carrier":"AT&T",
      "model":"iPhone5,1",
      "manufacturer":"Apple",
      "osName":"iPhone OS",
      "osVersion":"7.1",
      "osBuild":"13E28"
    }
  },
  {
    "name":"sessionStart",
    "type":"system",
    "timestamp":"2015-04-12T23:20:55.052Z",
    "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce"
  },
  {
    "name":"PurchaseFailed",
    "type":"custom",
    "timestamp":"2015-04-12T23:20:56.523Z",
    "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
    "component":"ShoppingCartActivity",
    "properties":{
      "cartContent":"A123-5EX",
      "cartPrice":"$50.00"
    }
  },
  {
    "name":"PushNotificationReceived",
    "type":"custom",
    "timestamp":"2015-04-12T23:20:59.052Z",
    "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
    "properties":{
      "notificationType":"Discount Promotion"
    }
  },
  {
    "name":"context",
    "type":"system",
    "timestamp":"2015-04-12T23:23:34.345Z",
    "properties":{
      "userName":"GDoe321",
      "latitude":"37.33527",
      "longitude":"-122.03255",
      "timezone":"-14400",
      "carrier":"AT&T",
      "model":"iPhone5,1",
      "manufacturer":"Apple",
      "osName":"iPhone OS",
      "osVersion":"7.1",
      "osBuild":"13E28"
    }
  },
  {
    "name":"PictureSaveFailed",
    "type":"custom",
    "timestamp":"2015-04-12T23:23:58.525Z",
    "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
    "properties":{
      "source":"camera",
      "size":"5MB"
    }
  },
  {
    "name":"sessionEnd",
    "type":"system",
    "timestamp":"2015-04-12T23:25:55.052Z",
    "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce"
  }
]

Example of Response Header

The following shows an example of the response header:

202 Accepted
Content-Type: application/json
Date: Sun, 12 Apr 2015 23:26:33 GMT

Example of Response Body

The following example shows the contents of the response body in JSON format:

{"message": "5 events accepted for processing."}
Back to Top