LucidVideo Recommendations

LucidVideo’s recommendation algorithm offers a unique combination of Editorial Control + AI to personalize the experience of users on your site. Recommendations are based on a unique combination of user profiling through content understanding, trending and most popular data as well as collaborative filters.

How It Works

Learn more about the recommendations algorithm and basic setup.

Editorial Widgets

How to set up editorial filters and content campaigns to decide what is shown to the users.

Recommendations JS

Start integrating LucidVideo Recommendations on your site with the JS plugin.

Recommendations SDK

Start adding recommendations to your apps using the LucidVideo SDKs.

Recommendations Swift

Start adding recommendations to your apps using Swift.

How It Works

The recommendation algorithm takes into account several variables in order to generate the perfect recommendation, unique to every user:

  1. Personalized contents (user profile)
  2. Current content being consumed (content related to the content that is being watched, if any)
  3. Trending (information about what is trending in the world, based on LucidVideo Stories, Google searches, Facebook and Twitter trends)
  4. Most viewed contents (currently being viewed on your site)
  5. Collaborative Filters (to solve the cold start problem) and Reinforcement learning (to keep improving recommendations for a user).
  6. Editorial Control (Editorial rules and Editorial Campaigns).

The algorithm tracks all user activity (what has been displayed to the user and what did the user click on/watched/consumed/seen a preview of). Based on this, we cross-match the concepts in each article/video and we create a user profile (which concepts the user reacts better to). This allows us to understand which concepts a user better reacts to, and build his user profile. This user profile is used to personalize his experience on the website.

Metadata is used for the personalization of contents and to detect content-to-content relationships. Moreover, you can leverage that metadata to put some specific editorial rules to the Recommendation algorithms (for instance, videos about one particular subject, or with some specific keywords).

To get started with LucidVideo Recommendations, first make sure all your contents have been uploaded to LucidVideo. LucidVideo will automatically process all your contents and find relationships between them. Then, you will need to create an Editorial Widget, and integrate the results in your website (using  Recommendations JS) or your app (Recommendations SDKs).

Editorial Widgets

We believe that your team is the one that better knows your audience, which is why they have full control to decide what should be shown to your users. Therefore, Recommendations algorithms have been designed to put your editorial team back in control.

To set up a new recommendation, you will need to generate an Editorial Widget, which is a set of rules for the recommendation algorithms to follow. To create one, just log into the Dashboard and click on Recommendations -> Create Editorial Rule. If you don’t see the Recommendations icon, contact us.

First, you need to add some rules. You can set up different rules, like showing content only with a specific tag (rule: Tags), or from a specific category or section. Add rules by selecting different options and values, and clicking on +. Once you have set up your rules, the Widget Preview will display the recommendations that would be shown with the current set of rules. Once you save the widget, you will see a hash. This is the editorial widget hash, which is used then to configure your recommendations module.

Copy this editorial widget hash and follow to Recommendations JS or Recommendations SDK to integrate with Web or Apps respectively.

Recommendations JS

Get Started

To start getting personalized recommendations you need to include the JavaScript code below to enable the Recommendation engine within your page framework.

<script src="//static.lucidvideo.com/vidrec/vidrec.3.0.1.min.js" data-publickey="yourpublickey" data-onpluginload="handler.onPluginLoad" data-confighash="confighash"></script>
HTML
  • data-publickey="yourpublickey" is your user ID.
  • data-onpluginload="handler.onPluginLoad" is the JavaScript function that will be called once the vidrec plugin is loaded. For more info, see integration examples.
  • data-confighash="confighash" the hash of an editorial filter.

Once the plugin is configured, here is an example code to get your recommendations:

var handler = {
    // handler.onPluginLoad will be passed to the lucidvideo 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 = "videoId";

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

        // The lucidvideo Recommendation plugin will find all the recommendations for 'url' and will insert them into the '#recommendations' DOM element
        lucidvideo.recommendations.get(url, handler.onRecommendations);
    },

    onRecommendations: function (recommendations) {
        console.log(recommendations);
    }
}
JavaScript

Integration Examples

