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 aren't 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 also can intersperse context events with custom events to indicate changes in context, such as a location change.
  • You define the location in context events either by defining locality, region, postalCode, and country or by defining latitude and longitude, one or the other, not both.
  • 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.

Permissions

You can access this operation as a social user, a virtual user, an anonymous user, or a mobile user. If you access this operation as a virtual user or a mobile user, then you must have the role that's associated with the mobile backend.

Request

Supported Media Types
Header Parameters
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 key can be up to 500 characters long. The value can be 1000 characters long. The property value must be a string and can't be any of the following reserved names:

    • appBuild

    • appId

    • appStartDate

    • appVersion

    • architecture

    • carrier

    • count

    • country

    • crashLog

    • crashReporterKey

    • crashTypeKey

    • day

    • exceptionName

    • exceptionReason

    • hour

    • locality

    • manufacturer

    • minutes

    • mobileAppKey

    • model

    • month

    • OS

    • OSVersion

    • OSBuild

    • postalCode

    • processName

    • region

    • week

    • year

  • 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 isn't formatted correctly, the service rejects the event and doesn't 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 key can be up to 500 characters long. The value can be 1000 characters long. The property value must be a string and can't be any of the following reserved names:

  • appBuild

  • appId

  • appStartDate

  • appVersion

  • architecture

  • carrier

  • count

  • country

  • crashLog

  • crashReporterKey

  • crashTypeKey

  • day

  • exceptionName

  • exceptionReason

  • hour

  • locality

  • manufacturer

  • minutes

  • mobileAppKey

  • model

  • month

  • OS

  • OSVersion

  • OSBuild

  • postalCode

  • processName

  • region

  • week

  • year

Show Source
Example Request (application/json)
[
    {
        "name":"context",
        "type":"system",
        "properties":{
            "carrier":"AT&T",
            "osBuild":"13E28",
            "osVersion":"7.1",
            "timezone":"-14400",
            "latitude":"37.35687",
            "model":"iPhone5,1",
            "osName":"iPhone OS",
            "userName":"GDoe321",
            "longitude":"-122.11663",
            "manufacturer":"Apple"
        },
        "timestamp":"2018-04-12T23:20:54.345Z"
    },
    {
        "name":"sessionStart",
        "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
        "type":"system",
        "timestamp":"2018-04-12T23:20:55.052Z"
    },
    {
        "component":"ShoppingCartActivity",
        "name":"PurchaseFailed",
        "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
        "type":"custom",
        "properties":{
            "cartPrice":"32.99",
            "cartContent":"sweater"
        },
        "timestamp":"2018-04-12T23:20:56.523Z"
    },
    {
        "name":"PushNotificationReceived",
        "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
        "properties":{
            "notificationType":"Discount Promotion"
        },
        "timestamp":"2018-04-12T23:20:59.052Z"
    },
    {
        "name":"context",
        "type":"system",
        "properties":{
            "country":"Canada",
            "carrier":"AT&T",
            "osBuild":"13E28",
            "osVersion":"7.1",
            "timezone":"-14400",
            "postalCode":"K1A0A1",
            "locality":"Ottawa",
            "model":"iPhone5,1",
            "osName":"iPhone OS",
            "region":"Ontario",
            "userName":"JDoe123",
            "manufacturer":"Apple"
        },
        "timestamp":"2018-04-12T23:23:34.345Z"
    },
    {
        "name":"PictureSaveFailed",
        "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
        "properties":{
            "size":"5MB",
            "source":"camera"
        },
        "timestamp":"2018-04-12T23:23:58.525Z"
    },
    {
        "name":"sessionEnd",
        "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
        "type":"system",
        "timestamp":"2018-04-12T23:25:55.052Z"
    }
]
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 isn't well-formed JSON, or because an exception occurred during processing.

Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by the service.
Show Source
Nested Schema : o:errorDetails
Type: array
Minimum Number of Items: 0
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 isn't supported by the resource.

Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by the service.
Show Source
Nested Schema : o:errorDetails
Type: array
Minimum Number of Items: 0
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-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":"2018-06-15T23: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":"2018-06-15T23:20:55.052Z",
    "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce"
  },
  {
    "name":"PurchaseFailed",
    "type":"custom",
    "timestamp":"2018-06-15T23:20:56.523Z",
    "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
    "component":"ShoppingCartActivity",
    "properties":{
      "cartContent":"A123-5EX",
      "cartPrice":"$50.00"
    }
  },
  {
    "name":"PushNotificationReceived",
    "type":"custom",
    "timestamp":"2018-06-15T23:20:59.052Z",
    "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
    "properties":{
      "notificationType":"Discount Promotion"
    }
  },
  {
    "name":"context",
    "type":"system",
    "timestamp":"2018-06-15T23: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":"2018-06-15T23:23:58.525Z",
    "sessionID":"2d64d3ff-25c7-4b92-8e49-21884b3495ce",
    "properties":{
      "source":"camera",
      "size":"5MB"
    }
  },
  {
    "name":"sessionEnd",
    "type":"system",
    "timestamp":"2018-06-15T23:58: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: Mon, 15 Jun 2018 23:58:55 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