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 eventProgram
(Program) Metadata about the programNetwork
(Network) Metadata about the network, if the program is assigned to a networkClip
(Clip) Metadata about the clipPlaylist
(Playlist) Metadata about the playlist, if the download is from a playlist RSS feedDownload
(Download) Metadata about the download
Program model
Id
(string) The GUID of the programName
(string) The name of the programExternalId
(string) The external identifier for the programSlug
(string) The URL slug of the program
Network model
Id
(string) The GUID of the networkName
(string) The name of the network
Clip model
Id
(string) The GUID of the clipSlug
(string) The URL slug of the clipTitle
(string) The title of the clipAudioDuration
(string) The duration of the published audio clip in HH:MM:SSAudioDurationSeconds
(number) The duration of the published audio clip in seconds (rounded to milliseconds/3 decimal places)
Playlist model
Id
(string) The GUID of the playlistTitle
(string) The title of the playlistSlug
(string) The URL slug of the playlist
Download model
RawUserAgent
(string) The user agent of the downloadRawDownloadUrl
(string) The URL of the downloadRawReferrerUrl
(string) The URL of the download referrerEmbeddedUrl
(string) If the download is from an embed player, the URL of the parent page which displayed the embedDownloadedAtUtc
(string) The date and time of the download in ISO8601
IpAddress
(string) The IP address of the downloadDevice
(Device) The device of the download, parsed from the user-agent at best effortOS
(OS) The operating system of the download, parsed from the user-agent at best effortUserAgent
(UserAgent) The app or browser of the download, parsed from the user-agent at best effortSource
(string) The source attribution for the download. Inferred sources includePodcast
,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 includeDesktop
,Mobile
,Tablet
,TV
,HiFi
,Unknown
.Brand
(string) The brand of the deviceFamily
(string) The name of the device
OS model
Family
(string) The name of the operating systemMajorVersion
(string) The major version number of the operating system
UserAgent model
Family
(string) The name of the app or browserMajorVersion
(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 nameCountryIsoCode
(string) The two letter ISO code of the countryState
(string) The name of the state or regionCity
(string) The name of the cityPostcode
(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.