The recommendation plugin allows you to retrieve the recommendations on a plain JavaScript array or to insert a rich HTML content directly to your page.

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 Recommendation plugin fires the onPluginLoad event when it’s ready. This allows you to use the lucidvideo.recommendations object to obtain a list of recommendations calling the lucidvideo.recommendations.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 lucidvideo 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 = "videoId",
            options = {"limit": 5};

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

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

    onRecommendations: function (recommendations) {
        console.log(recommendations);
    }
}
// The lucidvideo 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 lucidvideo user.
vidrecScript.dataset.publickey= "yourpublickey";
// Configuring the editorial filter
vidrecScript.dataset.confighash = "confighash";

vidrecScript.src = "//static.lucidvideo.com/vidrec/vidrec.3.0.1.min.js";

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

Update User Profile

There are two feedback actions that can be taken on recommended content to update the user profile for personalization:

  • Liking (positive)
  • Skipping (negative)

Liking

The LucidVideo recommendations plugin exposes a like function, which can be called with lucidvideo.recommendations.like(content_GUID). When a recommended piece of content is liked the user is more likely to see similar content in the future.

The like function accepts one parameter: a content guid that has been previously recommended by the plugin.

The following example shows how to use the like function:

var handler = {

    ...

    doLike: function(contentGuid) {    
        lucidvideo.recommendations.like(contentGuid);
    }
}
JavaScript

Skipping

The LucidVideo recommendations plugin exposes a skip function, which can be called with lucidvideo.recommendations.skip(content_GUID). When a recommended piece of content is skipped the user is less likely to see similar content in the future.

The skip function accepts one parameter: a content guid that has been previously recommended by the plugin.

The following example shows how to use the skip function:

var handler = {

    ...
    
    doSkip: function(contentGuid) {
        lucidvideo.recommendations.skip(contentGuid);
    }
}
JavaScript

Options

You can customize your integration with the following parameters:

NameTypeDefaultDescription
publickeystringnoneUnique string to identify your lucidvideo account.
confighash NEWstringnoneThe hash associated with your editorial filter. To learn more about editorial filters click here.
debugbooleanfalsePrint debug console logs.
onpluginloadfunctionnoneThe script called once the plugin is loaded.
limitnumber5The maximum number of recommendations returned by the script.
returnmetadatabooleanfalseIf set to true, will return a rich output with full item properties.

The configuration parameters can be used in two different ways:

  • Including them at the script tag. This will affect all the recommendations the plugin is generating.
  • Passing them as an object to the plugin request. Configuration parameters supplied by this method will override the ones at script tag.

Take a look at the integration examples to see some implementations.

Recommendations SDK

Android

Including The Library

To include Recommendations on your Android or Android TV app, you need to manually add the library .aar to your Android Studio project as a dependency. To do that, create a new module on your project and select Import .JAR/.AAR Package and then add this module as a dependency of your app.

The LucidVideo Recommendations library also has a transitive dependency on OkHttp and Gson, so you will need to add them too to your application Gradle file.

Getting recommendations

In order to get recommendations based on your content, you need to create an instance of RecommendationsParameters.

RecommendationsParameters defines all the configuration parameters for a request. Those parameters are:

  • publicKey: String: Your public key
  • guid: String: guid (or url) of the content that you want to get the recommendations.
  • dynamicFilter: String?: Dynamic filter for the content of the recommendations (if any).

Example:

private fun buildRequestParameters(
        guid: String
): RecommendationsParameters {
    return RecommendationsParameters(
            publicKey = "YOUR_PUBLIC_KEY",
            guid = guid,
            dynamicFilter = null)
}
Kotlin

The onCompletion callback will return you an array of Recommendation object sorted by score, having the following attributes for each recommended resource:


var duration: Double
var guid: String
var hash: String
var title: String?
var type: String? // Content type
var url: String?
var score: Double
var thumbnail: String?
// Any extra fields that were configured on the editorial rule
var extraItems: Map<String, Any>
Kotlin

Update User Profile

There are three feedback actions that can be taken on recommended content to update the user profile for personalization:

  • Clicking
  • Liking (positive)
  • Skipping (negative)

Clicking

When you request recommendations from a guid, the SDK will register it as clicked, but you can also mark a content guid as clicked by calling registerRecommendationClicked(guid: String):

