Add Events to the Analytics Database
/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
andsystem
. 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 tocustom
. - Events are JSON objects. All events must have a
name
and atimestamp
, andcomponent
andproperties
are optional. - If you want to provide context to a session, then precede the
sessionStart
event with a system event namedcontext
. 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 asessionEnd
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 asessionId
property to an event, and you can set theOracle-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
- application/json
-
Oracle-Mobile-Analytics-Session-ID(optional): string
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 theevent
object overrides this value. -
Oracle-Mobile-Application-Key(optional): string
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
-
Oracle-Mobile-Device-ID(optional): string
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.
array
1
-
Array of:
object event
The event metadata.
object
-
component(optional):
string
An optional attribute for custom use.
-
name:
string
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(optional):
object properties
Additional Properties Allowed: additionalPropertiesIn 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.
-
sessionID(optional):
string
Identifies the session that this event is for. This value overrides the `Oracle-Mobile-Analytics-Session-ID` header value, if it is present.
-
timestamp:
string
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.
-
type(optional):
string
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.
object
-
carrier(optional):
string
The mobile device's carrier.
-
country(optional):
string
The mobile device's GPS country.
-
latitude(optional):
string
The mobile device's GPS latitude. If you provide `locality`, `region`, `postalCode`, or `country`, then MCS ignores this value.
-
locality(optional):
string
The mobile device's locality, such as city, township, or village.
-
longitude(optional):
string
The mobile device's GPS longitude. If you provide `locality`, `region`, `postalCode`, or `country`, then MCS ignores this value.
-
manufacturer(optional):
string
The mobile device's manufacturer.
-
model(optional):
string
The mobile device's model name.
-
osBuild(optional):
string
The build of the mobile device's operating system.
-
osName(optional):
string
The name of the mobile device's operating system.
-
osVersion(optional):
string
The version of the mobile device's operating system.
-
postalCode(optional):
string
The mobile device's postal code.
-
region(optional):
string
The mobile device's region, such as state, canton, or province.
-
timezone(optional):
string
The mobile device's offset in seconds from UTC.
-
userName(optional):
string
The user name for the signed in user.
[
{
"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"
}
]
Response
- application/json
202 Response
The events were logged successfully.
object
Success
-
message:
string
The success message for a successful event collection.
400 Response
The request failed because the request body is not well-formed JSON, or because an exception occurred during processing.
object
Error
-
detail:
string
Message that provides the error details.
-
o:ecid:
string
Execution context ID, which is a unique identifier to correlate events or requests that are associated with the same transaction across several components.
-
o:errorCode:
string
Mobile Cloud Service error code.
-
o:errorDetails(optional):
array o:errorDetails
Minimum Number of Items:
0
List of the issues that cause the error. Included when the error is caused by multiple issues. -
o:errorPath:
string
The relative point in the API path where the error occurred.
-
status:
integer
HTTP status code. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more details.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
array
0
-
Array of:
object Error Detail
Title:
Error Detail
object
Error Detail
-
instance:
string
The URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
Mobile Cloud Service error code.
-
o:errorPath:
string
The relative point in the API path where the error occurred.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
405 Response
The request failed because it uses a method that is not supported by the resource.
object
Error
-
detail:
string
Message that provides the error details.
-
o:ecid:
string
Execution context ID, which is a unique identifier to correlate events or requests that are associated with the same transaction across several components.
-
o:errorCode:
string
Mobile Cloud Service error code.
-
o:errorDetails(optional):
array o:errorDetails
Minimum Number of Items:
0
List of the issues that cause the error. Included when the error is caused by multiple issues. -
o:errorPath:
string
The relative point in the API path where the error occurred.
-
status:
integer
HTTP status code. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more details.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
array
0
-
Array of:
object Error Detail
Title:
Error Detail
object
Error Detail
-
instance:
string
The URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
Mobile Cloud Service error code.
-
o:errorPath:
string
The relative point in the API path where the error occurred.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
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."}