Metrics and Dimensions

Read definitions of each metric and dimension returned in an Analytics API query response.


📘

  • Premium metrics and dimensions denoted in the following tables require a JWP Enterprise license.
  • Be mindful of the Data Availability when making queries.

This reference details each available metric and dimension across JWP's analytics offerings.

The following tables use the following icons.

IconDescription
Product offering supports the metric or dimension
Product offering does not support the metric or dimension
ℹ️Dimension or metric requires an SQL query or calculation
$Premium dimension or metric that requires a JWP Enterprise license
OTTDimension or metric is included in an OTT play session.
WEBDimension or metric is included in a web play session.


Metrics

A metric is a quantitative measurement. The following sections list the metrics that we currently offer.

Ads

Name
(NOTES)
API ID Description API Custom Reports Data Sharing
Ad Clicks
($, WEB)
ad_clicks integer Number of times a video ad was clicked in an embedded player
Ad Completes
($, WEB)
ad_completes integer Number of times a video ad was completed in an embedded player
Ad Skips
($, WEB)
ad_skips integer Number of times a video ad was skipped in an embedded player

Engagement

Name
(NOTES)
API ID Description API Custom Reports Data Sharing
25% Completes
(WEB)
25_percent_completes integer Number of times viewers watched to the 25% mark of a media item

This metric is only available for media items over 30 seconds.
50% Completes
(WEB)
50_percent_completes integer Number of times viewers watched to the 50% mark of a media item

This metrics is only available for media items over 30 seconds.
75% Completes
(WEB)
75_percent_completes integer Number of times viewers watched to the 75% mark of a media item

This metrics is only available for media items over 30 seconds.
Adjusted Complete Rate
(WEB)
adjusted_complete_rate percent Adjusted completes per play

This metric is only available through the API.
Adjusted Completes
(WEB)
adjusted_completes integer Used to calculate the Content Score, number of times a viewer watched at least 75% the total duration of a media item

This metric is only available through the API.
Complete Rate
(OTT, WEB)
complete_rate percent Ratio of completes divided by plays

This metric provides insight into how often users watch the end of a media item after starting it.
Content Score
($, WEB)
content_score integer Average of the play rate and complete rate

This metric is only available through the API.
Video Seeks
(WEB)
video_seeks integer Total number of times the user used the seek functionality of the player during this play session
Video Shares
(WEB)
video_shares integer Total number of times a viewer has clicked an option to share to social media
Watched Duration Viewable
(WEB)
watched_duration_viewable integer Total viewable watched duration for this session in seconds

In this instance, viewable means that 50% of the video pixels are in the viewport of the active tab.

Performance

Name
(NOTES)
API ID Description API Custom Reports Data Sharing
Ad Impressions
(OTT, WEB)
ad_impressions integer Number of ad starts across all embedded players
Ad Viewability Rate
(WEB)
ad_viewability_rate integer Number of viewable ad impressions divided by the number of total ad impressions

This provides insight into how many ads are viewable of all ads served.
Ad Viewable Impressions
(WEB)
ad_viewable_impressions integer Total number of viewable ad impressions in this session, as defined by the IAB (a viewer has watched an ad for 2 consecutive seconds with at least 50% of the pixels in the viewport)

The following are required to properly receive metrics:
  • Player version 8.5+
  • Ad schedule ID
Completes
(OTT, WEB)
completes integer Number of times a viewer watched the end of a media item
Count Playback Stalls
(WEB)
count_playback_stalls integer Number of times the player buffers for this play session
Embeds
(WEB)
embeds integer Number of times a player has been set up on a page

The following behaviors can log an embed:
  • Loading or refreshing a page with an embedded
  • Resetting an embedded player without refreshing the page
First Frame
(WEB)
first_frame integer Time in milliseconds (ms) until first frame is displayed
Play Rate
($, WEB)
play_rate percent Plays per embeds

Only the first play (based on the firstFrame event) for a given embed is counted.
Plays
(OTT, WEB)
plays integer Number of media item starts

The player does not have to be visible for this event to fire. This is based on the firstFrame player event.
Setup Duration
WEB)
setup_duration integer Time in milliseconds (ms) for the player to set up
Time Watched
(OTT, WEB)
time_watched integer Total duration of media content watched, measured in seconds

This metric excludes the duration of external live streams watched.
Underbuffer (cumulative)
(WEB)
underbuffer_cumulative integer Total milliseconds (ms) spent buffering since the play attempt for a given media item

