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.

Third-party developers and publishers can also enable consumption analytics for a custom web or mobile player using the consumption analytics API.

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 (e.g. 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 memory/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 will take up to 10 minutes for the results to appear in the Omny Studio portal. Note sessions totalling less than 10 seconds in duration are filtered from consumption analytics.

Support

Please contact support@omnystudio.com if you require assistance.

---

Send consumption data

Send consumption analytics event data to Omny Studio.

Request

POST https://traffic.omny.fm/api/consumption/events?organizationId={organizationId}

Parameters

OrganizationId The GUID of the Omny Studio organization

Headers

Content-Type must be application/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:
MobileApp recommended for custom mobile apps
SmartSpeaker recommended for custom smart speaker apps
CustomWeb recommended for custom web players
Custom recommended for all other custom apps
(By default the Omny embed player and Omny.fm website uses the Web source)
Events (TrackConsumptionEvent[]) An array of consumption events being submitted. Must have at least one event included. (See TrackConsumptionEvent model below)
Completed (boolean) If the session has completed. Must be true

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
}

---

Model schema

TrackConsumptionEvent

A consumption analytics event object

OrganizationId (string) The GUID of the clip’s organization
ClipId (string) The GUID of the clip
SessionId (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:
Start Playback has started at the current position
Stop Playback 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 from 1 that 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. 1502072310 It is important that the timestamp reflect the actual event emit time, and not when the event is being flushed to the API.