Close

APIs

Omniata provides APIs for sending events, requesting content, managing user properties, and integrating with external content management systems.

Event API

Omniata REST API allows to track user-generated events via HTTP. This API allows for building the custom data visualizations, engaging with users, and track user acquisition. The Event API is the same API that is used in the SDK calls.

Definition

The API URL is assigned per organization. When doing Event API integrations, replace 'example' with your organization's assigned subdomain name used in the Omniata panel. The API URL would then be:

https://example.analyzer.omniata.com/event

All Event API calls must include the following mandatory parameters, or they will not be accepted:

Parameter Format Description
api_key String Identifies multiple aspects of the events such as the organization and environment.
uid String Uniquely identifies a user within the organization's UID domain.
om_event_type String Identifies the Event Type, e.g. om_load, om_revenue, om_user.

The Event API response has the (among the standard HTTP response headers), the Cross-Origin Resource Sharing-related header (see https://www.w3.org/TR/cors/):

Access-Control-Allow-Origin: *

Standard Event Types

Omniata has three standard event types:

  • om_load
  • om_revenue
  • om_user (optional)

Tracking these events enables a number of basic reports including metrics such as DAU, ARPU, ARPPU, Conversion Rate, Retention, Session Length, etc.

om_load

The om_load event indicates that a user has loaded the application, or has moved the application from background to foreground. In addition to the mandatory event parameters, the following parameter may be passed in this event.

Note: SDKs pick these parameters up automatically. See the documentation of each of the SDKs for details on how to find out the values for the parameters on each platform.

Parameters

Format

Required

Example

Description

ref_code

String

No

xmas_promo

Reference code that specifies the acquisition source. This is a string that may be defined by the application.

om_device

String

No

iPad4%2C1

The device model

om_platform

String

Yes*

ios

The platform, standard ones are: ios, android, amazon, canvas

om_os_version

String

No

7.0.2

The version of the user's operating system

om_sdk_version

String

No

Server-1.0.1

The version of the server code or SDK

om_device_id

String

No

The device ID

om_bundle_version

String

No 123456789 The version of the game or bundle release

Note: cross-platform support requires om_platform parameter.

Example:

GET https://example.analyzer.omniata.com/event
    ?api_key=ae4398de
    &uid=e439da31f399c23a
    &om_event_type=om_load
    &om_platform=ios

om_revenue

The om_revenue event indicates that the user performed an action that generated real world revenue (In-App Purchase - IAP), and the event specifies the amount of revenue generated and the currency used.

In order to have meaningful metrics, this event needs to be sent only for server-side validated purchases; hacked purchases need to be excluded. Please review the latest integration guidelines from Apple and Google to ensure proper validation.

In addition to the mandatory event parameters, the following parameters must be passed in this event:

Parameters Format Required? Example Description
total float Yes 2.99 Positive decimal number with up to 4 decimals (with period as the separator), representing the revenue generated by that transaction.
currency_code string Yes EUR

3 letter currency code (in all caps). Revenue will be converted to USD according to the current day's exchange rate.

GET https://example.analyzer.omniata.com/event
    ?api_key=ae4398de
    &uid=e439da31f399c23a
    &om_event_type=om_revenue
    &total=2.99
    &currency_code=EUR
    &om_platform=ios

om_user

The optional om_user event is used to explicitly update demographic user attributes.

The following parameters may be passed with this event:

Parameters

Format

Required?

Example

Description

gender

“m”,”f”, or “u”

No

f

The gender of the user. "m" is male, "f" is female, and "u" is unknown.

country_code

2 character country code

No

FR

The country code from where the user is accessing. This overrides the automatic country detection based on IP Address.

dob

YYYY-MM-DD

No

1985-11-23

The date of birth for the user

GET https://example.analyzer.omniata.com/event
    ?api_key=ae4398de
    &uid=e439da31f399c23a
    &om_event_type=om_user
    &gender=f
    &country=FR
    &dob=1985-11-23
    &om_platform=ios

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 passing additional parameters. See below for a generic example.

GET https://example.analyzer.omniata.com/event
    ?api_key=ae4398de
    &uid=e439da31f399c23a
    &om_event_type=YOUR_EVENT_TYPE
    &om_platform=ios
    &your_parameter_1=YOUR_VALUE
    &your_parameter_2=YOUR_VALUE
    ...

Channel API

The Channel API delivers custom content to a specific segment of users at a scheduled time.

Definition

The API URL is assigned per organization. When doing Event API integrations, replace 'example' with your organization's assigned subdomain name used in the Omniata panel. The Channel API URL would then be:

https://example.engager.omniata.com/channel

Mandatory Parameters for Channel API content request are:

Parameter Format Description
api_key String Identifies multiple aspects of the Channel API call such as the organization, environment etc.
uid String Uniquely identifies a user within the organization's UID domain.
channel_id String Identifies the Channel that contains the Content to be delivered (The channel ID can be identified navigating to Engagement > Channels; you can create a new Channel when needed.)

Optional parameters

Parameter Format Description
require_user int

If this parameter is there (require_user=1), the Channel API returns HTTP 404 if the user doesn't exist.

An example: a Channel API request with URL parameters uid=123&channel_id=1&api_key=z&require_user=1. If the user with uid 123 doesn't have a state (i.e. the user never has sent an event to the Event API, or that the Event API hasn't yet processed the event), Channel API returns HTTP 404 and no content. If the state is there, the parameter has no effect.

