Third-party developers and publishers integrate can enable consumption analytics for a custom web or mobile player using the consumption analytics API.
The Omny Studio Consumption Analytics API is a beta feature
Omny Studio’s consumption analytics allows publishers to see a visualization of how their listeners are consuming and interacting with their audio content. By default, consumption analytics is available on plays through the Omny.fm web player and embeddable player.
Using the consumption analytics API, the player sends playback events which are parsed, filtered and processed by our analytics services to generated aggregated consumption analytic reports.
The raw event data is parsed, filtered and processed by our analytics services to generate aggregated consumption analytic reports.
Client Implementation
During playback of a clip, the player should emit the following events to local memory/queue.
Events must only be flushed/sent to the server when the session is complete and no additional events for the session are possible. Example: the listener ended playback of the clip, changed episodes, or closed the app, but not when the user has just paused playback because they may resume the session in the future.
For browsers, we recommend using Navigator.sendBeacon() to send events on page unload. For apps, we recommend a persisted local storage to store the events queue so even if the app was closed unexpectedly, the events can be persisted and flushed at the next available opportunity.
Batching (Optional)
To reduce network usage on the API endpoint, you may optionally send multiple completed sessions in one API request as long as each SessionId is guaranteed to be unique.
Testing
Upon submitting completed sessions, it takes up to 10 minutes for the results to appear in the Omny Studio portal. Sessions totaling less than 10 seconds in duration are filtered from consumption analytics.
Send Consumption Data
Send consumption analytics event data to Omny Studio.
Request
POST https://traffic.omny.fm/api/consumption/events?organizationId={organizationId}Parameters:
OrganizationIdThe GUID of the Omny Studio organization
Headers:
Content-Typemust beapplication/json
Body (JSON):
Source(string) The source of where this consumption information was recorded. This allows separating different consumption from different types of sources or apps in the UI. The following sources are available for custom implementations:
MobileAppfor custom mobile apps
SmartSpeakerfor custom smart speaker apps
CustomWebfor custom web players
Customfor all other custom appsBy default the Omny embed player and Omny.fm website uses the
Websource
Events(TrackConsumptionEvent[]) An array of consumption events being submitted. Must have at least one event included. SeeTrackConsumptionEventmodel below.Completed(boolean) If the session has completed. Must betrue
cURL Example
curl -X POST \
'https://traffic.omny.fm/api/consumption/events?organizationId=126281f8-200e-4c9f-8378-a4870055423b' \
-H 'Content-Type: application/json' \
-d '{
"Source": "Web",
"Events": [
{
"OrganizationId": "126281f8-200e-4c9f-8378-a4870055423b",
"ClipId": "9b5c82f7-74cf-4841-a870-a670017cc8eb",
"SessionId": "a039f83d-1916-436b-a090-efbc08698506",
"Type": "Start",
"Position": 0,
"SeqNumber": 1,
"Timestamp": 1540270724
},
{
"OrganizationId": "126281f8-200e-4c9f-8378-a4870055423b",
"ClipId": "9b5c82f7-74cf-4841-a870-a670017cc8eb",
"SessionId": "a039f83d-1916-436b-a090-efbc08698506",
"Type": "Stop",
"Position": 4.554,
"SeqNumber": 2,
"Timestamp": 1540270728
},
{
"OrganizationId": "126281f8-200e-4c9f-8378-a4870055423b",
"ClipId": "9b5c82f7-74cf-4841-a870-a670017cc8eb",
"SessionId": "a039f83d-1916-436b-a090-efbc08698506",
"Type": "Start",
"Position": 308.053,
"SeqNumber": 3,
"Timestamp": 1540270728
},
{
"OrganizationId": "126281f8-200e-4c9f-8378-a4870055423b",
"ClipId": "9b5c82f7-74cf-4841-a870-a670017cc8eb",
"SessionId": "a039f83d-1916-436b-a090-efbc08698506",
"Type": "Stop",
"Position": 542.643,
"SeqNumber": 4,
"Timestamp": 1540270962
}
],
"Completed": true
}'Response
Model
Enabled(boolean) Whether Consumption Analytics service is enabled or not. If the response is false, the client should stop attempting to submit events for the web page/mobile app session.
Example:
{
"Enabled": true
}TrackConsumptionEvent Model Schema
A consumption analytics event object:
OrganizationId(string) The GUID of the clip’s organizationClipId(string) The GUID of the clipSessionId(string) Client-side generated, globally unique ID (GUID/UUID) that identifies the same listen session for an individual clip.
A session is considered a single continuous play. Changing clips is considered a new session (for example switching between clips A, B, A in a playlist should generate 3 unique sessions). The SessionId should not be reused for other sessions.Type(string) The type of event emitted. Valid types are:
StartPlayback has started at the current position
StopPlayback has stopped at the current position
Position(number) Time of the listen position in fractional seconds, such as 1.5 which represents 1,500 milliseconds along the audio timeline.SeqNumber(number) A sequence number starting from1that must be incremented for each new event in the Session. This is used to resolve race condition issues with programmatically generated events that occur very quickly one after another that may have the same timestamp.Timestamp(number) A unix timestamp (in seconds) representing the moment this event was emitted. E.g.1502072310It is important that the timestamp reflect the actual event emit time, and not when the event is being flushed to the API.