Close

Event API

The Event API allows you to store event data in Omniata. Provide the user identifier and the action type you want to track and Omniata will process and store the event for segmentation and analysis. For more information on how to create custom events, check Events.

In this guide:

Events: get

Request Definition

The API URL is assigned per organization. We use “{orgname}” as an example, when testing use your organization’s assigned subdomain name defined in the Omniata panel.

GET https://{orgname}.analyzer.omniata.com/event

Example request:

$ curl -I "http://{orgname}.analyzer.omniata.com/event?api_key=11111111&om_event_type=om_load&uid=10000001A&om_device=generic&om_platform=android"

Parameters

All Event API calls made using the Omniata SDK include a set of automatically added parameters. The following are the most common parameters:

Name Description
api_key
mandatory
Identifies multiple aspects of the events such as the organization and environment.
uid
mandatory
Uniquely identifies a user within the organization’s UID domain.
om_event_type
mandatory
Identifies the Event Type, e.g. om_load, om_revenue, om_user.
om_platform
mandatory
The platform, standard ones are: ios, android, amazon, canvas.
om_device
optional, added by SDK
The device model.
om_os_version
optional, added by SDK
The version of the user’s operating system.
om_sdk_version
optional, added by SDK
The version of the server code or SDK.
om_device_id
optional, added by SDK
The device ID.
om_bundle_version
optional, added by SDK
The version of the game or bundle release.

Parameters marked as “mandatory” must be included in each call regardless of the integration type.

Response

Besides the standard HTTP response headers, the Event API response has the Cross-Origin Resource Sharing-related header. For more information see https://www.w3.org/TR/cors/.

Example response:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Cache-Control: no-cache
Content-Length: 43
Content-Type: image/gif
Date: Thu, 23 Feb 2017 16:18:26 GMT
Last-Modified: Mon, 28 Sep 1970 06:00:00 GMT
Pragma: no-cache
Server: Omniata-EP/1.0
Connection: keep-alive
Click and drag to move
Standard Event Types

Omniata SDK and the panel metrics use two mandatory event types. Any event type can be extended to include custom parameters, however the event types mandatory parameters should be kept the same.

Standard Event Types

Omniata SDK and the panel metrics use two mandatory event types. Any event type can be extended to include custom parameters, however the event types mandatory parameters should be kept the same.

Tracking the two mandatory events enables a number of standard reports including metrics such as DAU, ARPU, ARPPU, Conversion Rate, Retention, Session Length, Churned Users and many others, check the Free to Play Package to learn more.

Event Type Name Description
om_load
mandatory
Indicates that a user has loaded the application, or has moved the application from background to foreground.
om_revenue
mandatory
Indicates that the user performed an action that generated real world revenue like an In-App. Purchase (or IAP), the event specifies the amount of revenue generated and the currency used.
om_user
optional
Used to explicitly update demographic user attributes such as gender or date of birth.
om_deghost
optional
Marks the user as “ghost” in the user state, Standards Metrics aggregations ignore users marked as ghosts.
om_apns_enable
optional, added by SDK
Enables push notifications delivery for iOS in Omniata.
om_apns_disable
optional, added by SDK
Disables push notifications delivery for iOS in Omniata.
om_gcm_enable
optional, added by SDK
Enables push notifications delivery for Android in Omniata.
om_gcm_disable
optional, added by SDK
Disables push notifications delivery for Android in Omniata.
om_push_sent
optional, added by panel
Indicates that a push notification was sent to the user. Applies for iOS and Android.
om_push_clicked
optional, added by SDK
Sent from the SDK whenever a push notification is received and clicked. The event is sent whenever there is internet connection.
om_update_user
optional
Used to modify/update the user state without altering the activity of the user. These events do not update user’s last action time and other activity-based state fields.
om_email_enable
optional
Register the user as eligible to receive an email. Sets up the email address to deliver content.
om_email_disable
optional
Removes the user from the email delivery lists.

om_load

In addition to the mandatory event parameters the SDK will pick up parameters automatically. See the documentation of the SDK for Android, iOS or Unity for details.