Note: In order to successfully enable Channel API with user segmentation in Omniata, the incoming data stream of events must use the real-time Event API.

Example:

GET https://example.engager.omniata.com/channel
    ?api_key=ae4398de
    &uid=e439da31f399c23a
    &channel_id=123

This will return a standard JSON response.

{ "content": [{...}, {...}, {...}] }

The first level container node is standard, whereas the user-defined content is included in the [ ] elements and represented by the {...}. Any type of valid JSON can be included, for more examples and details can be found in the Content section.

User State API

In cases where the User State needs to be created or altered without directly using tracking events, the User State API can be used. This API allows creating new users as well as retrieving and updating User State and User Variables of existing users. The Omniata User State API is HTTP based, and RPC-like (Remote Procedure Call), in that it makes use of HTTP primitives:

  • POST to cause user state to be created
  • PUT to cause the state to be updated
  • GET to retrieve the current state

The primitives that create or modify state do not directly change the state of a user, but rather generate an event that causes the event processing engine to perform the operation. This API provides a means for clients to inject these state creating/altering events permanently into the event stream.

The state of a user is accessible by providing values for the uid and api_key fields. These are all that are required to reference a unique user state. The user state itself is divided into five groups information:

group field name values
user_group gender (m|f|u) [male,female,undefined]
user_group birthdate yyyy-mm-dd
acquisition_group acquisition_source <string>
acquisition_group acquisition_country_code <cc> [ISO 3166-1, two byte code]
activity_group activity_date yyyy-mm-dd
activity_group last_activity_date yyyy-mm-dd
activity_group first_activity_date yyyy-mm-dd
activity_group session_bitmap <bigint>
activity_group access_source <string>
activity_group access_country_code <cc> [ISO 3166-1, two byte code]
activity_group session_count <integer>
activity_group delta_session_count <integer>
activity_group session_seconds <integer>
activity_group delta_session_seconds <integer>
activity_group last_session_start yyyy-mm-dd HH:MM:SS
activity_group events <integer>
activity_group delta_events <integer>
activity_group last_event_time yyyy-mm-dd HH:MM:SS
revenue_group revenue <integer>
revenue_group delta_revenue <integer>
revenue_group purchases <integer>
revenue_group delta_purchases <integer>
revenue_group purchase_bitmap <bigint>
user_vars_group any custom user vars created for an user

There is a number of attributes, such as daynum, birth_daynum, spender_tier and age_tier, which are derived from the values of other attributes.

Creating User

To create a user, issue a POST to the user state API using the domain of your organization ('example' in the following example), specifying the desired values for uid and api_key for the new user.

POST /user HTTP/1.1
Host: EXAMPLE.engager.omniata.com:8080
Content-Type: application/x-www-form-urlencoded
Content-Length: 25
uid=1234&api_key=4312e3fa

The example above will initialize a new, inactive user. It is also possible to include src_uid and src_api_key parameters:

POST /user HTTP/1.1
Host: EXAMPLE.engager.omniata.com:8080
Content-Type: application/x-www-form-urlencoded
Content-Length: 62
uid=1234&api_key=4312e3fa&src_uid=7891234&src_api_key=e343ac41

This will create a new user, but initialize the state according to that of an existing user. By default, all groups are copied from the original user. However, with some restrictions, it is possible to exclude some groups, and leave the information uninitialized, by specifying a list of the groups to be excluded with the 'exclude' parameter. The value specified for the 'exclude' parameter is a comma separated list that may contain one or more of the following strings:

  • user_group
  • acquisition_group
  • activity_group
  • revenue_group
  • user_vars_group
POST /user HTTP/1.1
Host: EXAMPLE.engager.omniata.com:8080
Content-Type: application/x-www-form-urlencoded
Content-Length: 100
uid=1234&api_key=4312e3fa&src_uid=7891234&src_api_key=e343ac41&exclude=user_vars_group,revenue_group

This will create a new user that is initialized with the same user_group, acquisition_group, and activity_group as the source user, but will have uninitialized revenue and user_vars groups. Please note that excluding 'activity_group' will also cause 'revenue_group' to be excluded.

