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 a local buffered queue.

Events must only be flushed when the session is complete and no additional events 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).

We recommend a persisted local storage to store the buffered queue so even if the browser or app was closed unexpectedly, the events can be persisted and flushed at the next available opportunity.

Batching

To help reduce network usage on the API endpoint, multiple completed sessions can be sent in one API request.

Testing

Upon submitting completed sessions, it will take up to 10 minutes for the results to appear in the Omny Studio portal. You should test playback sessions up to 5-10 minutes in listen duration also appear correctly in the portal.

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  should 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. (Schema defined 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.
Did this answer your question?