All Collections
Developer documentation and guidance
Consumption analytics API for third-party players (beta)
Consumption analytics API for third-party players (beta)

Integrating consumption analytics reporting for custom web and mobile players

Long Zheng avatar
Written by Long Zheng
Updated over a week ago

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 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.


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.


Please contact if you require assistance.


Send consumption data

Send consumption analytics event data to Omny Studio.




  • OrganizationId The GUID of the Omny Studio organization


  • 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 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 \
  '' \
  -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



  • 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.


    "Enabled": true


Model schema


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?