For the user_vars_group only, it is also possible to specify only the list of user_vars to be included in the copy.

POST /user HTTP/1.1
Host: EXAMPLE.engager.omniata.com:8080
Content-Type: application/x-www-form-urlencoded
Content-Length: 106
uid=1234&api_key=4312e3fa&src_uid=7891234&src_api_key=e343ac41&exclude=revenue_group&user_vars=xxx,yyy,zzz

This will cause revenue_group to be excluded, and all the user_vars to be excluded *except* xxx, yyy and zzz. Specifying exclude=user_vars_group *and* a list of user_vars, would cause only the specified list of user vars to be excluded. All others would be included.

POST /user HTTP/1.1
Host: EXAMPLE.engager.omniata.com:8080
Content-Type: application/x-www-form-urlencoded
Content-Length: 104
uid=1234&api_key=4312e3fa&src_uid=7891234&src_api_key=e343ac41&exclude=user_vars_group&user_vars=aaa,bbb

Updating User

To update the User State, use the PUT primitive. Only user_group and acquisition_group can be updated. Also elements of acquisition_group can only be updated if they are undefined.

PUT /user HTTP/1.1
Host: EXAMPLE.engager.omniata.com:8080
Content-Type: application/x-www-form-urlencoded
Content-Length: 99
uid=1234&api_key=4312e3fa&acquisition_source=213432-4332123-43212-33333&acquisition_country_code=JP

To update User Vars, specify their names and values in the following manner:

PUT /user HTTP/1.1
Host: EXAMPLE.engager.omniata.com:8080
Content-Type: application/x-www-form-urlencoded
Content-Length: 68
uid=1234&api_key=4312e3fa&user_vars[xxx]=newvalue&user_vars[yyy]=zzz

HTTP Response codes are used to indicate the success or failure of a request:

  • 200 OK - The request completed
  • 400 Bad Request - The request could not be completed (for example, an invalid API key was specified), or a request was made to create a user that already exists.

Delivery API

The Delivery API is useful when users have registered to receive email or push notifications. This API allows you to send the desired content to the user as per your use case through Omniata's Engagement tools.

In the following example we use 1234 as the User ID and as example Content ID we use 5.

Setup

In the examples, we are using URLs that have "example" as subdomain in them. Please replace "example" with your subdomain.

  1. You will need your SendGrid credentials added to your applications delivery credentials settings page. Please contact Omniata for this to be enabled for you.
  2. You will need to create content types for your content https://example.panel.omniata.com/123-data-model/content_types
  3. You will need to create content for delivery https://example.panel.omniata.com/123-data-model/content

Delivery Management

After following the steps mentioned above, please make sure to send the following event to be able to register your user to receive emails or push notifications:

Email:

Send 'om_emaiLenable' events to register the users as eligible to receive an email, and send email 'om_email_disable' to remove their eligibility.

  • Example of 'om_email_enable'
    • api_key=a1b2c3d4&uid=123abc&om_event_type=om_email_enable&om_device_token=joe.user@gmail.com
  • Example of 'om_email_disable'
    • api_key=a1b2c3d4&uid=123abc&om_event_type=om_email_disable

Push Notifications:

To setup users for receiving push notifications, please click here to go through the list of steps required to be configured https://www.omniata.com/guide/push-notifications-email

Delivery Testing

Once users are registered to receive emails and push notifications, Content ID can be retreived as shown below:

https://example.panel.omniata.com/deliver?api_key=a1b2c3d4&content_id=5&uid=123abc

To locate your Content ID, click on the content name listed on this page: https://example.panel.omniata.com/data_models/content/

The URL in your address bar will look like: https://example.panel.omniata.com/data_models/content/5-test-content
(the 5 in content name '5-test-content' is the Content ID)

Depending on the type of content, email or push notification will be sent to the user.

Content API

The Content API is useful when there is an existing content management system in-house that can be integrated with Omniata's Engagement tools. This approach is most effective when the campaigns have a significant amount of different types of content.

In the examples below we use curl on the command line. In the following example we use 123 as the Data Model ID and as example Channel ID we use 12.

Setup

In the examples, we are using URLs that have "example" as subdomain in them. Please replace "example" with your subdomain.

  1. You will need your authorization token in your account settings page found at https://example.panel.omniata.com/users/edit. The token is a 20 digits hash, you can regenerate your token at any time.
  2. You will need to create content types for your content https://example.panel.omniata.com/123-data-model/content_types

Content Management

Replace YOUR_API_KEY_IN_ACCOUNT_SETTINGS with your authorization token. In the examples below we use 123 as the <Data Model ID>, in your organization the Data App ID will be followed by its name.

Listing Content

