Set up Recommendations (Web Player)
Automate the generation of a playlist based on a seed video.
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 JWP 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 player library or self-hosted player library that has been added to the <head>
of your page.
- Associate Recommendations to specific content: This option provides the most flexibility.
- Associate Recommendations to a player: This option allows you to associate the same recommendations playlist logic to all content viewed in a player. However, you cannot customize the
related.autoplaymessage
orrelated.heading
for localization.
You can also set up Recommendations from your JWP dashboard.
Associate Recommendations to specific content
-
Make a call to
api.jwplatform.com/v1
usingPOST /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.curl -X POST 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
-
Locate the eight-character, alphanumeric
channel.key
in the response. This is the unique identifier for the playlist that you just created.
{ "status": "success", "rate_limit": { "reset": 1562880540, "limit": 60, "remaining": 60 }, "channel": { "key": "n29tZc01" }, "signature": "12Three4567=&$-12Three4567=&$.EAk7kg.12Three4" }
As an alternative to these previous steps you can use the following steps:
- Create a recommendations playlist within your JWP dashboard.
- Copy the Playlist ID from the DEVELOPER RESOURCES tab of the recommendations playlist.
-
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.
You can append the same recommendations playlist to multiple players. And, you can also incorporate additional features to the media (/v2/media/{media_id}
) or playlist (/v2/playlists/{playlist_id}
) URL.playlist: "https://cdn.jwplayer.com/v2/media/Ly53q8A1?recommendations_playlist_id={key}"
-
(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.
-
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
-
(Optional) Define the
related.autoplaytimer
as10
. This creates a 10-second break between the playback of videos and enables the countdown overlay to appear. -
(Optional) Define the
related.oncomplete
asautoplay
. This property helps to extend a user's viewing session. -
(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 byrelated.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
.
-
(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
-
(Optional) Add other related properties to customize the viewing experience.
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" } } } });
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:
-
Make a call to
api.jwplatform.com/v1
usingGET /players/list
to receive a list of existing players. If this is your first time using the Management API, read our documentation on authentication.curl -X GET https://api.jwplatform.com/v1/players/list?api_nonce=80684812&api_timestamp=1237387841&api_format=json &api_signature=fbdee51a45980f9876834dc5ee1tz5e93f67cb89&api_key=abC432d1
-
Locate and save the eight-character, alphanumeric
player.key
in the API response for the player that you want to update. -
Make a
GET /channels/create?type=feed&type={title_name}
call to create a playlist. Replace{title_name}
with a name for the playlist.curl -X POST 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
-
Locate the eight-character, alphanumeric
channel.key
in the API response. This is the unique identifier for the playlist that you just created. -
Make a POST /player/update call to configure the recommendations playlist you created and to associate the recommendations playlist to an existing player.
curl -X 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" }
Updated 12 months ago