Viewers

Name
(NOTES)
API ID Description API Custom Reports Data Sharing
Ad Impressions per Viewer
($, OTT, WEB)
ads_per_viewer integer Number of ad impressions divided by the number of unique viewers

This provides insight into how many ads are being served for each viewer.
Logged-In Unique Viewers
($, OTT)
logged_in_unique_viewers integer Number of unique authenticated users who have played at least one media item

Values are only returned for Apps that are integrated with a subscriber management provider, such as Cleeng or InPlayer.
Plays per Viewer
($, OTT, WEB)
plays_per_viewer integer Number of plays divided by the number of unique viewers

This provides insight into how many media items are being watched by each viewer.
Time Watched per Viewer
(OTT, WEB)
time_watched_per_viewer integer Total time watched in seconds divided by the number of unique viewers

This provides insight into the duration of a media item each viewer is watching.
Unique Viewers
(OTT, WEB)
unique_viewers integer Approximate number of unique users who have played at least one media item

A unique viewer is defined by IP and user agent.


Dimensions

A dimension is an attribute of your metrics. For example, each play event has several attributes that add context to the event. JWP determines the country where the event occurred, the associated video, and the device used.


_Content


Name
(NOTES)
Dimension ID Description API Custom Reports Data Sharing
Ad Client
(WEB)
ad_client integer Ad client being used

Possible Values:
  • Null: Player not enabled for ads
  • 0: VAST
  • 1: Google IMA
  • 2: FreeWheel
  • 3: DAI
Ad Schedule
($, WEB)
ad_schedule_id string (Custom Reports) Name or ID associated with a specific ad schedule

(API) ID associated with a specific ad schedule
Advance Type
(WEB)
advance_type string Denotes the method by which the playlist advanced at the end of this play session

Possible Values:
  • Null: User did not play video, user abandoned during play of video, or no advancement at end of play
  • Auto: Auto play
  • Click: User clicked on a video
Analytics ID
(WEB)
analytics_id string 22-character alphanumeric ID representing a grouping of properties

When segmenting data by a specific property, query by site ID.
Feed ID
(OTT, WEB)
feed_id string Unique ID for a playlist

NOTE: This dimension is the same as playlist_id in the Dashboard and API.
Has Ad Block
(WEB)
has_ad_block integer Indicates if an ad block is detected for this session due to a browser blocking ads

Possible Values:
  • -1: unknown
  • 0: No ad block
  • 1: Ad block
Is Autostart
(WEB)
is_autostart integer Player autostart setting for the first video upon embed of the player

Possible Values:
  • 0: Not autostart
  • 1: Autostart
  • 2: Autostart on viewable
Is Click to Play
(WEB)
is_click_to_play integer Denotes whether the reason for this play is a user click, auto or unknown

Possible Values:
  • -1: unknown
  • 0: auto
  • 1: user click
Is First Play
($, WEB)
is_first_play boolean Indicator that the media was the first media item within a playlist or embed
Media
(OTT, WEB)
media_id string (Custom Reports) Name or ID of the media item

(API) ID of the media item
Media Tag
($, OTT, WEB)
tag string Metadata media tag associated with a media item
Media Title
(WEB)
media_title string Title of the media
Media Type
(WEB)
media_type string Media type player has played
Media URL
(WEB)
media_url string URL of the media item
Number of Ad Breaks
(WEB)
num_ad_breaks integer Total number of ad break events that occurred during this session
Play ID
(WEB)
play_id string Unique ID generated for each play session
Play Reason
($, WEB)
play_reason string Indicator of how media playback was initiated

Possible Values:
  • autoplay: Autostarted playback, not dependent upon player viewability settings
  • click: A user clicked on the video
  • external: JavaScript call to the JW Player API
  • progression: Auto-advance on dynamic and manual playlists
  • related: Auto-advance on recommendation and search playlists
  • repeat: Auto-repeat based on the configuration of the player
  • unknown: Unknown reason
  • viewable: Autostarted playback when the player was viewable, dependent upon player viewability settings
Play Sequence
(WEB)
play_seq integer Item number within a playlist
Player
(WEB)
player_id string (Custom Reports) Name or ID of the player

(API) ID of the player
Player Playback Mode
(WEB)
player_playback_mode string Player's playback mode when the first frame of content is rendered

Possible Values:
  • DVR: Livestreams that support seeking
  • LIVE: Livestreams that do not support seeking
  • NULL: Embed without plays
  • VOD: Video on Demand
