Integration examples

There are two ways to integrate the recommendation plugin into your site:

JavaScript array response

Use the code below to enable the recommendation plugin. It returns a JavaScript array with a list of URLs to display content on your page.

Example

The Vilynx Recommendation plugin fires the onPluginLoad event when it's ready. This allows you to use the vilynxRecommendations object to obtain a list of recommendations calling the vilynxRecommendations.get() function. Before this function ends, a callback function it's passed as a second parameter to the .get() call.

For example, if your callback function is onReturn(recs), the recommendations will be on the recs variable.

The .get() function allows up to three parameters:

  • The URL where to get the recommendations.
  • The callback function to receive the recommendations.
  • An options object with settings for each individual request. See more details.

The following example shows how to use these two events to manage the recommendations:

var handler = {
    // handler.onPluginLoad will be passed to the Vilynx Recommendation script tag and will be called when the vidrec plugin is ready.
    onPluginLoad: function () {
        // This variable must contain a valid URL or a valid GUID.
        var url = "example.com/sports/somearticle", options = {"limit": 5, "type":["video", "article"]};
        // Let's get some feedback.
        console.info('Vilynx Recommendation plugin loaded');

        // The Vilynx Recommendation plugin will find all the recommendations for 'url' and will call handler.onRecomendations when the recommendations are ready.
        vilynxRecommendations.get(url, handler.onRecomendations, options);
    },
    // handler.onRecomendations will be called when the vilynxRecommendations.get call has finished executing.
    onRecomendations: function (recomendations) {
        // 'recomendations' is an ordered array of recommended urls
        console.log(recomendations)
    }
}

// The Vilynx Recommendation plugin can be inserted with JavaScript or can already exist on the DOM when the document loads. The onPluginLoad function must exist when the vidrec is loaded.
var vidrecScript = document.createElement("script");

// onpluginload will be called when the vidrec plugin is successfully loaded.
vidrecScript.dataset.onpluginload= "handler.onPluginLoad";

// publickey is required to identify you as a Vilynx user.
vidrecScript.dataset.publickey= "HASH";

// This limits the maximum number of recommendations.
vidrecScript.dataset.limit= "5";

vidrecScript.src = "//static.vilynx.com/vidrec/vidrec.{{vidrecVersion}}.min.js";

var target = document.querySelector("body");
target.appendChild(vidrecScript);

HTML response

You can also use the recommendation plugin to get an HTML response that displays your thumbnails and content title. The resulting code is responsive and shows as many thumbnails as possible, depending on the size and orientation of its parent container. You can choose to override the default size settings by defining a minimum width and height value.

Example

The onPluginLoad event fires when the plugin is ready, which allows you to use the vilynxRecommendations object. To obtain the complete HTML of your recommendations you can call the function vilynxRecommendations.insert(). The recommendations will be inserted in the desired DOM object when passed as a parameter to the .insert() call.

The URL where to get the recommendations.

The DOM path to insert the recommendations.

An options object with the settings for each individual request. See more details.

The following example displays how to use these two events to manage the recommendations:

var handler = {
    // handler.onPluginLoad will be passed to the Vilynx Recommendation script tag and will be called when the vidrec plugin is ready.
    onPluginLoad: function () {
        // This variable must contain a valid URL or a valid GUID.
        var url = "example.com/sports/somearticle",
        options = {"limit": 5, "type":["article"]};

        // Let's get some feedback
        console.info('Vilynx Recommendation plugin loaded');

        // The Vilynx Recommendation plugin will find all the recommendations for 'url' and will insert them into the '#recommendations' DOM element
        vilynxRecommendations.insert(url, '#recommendations', options);
    }
}

// The Vilynx Recommendation plugin can be inserted with JavaScript or can already exist on the DOM when the document loads. The onPluginLoad function must exist when the vidrec is loaded.
var vidrecScript = document.createElement("script");

// onpluginload will be called when the vidrec plugin is successfully loaded.
vidrecScript.dataset.onpluginload= "handler.onPluginLoad";

// publickey is required to identify you as a Vilynx user.
vidrecScript.dataset.publickey= "youruserhash";

// This limits the maximum number of recommendations.
vidrecScript.dataset.limit= "5";

vidrecScript.src = "//static.vilynx.com/vidrec/vidrec.{{vidrecVersion}}.min.js";

var target = document.querySelector("body");
target.appendChild(vidrecScript);

Options

You can further customize the code with these options:

Name Type Default Description
publickey string none Unique string to identify your Vilynx account.
confighash string none The valid editorial widget hash. Find it on your Vilynx dashboard.
debug boolean false Print debug console logs.
onpluginload function none The script called once the plugin is loaded.
limit number 5 The maximum number of recommendations returned by the script.
returnmetadata boolean false If set to true, will return a rich output.
feedhash string none If a feed hash is given, only the recommendations obtained from that feed will be returned.
retrieveguid boolean false If set to true, the plugin will return GUID insead of URLs.
urlfilterregex regex none Filter all the URLs that match a given regular expression.
type array ["video"] The type of recommendations to get. Possible values are either video or article.

All the strikethrough parameters are deprecated and will be removed on version 4.0.0. You can configure your recommendations on the Vilynx Dashboard.