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 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
    ❌
    ❌
    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 adn 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
    βœ…
    βœ…
    ❌
    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.
    βœ…
    βœ…
    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
    βœ…
    βœ…
    βœ