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.

1720

Recommendations shelf overlay

πŸ“˜

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.


πŸ”‘

You can also set up Recommendations from your JWP dashboard.



Associate Recommendations to specific content

  1. Make a call to api.jwplatform.com/v1 using POST /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
    
  2. 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:

    1. Create a recommendations playlist within your JWP 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.

    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}"
    
  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.

1018

Next Up pop-up

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


    OptionDescription
    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.
    shelfWidgetAdds a persistent horizontal bar of thumbnails beneath the player that allows viewers to browse recommended videos during the playback experience

    1375

    Shelf and Shelf Widget display modes

  2. (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.

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

  4. (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.

1956

Next up overlay

  1. (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 modeLocations
    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
  2. (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:

  1. Make a call to api.jwplatform.com/v1 using GET /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
    
  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.

    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
    
  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.

    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"
    }