curl -v -i -H 'Authorization: Token token="YOUR_API_KEY_IN_ACCOUNT_SETTINGS"' 
   -X GET 
   https://example.panel.omniata.com/data_models/123/content.json

Creating Content

The Content Type machine names can be found in the Content Types menu of your Engagement dashboard. To create content you issue a POST HTTP request to https://example.panel.omniata.com/data_models/<Data Model ID>/content.json with Content fields, see example below.

curl -v -i -H 'Authorization: Token token="YOUR_TOKEN_HERE"'
   -X POST
   -d "content[name]=foo"
   -d "content[tag_list]=tag1,tag2"
   -d "content[content_type_machine_name]=test"
   -d 'content[json]={"hello": "world"}'
   https://example.panel.omniata.com/data_models/123/content.json

The key field uniquely identifies content within your organization e.g. example_announce_blog_123. You can reference this key when performing updates and deletions.

If you do not wish to use the key field, we can generate one for you, and simply use the returned Content's ID to perform updates/deletions.

Updating Content

Submit a PUT HTTP request to https://example.panel.omniata.com/data_models/<Data Model ID>/content/<Content ID>.json with your updated content fields. For example, if the last Content created retuned an ID = 99, you would update its name with the example below.

curl -v -i -H 'Authorization: Token token="YOUR_API_KEY_IN_ACCOUNT_SETTINGS"'
   -X PUT 
   -d "content[name]=foo2" 
   https://example.panel.omniata.com/data_models/123/content/99.json

Deleting Content

Submit a DELETE HTTP request to https://example.panel.omniata.com/data_models/<Data Model ID>/content/<Content ID>.json, for example:

curl -v -i -H 'Authorization: Token token="YOUR_API_KEY_IN_ACCOUNT_SETTINGS"' 
   -X DELETE
   https://example.panel.omniata.com/data_models/123/content/99.json

Channel Message Management

Replace YOUR_API_KEY_IN_ACCOUNT_SETTINGS with your authorization token. In the examples below we use 123 as the Data Model and 12 as the channel, in your organization the Data Model ID will be followed by its name, similarly for the the channel. You can use the full ID and name or just the ID.

Listing Channel Messages

This command can be used to obtain the Channel Message ID that uniquely identifies each message.

curl -v -i -H 'Authorization: Token token="YOUR_API_KEY_IN_ACCOUNT_SETTINGS"' 
   -X GET
   https://example.panel.omniata.com/data_models/123/display_channels/12/channel_messages.json

Disabling Channel Messages

curl -v -i -H 'Authorization: Token token="YOUR_API_KEY_IN_ACCOUNT_SETTINGS"'
   -X POST
   -d "bulk_operation[operation]=disable"
   -d "bulk_operation[channel_message_ids][]=123"
   -d "bulk_operation[channel_message_ids][]=456"
   https://example.panel.omniata.com/data_models/123/display_channels/12/channel_messages/bulk_operation_confirmed.json

Enabling Channel Messages

curl -v -i -H 'Authorization: Token token="YOUR_API_KEY_IN_ACCOUNT_SETTINGS"'
   -X POST
   -d "bulk_operation[operation]=enable"
   -d "bulk_operation[channel_message_ids][]=123"
   -d "bulk_operation[channel_message_ids][]=456"
   https://example.panel.omniata.com/data_models/123/display_channels/12/channel_messages/bulk_operation_confirmed.json

Deleting Channel Messages

curl -v -i -H 'Authorization: Token token="YOUR_API_KEY_IN_ACCOUNT_SETTINGS"' 
   -X POST 
   -d "bulk_operation[operation]=delete" 
   -d "bulk_operation[channel_message_ids][]=123" 
   -d "bulk_operation[channel_message_ids][]=456" 
   https://example.panel.omniata.com/data_models/123/display_channels/12/channel_messages/bulk_operation_confirmed.json

Publishing Channel Messages

curl -v -i -H 'Authorization: Token token="YOUR_API_KEY_IN_ACCOUNT_SETTINGS"' 
  -X POST 
  -d "channel_message[content_ids][]=574" 
  -d "channel_message[content_ids][]=745" 
  -d "channel_message[enabled]=1" 
  -d "channel_message[includes_target_ids][]=55" 
  -d "channel_message[excludes_target_ids][]=56" 
  -d "channel_message[enable_scheduling]=1" 
  -d "channel_message[from]=2015-01-01" 
  -d "channel_message[to]=2015-01-15" 
  https://example.panel.omniata.com/data_models/123/display_channels/12/channel_messages.json

Scheduling is in UTC. The includes_target_ids qualifiers are the segment_id given by.

https://example.panel.omniata.com/data_models/123/segments.json

This article was last updated on April 14, 2016 12:24. If you didn't find your answer here, search for another article or contact our support to get in touch.

Contact Sales

Add Phone Number