lucidvideoRecommendations.instance.registerRecommendationLiked(guid: String)
Kotlin

Liking

When a recommended piece of content is liked the user is more likely to see similar content in the future.

lucidvideoRecommendations.instance.registerRecommendationClicked(guid: String)
Kotlin

Skipping

When a recommended piece of content is skipped the user is less likely to see similar content in the future.

LucidVideoRecommendations.instance.registerRecommendationSkipped(guid: String)
Kotlin

Configuring log level

You can enable or disable the logs of the Recommendations SDK by calling LucidVideoRecommendations.instance.setLogLevel(logLevel: LogLevel). Valid values are .Debug and .None.

Disabling user profile storage

You can enable or disable the logs of the Recommendations SDK by calling LucidVideoRecommendations.instance.setLogLevel(logLevel: LogLevel). Valid values are .Debug and .None.


    lucidvideoRecommendations.instance.getRecommendations(
            ...
            disableStorage = false,
            ...
    
Kotlin

When disableStorage is activated it will clear the current user profile, if it exists, and no data will be stored on the device.

Download SDK & Example

To get access to our SDKs, please contact us.

Swift

Integrating framework

To integrate Recommendations on your Swift app you will need to include the LucidVideoRecommendations.xcframework on your Xcode project. After importing it check that it is linked and copied into your app target, by checking the Link Binary With Libraries and Embed Frameworks Build Phases of it.

Getting recommendations

In order to get recommendations based on your content, you need to create an instance of RecommendationsParameters.

The RecommendationsParameters struct defines all the configuration parameters for a request. Those parameters are:

  • publicKey: String: Your public key
  • guid: String: guid (or url) of the content that you want to get the recommendations.
  • dynamicFilter: String?: Dynamic filter for the content of the recommendations (if any).

Example:

private func buildRequestParameters(
    guid: String
) -> RecommendationsParameters {
        return RecommendationsParameters(
            publicKey: "YOUR_PUBLIC_KEY",
            guid: guid,
            dynamicFilter: nil,
            disableUserProfile: false
        )
}
Swift

Then you need to create an instance of LVRecommendations and call the method getRecommendations of it.

Example:

var lucidvideoRecommendations = LVRecommendations(logLevel: .debug)
lucidvideoRecommendations.getRecommendations(
    recommendationsConfiguration: buildRequestParameters(guid: "a content guid"),
    editorialRuleHash: nil,
    limit: 25,
    disableStorage: false,
    onCompletion: { recommendations in
        // Handle the recommendations output
    }
    , onError: {
        ...
    })
Swift

The onCompletion closure will return you an array of Recommendation sorted by score, having the following attributes for each recommended resource:

public var duration: Double?
public var guid: String
public var hash: String
public var title: String?
public var type: String? // Content type
public var url: String?
public var score: Double
public var thumbnail: String?
// Any extra fields that were configured on the editorial rule
public var extraItems: [String: Any]?
Swift

Update User Profile

There are three feedback actions that can be taken on recommended content to update the user profile for personalization:

  • Clicking
  • Liking (positive)
  • Skipping (negative)

Clicking

When you request a recommendations from a guid, the SDK will register it as clicked but you can also mark some contents as clicked by calling registerRecommendationClicked(guid: String):


let LVRecommendations = LVRecommendations.init()
LVRecommendations.registerRecommendationClicked(guid: String)
Swift

Liking

When a recommended piece of content is liked the user is more likely to see similar content in the future.

let LVRecommendations = LVRecommendations.init()
LVRecommendations.registerRecommendationLiked(guid: String)
Swift

Skipping

When a recommended piece of content is skipped the user is less likely to see similar content in the future.

let LVRecommendations = LVRecommendations.init()
LVRecommendations.registerRecommendationSkipped(guid: String)
Swift

Disabling user profile storage

You can disable the storage of the user profile by passing true to disableStorageparameter of getRecommendations:

recommendations.getRecommendations(
    ...
    disableStorage: false,
    ...)
Swift

When disableStorage is activated it will clear the current user profile, if it exists, and no data will be stored on the device.

Download SDK & Example

To get access to our SDKs, please contact us.