Common parameters:

Name Example Definition
api_key 11111111 Key that maps to the application in Omniata.
om_delta 1 The amount of time in seconds between the event creation and event sending.
om_event_type om_load Qualifier name for the event.
om_platform ios Platform name.
uid 10000001A User identifier supplied by the application.
country_code US ISO 2-letter country code.
om_device iPad 4.1 Device name.
om_discarded 0 Number of events discarded before this event.
om_ios_bundle_identifier com.omniata.sdk iOS Application bundle Identifier.
om_locale es_US Locale information. Custom formats allowed.
om_os_version 7.0.2 OS Version.
om_ios_sysver 9.3.3 iOS System version.
om_sdk_version Server-1.0.1 Omniata SDK Version.
om_ios_sysname iPhone OS iOS System name.
om_ios_model iPhone iOS Model.
om_ios_hardware iPhone 7,2 iOS Hardware.
om_ios_bundle_short_version_string 1.2.3 iOS Application bundle version, short format.
ref_code xmas_promo Reference code that specifies the acquisition source. This is a string that may be defined by the application.
dob 01/02/1993 User’s date of birth.
gender F Gender of the user. Custom formats allowed.
om_ios_bundle_version 123 iOS Application bundle version.
om_package_version_name 4.0.1 Android package version name.
om_package_version_code 20070301 Android package version code.
om_country US ISO 2-letter country code.
om_app_version 401 Application version.
om_unity_sdk_version unitySDK-1.3.4 Unity SDK version.
om_android_device Pixel Android device name.
om_android_hardware qcom Android hardware.
om_android_id ABC123ABC123ABCD Android Id.
om_android_serial PX0000101 Android serial number.

Example request:

$ curl -I "https://{orgname}.analyzer.omniata.com/event?api_key=11111111&uid=10000001A&om_event_type=om_load&om_platform=ios"

om_revenue

In order to have meaningful metrics, this event needs to be sent only for purchases that have been approved via server-side validation. Fake purchases should be excluded or added as a custom events.

Please review the latest integration guidelines from Apple and Google to ensure proper validation.

Parameters:

Name Example Description
api_key 11111111 Key that maps to the application in Omniata.
uid 10000001A User identifier supplied by the application.
om_event_type om_revenue Qualifier name for the event.
om_platform ios Platform name.
om_app_version 401 Application version.
total 2.99 Positive decimal number with up to 4 decimals (with period as the separator), representing the revenue generated by that transaction.
currency_code EUR 3 letter currency code (in all caps). Revenue will be converted to USD according to the current day’s exchange rate.

Example request:

$ curl -I "https://{orgname}.analyzer.omniata.com/event?api_key=11111111&uid=10000001A&om_event_type=om_revenue&total=2.99&currency_code=EUR&om_platform=ios"

om_user

This event can be used whenever the user connects to a social media platform to set extra demographical information. Can be extended to update other user properties defined.

Parameters:

Name Example Description
gender F Gender of the user. Custom formats allowed.
country_code US ISO 2-letter country code.
dob 1985-11-23 The date of birth for the user
api_key 11111111 Key that maps to the application in Omniata.
uid 10000001A User identifier supplied by the application.
om_event_type om_user Qualifier name for the event.
om_platform ios Platform name.
om_app_version 401 Application version.

Example request:

$ curl -I "https://{orgname}.analyzer.omniata.com/event?api_key=11111111&uid=10000001A&om_event_type=om_user&gender=f&dob=1985-11-23&om_platform=ios&country=FR"

om_deghost

Provides support for change of ID from a temporary identifier to a previously used or social media account. The user is flagged in the User State as “ghost” and cannot be undone.

For more details on account deghosting and metrics check the User De-Ghosting guide.

Parameters:

Name Example Description
api_key 11111111 Key that maps to the application in Omniata.
uid 10000001A User identifier supplied by the application. This ID is flagged as “ghost”.
om_event_type om_deghost Qualifier name for the event.
new_uid 10000001B User identifier that replaces the flagged identifier.

Example request:

$ curl -I "https://{orgname}.analyzer.omniata.com/event?api_key=11111111&uid=10000001A&om_event_type=om_deghost&&new_uid=123456789012345"

om_push_sent

This event indicates that a push notification has been sent to the user. The event is internal only, but can be enabled in the Omniata panel.

Parameters:

Name Example Description
api_key 11111111 Key that maps to the application in Omniata.
uid 10000001A User identifier supplied by the application.
om_event_type om_push_sent Qualifier name for the event.
om_silent 1 Flag this event as a non-user event. It prevents to trigger activity for the user.
message_id 123 Message identifier for the content and campaign.
content_id 456 JSON content identifier.
content_name Push iOS 1 Name of the content linked to the message.
experiment_id 11 Unique identifier of the campaign (experiment).
experiment_name Push Engagement 01/2017 Name of the campaign.
campaign_type push Describes if the campaign is for push notifications or display of content.
campaign_start 2017-01-01 Beginning date of the campaign.
experience_id 1 Unique identifier of the experience in the campaign.
experience_name Control Name of the experience.
is_control 1 Indicates if the experience is the control group in the campaign.

om_push_clicked

The Omniata SDK will send this event when the user has received a push notification and has clicked it. The event sending will depend on the online availability of the device. Refer to the Omniata SDK for more information on the configuration of this event.

Parameters:

Name Example Description
api_key 11111111 Key that maps to the application in Omniata.
uid 10000001A User identifier supplied by the application.
om_event_type om_push_clicked Qualifier name for the event.
om_delta 2 Seconds between event creation and event sending.
alert A new day has begun! Here is a gift! Content text of the push notification.

Example request:

$ curl -I "https://{orgname}.analyzer.omniata.com/event?api_key=11111111&uid=10000001A&om_event_type=om_push_clicked&om_delta=2&alert=A+new+day+has+begun%21+Here+is+a+gift%21"

om_apns_enable

Registers a user’s token for receiving push notifications in iOS. For more information on how to integrate push notifications in iOS check Push Notifications setup guide.

Parameters:

Name Example Description
api_key 11111111 Key that maps to the application in Omniata.
uid 10000001A User identifier supplied by the application.
om_event_type om_apns_enable Qualifier name for the event.
om_device_token 123456789ABCDEF1234 Device token for delivering push notifications.

Example request:

$ curl -I "https://{orgname}.analyzer.omniata.com/event?api_key=11111111&uid=10000001A&om_event_type=om_apns_enable&om_device_token=123456789ABCDEF1234"

om_apns_disable

Unregisters a user’s token from receiving push notifications in iOS. For more information on how to integrate push notifications in iOS check Push Notifications setup guide.

Parameters:

Name Example Description
api_key 11111111 Key that maps to the application in Omniata.
uid 10000001A User identifier supplied by the application.
om_event_type om_apns_disable Qualifier name for the event.
om_device_token 123456789ABCDEF1234 Device token to unregister push notifications.

Example request:

$ curl -I "https://{orgname}.analyzer.omniata.com/event?api_key=11111111&uid=10000001A&om_event_type=om_apns_disable&om_device_token=123456789ABCDEF1234"

om_gcm_enable

Registers a user’s device for receiving push notifications in Android. For more information on how to integrate push notifications in Android check Push Notifications setup guide.

Parameters:

Name Example Description
api_key 11111111 Key that maps to the application in Omniata.
uid 10000001A User identifier supplied by the application.
om_event_type om_gcm_enable Qualifier name for the event.
om_registration_id 123456789ABCDEF1234 Device registration identifier for delivering push notifications.

Example request:

$ curl -I "https://{orgname}.analyzer.omniata.com/event?api_key=11111111&uid=10000001A&om_event_type=om_gcm_enable&om_registration_id=123456789ABCDEF1234"

om_gcm_disable

Unregisters a user’s device for receiving push notifications in Android. For more information on how to integrate push notifications in Android check Push Notifications setup guide.

Parameters:

Name Example Description
api_key 11111111 Key that maps to the application in Omniata.
uid 10000001A User identifier supplied by the application.
om_event_type om_gcm_disable Qualifier name for the event.
om_registration_id 123456789ABCDEF1234 Device registration identifier to unregister push notifications.

Example request:

$ curl -I "https://{orgname}.analyzer.omniata.com/event?api_key=11111111&uid=10000001A&om_event_type=om_gcm_disable&om_registration_id=123456789ABCDEF1234"

om_email_enable

Registers a user’s email address for receiving content. For more information on how to integrate automatic email delivery check Email Delivery setup guide.

Parameters:

Name Example Description
api_key 11111111 Key that maps to the application in Omniata.
uid 10000001A User identifier supplied by the application.
om_event_type om_email_enable Qualifier name for the event.
om_device_token some@email.com Email address of the user to send content to.

Example request:

$ curl -I "https://{orgname}.analyzer.omniata.com/event?api_key=11111111&uid=10000001A&om_event_type=om_email_enable&om_device_token=some@email.com"

om_email_disable

Unregisters a user’s email address from receiving content. For more information on how to integrate automatic email delivery check Email Delivery setup guide.

Parameters:

Name Example Description
api_key 11111111 Key that maps to the application in Omniata.
uid 10000001A User identifier supplied by the application.
om_event_type om_email_disable Qualifier name for the event.

Example request:

$ curl -I "https://{orgname}.analyzer.omniata.com/event?api_key=11111111&uid=10000001A&om_event_type=om_email_disable"

om_update_user

This special event will not trigger user’s activity and can be used to update user properties and certain user state elements.

Parameters:

Name Example Description
api_key
mandatory
11111111 Key that maps to the application in Omniata.
uid
mandatory
10000001A User identifier supplied by the application.
om_event_type
mandatory
om_update_user Qualifier name for the event.
usr_src partner none
country BR ISO 2-letter country code the user last accessed the application from.
acq_country US ISO 2-letter country code from which the user accessed the application for the first time.
gender M Gender of the user. Custom formats allowed.
flags 2352 A bit-encoded value for which each position represents a enabled/disabled user flag.
birth_daynum 33686 Date of birth, defined as days since 1900-03-02.
usr_created_at 1487856372 Unix timestamp of the creation date and time of the user.
datestamp 1489968000 Unix timestamp of the creation date of the user.
daynum 42756 Days since 1900-03-02.
first_daynum 42727 First day of activity defined as days since 1900-03-02.
session_count 1 Number of sessions.
session_seconds 35 Cumulative number of seconds the user has been active.
last_session_start 1490026741 Unix timestamp of the last session start date and time of the user.
events 17 Cumulative number of events the user has sent.
last_event_time 1490026741 Unix timestamp of the creation date and time of the user.
revenue 0.99 Total past revenue of the user in USD.
purchases 1 Number of purchases user made.
session_count 5 Number of times user accessed the application.
user_vars[{name}] clan_1 Special parameter that updates User Properties. Can be defined multiple times. The parameter name must include the name of the user property to update.

Example request:

$ curl -I "https://{orgname}.analyzer.omniata.com/event?api_key=11111111&uid=10000001A&om_event_type=om_update_user&gender=F&user_vars[cuf_clan_name]=clan_1"

Custom Event Types

Omniata allows sending custom events using custom parameters and data taxonomy. For example, user progression (e.g. levels) or user completing a video view. Omniata provides complete freedom for defining custom event types and pass any number of additional parameters.

Parameters

Use the following as a quick start template of mandatory parameters to add custom events into your application.

Name Example Description
api_key {api_key} Key that maps to the application in Omniata.
uid {user_id} User identifier supplied by the application.
om_event_type {your_event_name} Qualifier name for the event.
om_platform {platform_name} Platform name.

Example request:

$ curl -I "https://{orgname}.analyzer.omniata.com/event?api_key=11111111&uid=10000001A&om_event_type=game_progress&level=2&stage=19&om_platform=ios&gp_result=win"

This article was last updated on March 29, 2017 17:29. If you didn't find your answer here, search for another article or contact our support to get in touch.