Analytics data export

Analyze and extract insights from individual download events data

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

In addition to the aggregated analytics available from within the Omny Studio interface, we offer an optional add-on that logs and exports all individual download events to a customer's cloud storage system.

Analyzing individual download events provides the flexibility to extract insights by correlating analytics from other sources such as websites or mobile apps, as well as pivoting and filtering data on attributes not possible within the dashboard such finding which episodes are popular in a specific city, downloads by episode duration or all downloads by an IP address.

---

Download event data

Download events includes the following properties:

  • EventId  (string) An unique identifier for the download event

  • Program  (Program) Metadata about the program

  • Network  (Network) Metadata about the network, if the program is assigned to a network

  • Clip (Clip) Metadata about the clip

  • Playlist  (Playlist) Metadata about the playlist, if the download is from a playlist RSS feed

  • Download  (Download) Metadata about the download

Program model

  • Id  (string) The GUID of the program

  • Name (string) The name of the program

  • ExternalId  (string) The external identifier for the program

  • Slug  (string) The URL slug of the program

Network model

  • Id (string) The GUID of the network

  • Name (string) The name of the network

Clip model

  • Id (string) The GUID of the clip

  • Slug (string) The URL slug of the clip

  • Title (string) The title of the clip

  • AudioDuration (string) The duration of the published audio clip in HH:MM:SS

  • AudioDurationSeconds (number) The duration of the published audio clip in seconds (rounded to milliseconds/3 decimal places)

Playlist model

  • Id (string) The GUID of the playlist

  • Title (string) The title of the playlist

  • Slug (string) The URL slug of the playlist

Download model

  • RawUserAgent (string) The user agent of the download

  • RawDownloadUrl (string) The URL of the download

  • RawReferrerUrl (string) The URL of the download referrer

  • EmbeddedUrl (string) If the download is from an embed player, the URL of the parent page which displayed the embed

  • DownloadedAtUtc (string) The date and time of the download in ISO8601

  • IpAddress (string) The IP address of the download

  • Device (Device) The device of the download, parsed from the user-agent at best effort

  • OS (OS) The operating system of the download, parsed from the user-agent at best effort

  • UserAgent (UserAgent) The app or browser of the download, parsed from the user-agent at best effort

  • Source (string) The source attribution for the download. Inferred sources include Podcast , Embed , OmnyFM , Twitter , MobileApp , GooglePodcastsWeb , ApplePodcastsWeb, CustomPlayer1, CustomPlayer2, CustomPlayer3, CustomPlayer4, CustomPlayer5

  • MemberId (string) ID of the restricted access member for the download

Download model

  • Geo (Geo) Optionally with additional fees. The location of the download, estimated from the IP address

Device model

  • Type (string) The type of device. Detected types include Desktop , Mobile , Tablet , TV , HiFi , Unknown.

  • Brand (string) The brand of the device

  • Family (string) The name of the device

OS model

  • Family (string) The name of the operating system

  • MajorVersion (string) The major version number of the operating system

UserAgent model

  • Family (string) The name of the app or browser

  • MajorVersion (string) The major version number of the app or browser

Geo model (Optionally with additional fees)

Please note that this data is NOT included in the 'basic' analytics data export.

  • Country (string) The country name

  • CountryIsoCode (string) The two letter ISO code of the country

  • State (string) The name of the state or region

  • City (string) The name of the city

  • Postcode (string) The post code

Example of a download event JSON

{
    "EventId": "46fa9c3a-1bd6-4c7f-9b50-107b20d7faa1",
    "Program": {
        "Id": "27aa1c43-82bf-4b8a-9e78-a93b002c0a85",
        "Name": "Morbi leo risus",
        "Slug": "morbi-leo-risus"
    },
    "Network": {
        "Id": "bc8305f4-52e8-4df5-a7b7-3937939adb2d",
        "Name": "Dolore magna aliqua",
    }
    "Clip": {
        "Id": "67cc2dc9-6709-48e1-8d6b-a9fa007b32e7",
        "Slug": "etiam-porta",
        "Title": "Etiam porta sem malesuada magna mollis euismod.",
        "AudioDuration": "01:25:05.2510000",
        "AudioDurationSeconds": 5105.251
    },
    "Download": {
        "RawUserAgent": "AppleCoreMedia/1.0.0.15A402 (iPhone; U; CPU OS 11_0_1 like Mac OS X; en_au)",
        "RawDownloadUrl": "https://omnystudio.com:443/d/clips/.../audio.mp3?utm_source=Embed...",
        "RawReferrerUrl": null,
        "EmbeddedUrl": null,
        "DownloadedAtUtc": "2019-03-18T00:52:01Z",
        "Device": {
            "Type": "Mobile",
            "Brand": "Apple",
            "Family": "iPhone"
        },
        "OS": {
            "Family": "iOS",
            "MajorVersion": "11"
        },
        "UserAgent": {
            "Family": "Apple Core Media",
            "MajorVersion": "1"
        },
        "Source": "Podcast"
    }
}

Implementation notes for developers

Consumers of the analytics export feed should be conscious of the following implementation details.

Best-effort delivery

The data export is provided as a best-effort service with at least once delivery. 

Use the EventId property to de-duplicate the chance of repeated events

Download events may be duplicated within a 24-hour window due to intermittent errors and we recommend verifying event uniqueness using the EventId unique identifier.

No historical export available

Data is only available from the time the feature is enabled for the organization. Historical data is not available through this feature.

Timing of delivery of download events relative to exported files

Download events that are exported can also be delayed by up to 24 hours from when they have occurred.

For example, if a download occurs on the 10th of the month, the download event may be written into an exported file that has the date of the 11th of the month. The event's DownloadedAtUtc will still reflect the download time on the 10th, however.

This can occur as part of our download filtering techniques requiring CDN log data that may be delayed, or because the listener did not download a sufficient amount of the episode until later in the day to be considered a verified download.

Event export file format

Download events are batch exported to the specified cloud storage server at a regular interval as gzipped JSON Lines files.

The files are written using the following folder convention:

{year}/{year}-{month}/{year}-{month}-{day}

e.g. /2019/2019-03/2019-03-18 

The files are written using the following filename convention:

{year}-{month}-{day}T{hour}{minute}_{time of first event}_{unique identifier}.jsonl.gz

e.g. 2019-03-18T0052_005201.941_81b9bcac-f6b0-4bd8-b191-4af7b89a985c.jsonl.gz 

We currently support the following cloud storage systems:

  • Microsoft Azure Blob Storage

  • Amazon S3

If you require data exported to a different storage system, please contact us.

S3 export

For an S3 export, we need the following details:

  • Bucket name

  • Region

  • Access key

  • Secret key
    ​

The secret key should be considered sensitive data. Please use a service such as onetimesecret.com to transmit the secret key.

Did this answer your question?