The Podlove Publisher tracks download intents made by clients. It is only tracked that a download was started but not if it was completed. For brevity, this document will speak of “downloads”. Just be aware that what is tracked are actually only download intents. So when you are looking at your data, be aware that the numbers displayed do not represent the actual number of listening users.

Anatomy of Tracking URLs

The Publisher creates “tracking URLs”. For example, if your media file is this:

media.example.com/podcast/pod001.m4a

then a tracking URL might look like that:

example.com/podlove/file/646/s/feed/c/m4a/pod001.m4a

Requests on tracking URLs are intercepted by the Publisher, analyzed, and finally redirected to the actual physical file. On to a closer look at the URL components.

example.com/podlove/file/646/s/feed/c/m4a/pod001.m4a

This is your blog domain and a “podlove” URL prefix so tracking URLs don’t interfere with your blogs pages.

example.com/podlove/file/646/s/feed/c/m4a/pod001.m4a

This identifies the actual file to download.

example.com/podlove/file/646/s/feed/c/m4a/pod001.m4a

These are indicators for the source (s) and context (c) of the Download. This allows you to have separate analytics for downloads from feeds, the web player, etc.

example.com/podlove/file/646/s/feed/c/m4a/pod001.m4a

What looks like the file name is purely of decorative nature. It makes the URL easier to read and some command line clients will use that part of the URL to auto-generate a filename. But it is irrelevant for the purpose of tracking.

Tracking Data

Only real download requests are tracked. In more technical terms: HEAD requests are ignored. These are the analyzed and saved values:

UA (User Agent)

Based on the UA, facts about the client can be derived or guessed; such as:

  • client name (Chrome, Firefox, iTunes, Instacast, …)
  • operating system (Android, iOS, Mac, …)
  • device (iPhone, Galaxy Nexus, …)

Furthermore, bots can be detected.

File ID

A reference to the downloaded file is kept. This allows to group tracking data by episode.

Request ID

The request ID is an artificial compound ID to identify identical requests anonymously. It is a hash from the combined IP address and user agent string.

Source & Context

Download source & context allows to analyze tracking data by how and where the file was requested. By default, the sources are:

  • download: a direct download via the website
  • feed: an automatic download via RSS feeds
  • webplayer: the episode was played using the player on the website

To further drill down, each source has multiple contexts:

  • download
    • select-button: a direct download by clicking a download button
    • select-show: the user obtained the URL by revealing it on the website
  • for feed, the asset is saved (m4a, mp3, ogg, etc.)
  • webplayer
    • episode: the player on the episode page
    • home: the player on the home page
    • website: the player on any other page

Geo Location

Based on the IP address and the GeoLite2 Database by MaxMind location data is saved.

Data Cleanup

Before tracking data is presented in the analytics area, it is cleaned up. Cleanup involves the following steps:

  • Based on the UA analysis bots are filtered out.
  • Duplicate requests are filtered out. A request is considered a duplicate if it contains
    • the same File ID
    • and the same Request ID
    • and was made within the same hour
  • Pre-Release downloads are filtered out. They may happen if you test downloads before publishing the episode.

Database Structure

If you would like to access the raw analytics data and process it yourself, you need to know where what data is and what it means.

wp_podlove_downloadintent

You probably want to use wp_podlove_downloadintentclean instead. This table contains every tracked request. Columns are nearly identical to wp_podlove_downloadintentclean.

wp_podlove_downloadintentclean

This table contains cleaned data from wp_podlove_downloadintent. See section “Data Cleanup” for detail on how data is cleaned/aggregated. Each row represents one download. If you count the rows in this table you have the total number of downloads.

Column Description
id Unique, auto-incrementing integer id
user_agent_id reference to id in wp_podlove_useragent
media_file_id reference to id in wp_podlove_mediafile
request_id Artificial compound ID to identify identical requests anonymously. It is a hash from the combined IP address and user agent string.
accessed_at Date and time of the download
source One of “download”, “feed”, “webplayer”. Specifies how the download was initiated.
context A more specific description for the source column.
geo_area_id reference to id in wp_podlove_geoarea
lat Location: latitude
lng Location: longitude
httprange HTTP “Range” header of the request, which may specify which bytes exactly were requested.
hours_since_release Amount of hours between episode release and download. May be useful for aggregation.

wp_podlove_mediafile

This table holds metadata for each file, like the file size. It holds references to the episode and asset.

Column Description
id Unique, auto-incrementing integer id
episode_id reference to id in wp_podlove_episode
episode_asset_id reference to id in wp_podlove_episodeasset
size file size in bytes. -1 or NULL if unknown.
etag etag used in HTTP requests

wp_podlove_episodeasset

This table holds metadata for assets. It is useful if you want to display asset names or need the reference to the file type.

Column Description
id Unique, auto-incrementing integer id
title Asset title
identifier Asset identifier for use in templates
file_type_id reference to id in wp_podlove_filetype
suffix Used for constructing download URLs
downloadable 1 if it appears in download dialogues, 0 otherwise.
position integer used for ordering

wp_podlove_filetype

This table holds metadata for the file type associated to an asset. It is useful if you need to display the file extension or filter all downloads by type == audio.

Column Description
id Unique, auto-incrementing integer id
name Filetype name
type One of “audio”, “video”, “ebook”, “image”, “chapters”, “metadata”, “transcript”
mime_type Mime Type
extension File extension

wp_podlove_episode

This table holds metadata for the episode. It is complemented by data in the WordPress-native table wp_posts, which you will need to access the episode title for example.

Column Description
id Unique, auto-incrementing integer id
post_id reference to id in wp_posts
subtitle Episode subtitle
summary Episode summary / description