Prizma offers an Embedded Recommendations JavaScript API for developers who wish to build lightweight web applications that serve Prizma video recommendations. This headless API can be implemented using the below instructions. One of the hallmarks of Prizma is its ability to improve recommendations automatically; therefore, it is paramount that performance information be sent back to Prizma to ensure optimal performance.

Begin by adding the following to the <head> tag of any page(s) where you want to use the Prizma recommendation software:

<script src="http://cdn.prizma.tv/widget/prizma-headless-widget.js"></script>

You may instantiate the widget with just your Partner ID and it will automatically curate videos based on the page where it is embedded:

<script> new prizma.api({partnerId: "PB-XXXXXXX"});</script>

See bottom of page for examples

Optional Initialization Parameters

These parameters can be used when instantiating a new Prizma widget. All widget instantiations must include your Partner ID.

option details
url The URL of the page that should be used to curate videos, if not the current page. String.
description A description of the page, e.g. Open Graph or meta description. Improves curation. String.
title The title of the page e.g. Open Graph or title tag; improves results if provided. String.

Methods

The following methods can be invoked on a Prizma widget object:

  • getRelevantVideos() : returns a JSON object of video recommendations based on viewer's context
  • getEndSlateVideos({ "videoid":videoid , "player": player }) : returns a JSON object of video recommendations based on what viewer has watched already. See getEndslateVideos parameters.
  • trackEvent(eventname, properties) : see below for events and their respective properties

getRelevantVideos() response

Invoking getRelevantVideos() on a Prizma API object returns a JSON object containing the following:

  • num : the number of recommendations returned
  • partnerID : your Prizma partner ID
  • results : an array of video recommendation objects, explained below

Video Recommendation Objects

Each video recommendation object contains the following:

  • prizma_videoid : The unique Prizma identifier for that video
  • player : The name of the player required to play that video
  • playerparams : An array of parameters required to play that video. This varies depending on the player used; typically, it will include at least a video id. Refer to the third-party player documentation for information about required player parameters.

getEndslateVideos() parameters

getEnslateVideos() takes a JSON object of a player and a videoid.

  • videoid : The ID (provided by your system) of the most recent video played
  • player : The name of the player used to play videos.

getEndslateVideos() response

Response is same format as getRelevantVideos. See getRelevantVideos() response.

Tracking Events with trackEvent()

These events should be passed back to the Prizma widget to ensure accurate tracking using widget.trackEvent().

event details properties
VideoThumbnailClick Pass when the video's thumbnail (or equivalent) has been clicked video_id, video_player video_title, video_thumbnail_url
VideoPlayerLoad Pass this event after the user has triggered the load event for your chosen video player video_id, video_player, video_title
VideoPlayStarted Pass this event when the video has started video_id, video_player, video_title
VideoPlayCompleted Pass this event when the video has been completed video_id, video_player, video_title

Event Properties

All initialization events have the following properties: video_id, video_player, video_title. The VideoThumbnailClick event also should include the video_thumbnail_url property.

event details
video_id The id of the video triggering the event
video_player The name of the player used to play the video, e.g. 'kaltura', 'brightcove'
video_title The title of the video triggering the event
video_thumbnail_url The URL of the thumbnail of the video triggering the event

getRelevantVideos Usage Examples

Create a new Prizma widget by adding the following code to a page:

Run Code