Playlist
(OTT, WEB)
playlist_id string (Custom Reports) Name or ID of the playlist

(API) ID of the playlist
Playlist Type
($, OTT, WEB)
playlist_type string Type of playlist

Possible Values:
  • Article Matching
  • Dynamic
  • Feed1
  • Manual
  • No Playlist (NULL)
  • Search
Promotion
($, WEB)
promotion string ID of the playlist pinned into a recommendations playlist that promoted the media item played in a player
Site ID
($, OTT, WEB)
site_id string Unique alphanumeric ID of the site
Video Duration
($, OTT, WEB)
video_duration string Duration of the content

Possible Values:
  • Short (under 4 mins)
  • Medium (4-20 mins)
  • Long (over 20 mins)

1 This is the same as a recommendations playlist.


Date/Time

Name
(NOTES)
Dimension ID Description API Custom Reports Data Sharing
Eastern Date
(OTT, WEB)
eastern_date string Date when the media item started to play within a player, using YYYY-MM-DD (USA - Eastern Time) format
End Time
(WEB)
end_time string End time of session in UTC as a datetime string
Start Time
(WEB)
start_time string Start time of session in UTC as a datetime string
Upload Date
($, OTT, WEB)
upload_date string Date when the media item was last uploaded to the platform, using YYYY-MM-DD (USA - Eastern Time) format
Viewer Timezone Offset
(WEB)
viewer_tz_offset integer UTC offset for the timezone of the user represented as an integer from -12 to 14

Device

Name
(NOTES)
Dimension ID Description API Custom Reports Data Sharing
App Bundle ID
(OTT)
app_bundle_id string (Apps) Identifier unique to the app
App Install Instance ID
(OTT)
ott_app_install_instance_id string (Apps) App install instance ID
App User ID
(OTT)
ott_app_user_id string (Apps) App account ID or its hash
App Version
(OTT)
app_version string (Apps) Version of the app
Average Player Height
(WEB)
avg_player_height number Average player height in pixels throughout session
Average Player Size
(WEB)
avg_player_pixel_size integer Average pixel widths of the player for the play session, grouped by player size buckets

Possible Values:
  • 0: Unknown
  • 1: Small (<=320px)
  • 2: Medium (321-640px)
  • 3: Large (>640px)
Average Player Width
(WEB)
avg_player_width number Average player width in pixels throughout session
Browser
($, WEB)
browser string Type of browser used to watch a media item
Device
(WEB)
device_id string Type of device used to watch a media item

Possible Values:
  • Connected Device
  • Connected TV
  • Desktop
  • Other
  • Phone
  • Tablet
  • Unknown
Device Firmware Version
(OTT)
ott_device_firmware_version string (Apps) Firmware version of the OTT device
Device Model
(OTT)
ott_device_model string (Apps) OTT Device Model number
Operating System
(OTT)
ott_os string (Apps) Name of the OS on the OTT device
Operating System Language
(OTT)
ott_os_language string (Apps) Language of the OS on the OTT device
Operating System Version
(OTT)
ott_os_version string (Apps) Version of the OS on the OTT device
Platform
($, OTT, WEB)
platform_id string SDK platform in which the player was embedded

Possible Values:
  • android
  • chromecast(Chromecast receiver)
  • fireos
  • ios
  • roku
  • tvos
  • unknown
  • web

Geography

Name
(NOTES)
Dimension ID Description API Custom Reports Data Sharing
City
($, WEB)
city string City from which a user accessed the media item

The value is based on the ISO 3166-2 standard.
Country
(OTT, WEB)
country_code string Two-letter country code from which a user accessed a media item

The value is the ISO 3166-1 alpha-2 country code.

Placement

Name
(NOTES)
API ID Description API Custom Reports Data Sharing
Domain
(WEB)
page_domain string Domain within which a player was embedded

By excluding www, all subdomains are also included.
Placement
(WEB)
placement_id string (Custom Reports) Name or ID associated with a Dynamic Strategy Rules placement

(API) ID associated with a Dynamic Strategy Rules placement
Placement Embed ID
(WEB)
placement_embed_id string Unique ID generated for each Dynamic Strategy Rules placement instance that is embedded on a page
Plugin Document Referrer
(WEB)
plugin_document_referrer string Referrer to the page where player is embedded

This information is gathered from the DOM.
URL
(WEB)
page_url string URL of the page within which a player was embedded