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 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
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 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 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.
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
- 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
Deprecated.
-
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 the service using the Mobile 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
, andsessionEnd
. -
properties(optional):
object 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
-
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 isn't formatted correctly, the service rejects the event and doesn't log it.
-
type(optional):
string
The type of event. Use
custom
for custom events and usesystem
forcontext
,sessionStart
, andsessionEnd
events. If omitted, the event is considered to be acustom
event.
object
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
-
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
, orcountry
, then the service 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
, orcountry
, then the service 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.
[
{
"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"
}
]
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 isn't 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
The service's error code.
-
o:errorDetails(optional):
array o:errorDetails
Minimum Number of Items:
0
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
URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
The service's 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 isn't 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
The service's error code.
-
o:errorDetails(optional):
array o:errorDetails
Minimum Number of Items:
0
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
URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
The service's 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-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."}