Set up Recommendations

Last Updated: August 6, 2019

If you have hundreds of videos hosted on or registered with your account, Recommendations automates the generation of a playlist based on a seed video and provides you options to customize the appearance and behavior of that playlist.

This feature requires an Enterprise license. To access these features, upgrade now and ask your JW Player representative to enable Recommendations.


Use one of the following approaches to add Recommendations to an embedded web player and configure the viewing experience. You must be using a cloud-hosted or self-hosted player library that has been added to the <head> of your page.



You can also set up Recommendations from your JW Player dashboard.


Associate Recommendations to specific content

1. Make a call to api.jwplatform.com/v1 using GET /channels/create?type=feed&title={title_name} to create a playlist. Replace {title_name} with a name for the playlist. If this is your first time using the Management API, read our documentation on authentication and call syntax.

GET https://api.jwplatform.com/v1/channels/create?type=feed&title=An+awesome+feed
&api_nonce=80684843&api_timestamp=1237387851&api_format=json
&api_signature=fbdee51a45980f9876834dc5ee1ec5e93f67cb89&api_key=abC432d1


2. Locate the eight-character, alphanumeric channel.key in the response. This is the unique identifier for the playlist that you just created.

As an alternative to these previous steps you can use the following steps:

  1. Create a recommendations playlist within your JW Player dashboard.
  2. Copy the Playlist ID from the DEVELOPER RESOURCES tab of the recommendations playlist.


3. In the playlist parameter of your player code, add a query string for the recommendation playlist (?recommendations_playlist_id={channel.key}) to the existing playlist or video URL. Be sure to replace {channel.key} with the key from the API response or Playlist ID.

playlist: "https://cdn.jwplayer.com/v2/media/Ly53q8A1?recommendations_playlist_id={key}"

You can append the same recommendations playlist to multiple players. And, you can also incorporate additional features to the media URL (/v2/media/{media_id}) or playlist URL (/v2/playlists/{playlist_id}) endpoint.


4. (Optional) Define the nextupoffset property to define when the Next Up pop-up appears. The Next Up display shows the name, thumbnail, and duration of the next video. When the default value (-10) is not changed, the Next Up display appears 10 secs before the current video ends.


5. Define the related.displayMode property. This property controls how the recommended video thumbnails are displayed. Choose between the options in the following table.

Option Description
shelf (Default) Adds a horizontal bar of thumbnails above the control bar that allows viewers to browse recommended videos during the playback experience and when playback is paused

The shelf appears when a viewer clicks the Recommendations icon located above the control bar during playback or pauses playback.
shelfWidget Adds a persistent horizontal bar of thumbnails beneath the player that allows viewers to browse recommended videos during the playback experience


6. (Optional) Define the related.autoplaytimer as 10. This creates a 10-second break between the playback of videos and enables the countdown overlay to appear.


7. (Optional) Define the related.oncomplete as autoplay. This property helps to extend a user's viewing session.


8. (Optional) Use the intl.en.related.autoplaymessage property to define the message that displays when the countdown overlay appears. We suggest using __title__ will play in xx seconds.

The countdown message appears above the title and description of the next video to play. The default message is Next up in X. X represents the number of seconds remaining in the countdown as defined by related.autoplaytimer. As shown in the full code sample at the end of this article, you can customize this text for other languages by adding additional language objects: intl.{lang}.related.autoplaymessage.


9. (Optional) Define the intl.en.related.heading property to customize the title of Recommendations videos. You can customize this text for other languages by adding additional language objects: intl.{lang}.related.heading. The location of this text depends upon the value of displayMode.

Display mode Locations
shelf • Next to the Recommendations icon above the control bar
• Title of the countdown overlay
shelfWidget • Above the horizontal bar of thumbnails beneath the player
• Title of the countdown overlay


10. (Optional) Add other related properties to customize the viewing experience.


Full code sample:

jwplayer("myElement").setup({
  playlist: "https://cdn.jwplayer.com/v2/media/Ly53q8A1?recommendations_playlist_id=n29tZc01",
  nextupoffset: -10,
  related: {
    displayMode: "shelf",
    autoplaytimer: 10,
    oncomplete: "autoplay"
  },
  intl: {
    en: {
      related: {
        autoplaymessage: "__title__ will play in xx seconds",
        heading: "More Amazing Videos"
      }
    },
    fr: {
      related: {
        autoplaymessage: "__title__ commencera dans xx secondes",
        heading: "Plus de vidéos étonnantes"
      }
    }
  }
});

You can also use JavaScript API calls to enhance the functionality of your JW Recommendations viewer experience.

Associate Recommendations to a player

If you use the same cloud-hosted player in multiple locations on your site, you can add Recommendations to the player. This allows you to configure Recommendations in one location and to apply those settings to all content that is viewed in the player.


Use the following steps to add Recommendations to a player:


1. Make a call to api.jwplatform.com/v1 using GET /players/list. If this is your first time using the Management API, read our documentation on authentication and call syntax.

GET https://api.jwplatform.com/v1/players/list?api_nonce=80684812&api_timestamp=1237387841&api_format=json
&api_signature=fbdee51a45980f9876834dc5ee1tz5e93f67cb89&api_key=abC432d1


2. Locate and save the eight-character, alphanumeric player.key in the API response for the player that you want to update.


3. Make a GET /channels/create?type=feed&type={title_name} call to create a playlist. Replace {title_name} with a name for the playlist.

GET https://api.jwplatform.com/v1/channels/create?type=feed&title=An+awesome+feed&api_nonce=80684843&api_timestamp=1237387851&api_format=json
&api_signature=fbdee51a45980f9876834dc5ee1ec5e93f67cb89&api_key=abC432d1


4. Locate the eight-character, alphanumeric channel.key in the API response. This is the unique identifier for the playlist that you just created.


5. Make a POST /player/update call to configure the recommendations playlist you created and to associate the recommendations playlist to an existing player.

POST https://api.jwplatform.com/v1/player/update?
api_nonce=80684843&api_timestamp=1237387851&api_format=json
&api_signature=fbdee51a45980f9876834dc5ee1ec5e93f67cb89&api_key=abC432d1

{
  "player_key": "kGWxy33Z",
  "related_displaymode": "shelf",
  "related_autoplaytimer": "10",
  "related_videos": "autoplay",
  "related_autoplaymessage": "__item-title__ will play in xx seconds",
  "related_heading": "More Amazing Videos"
}

You can also use JavaScript API calls to enhance the functionality of your JW Recommendations viewer experience.



Use this form to provide your feedback.