Discovery Design Considerations

Consider these design issues when implementing discovery for your player.

Use discovery profiles instead of editorial query string parameters.

As stated in Summary of Ooyala Discovery REST API Requests, Ooyala Discovery API requests that read return a base set of recommendations from the machine-learning algorithm. This base set can be modified either by discovery profiles (see Discovery Profiles) or by the editorial query string parameters (see Discovery Editorial Query String Parameters). Both mechanisms accomplish the same goal: tailoring the base set of recommendations.

Ooyala recommends using discovery profiles rather than editorial query string parameters.

With discovery profiles, you can abstract how Discovery works for your viewers and centralize some of the onscreen behavior of Discovery recommendations. You can then reuse these profiles on any of your Discovery API requests.

One advantage of discovery profiles is that, after you create them, their data is periodically precomputed. By contrast, the editorial query string parameters are settings on each individual ad hoc request, applied after the base set has been created. The editorial query string parameters are applied at the time of the request, without pre-computation.

Discovery profiles also avoid some common problems, as described in other sections.

Do not mix filtering with discovery profiles. Filtering always takes precedence.

The base set of returned results can be modified either by discovery profiles or by the filter_by query string parameter (among others).

However, the filter_by parameter always take precedence over discovery_profile_id, effectively nullifying the profile.
Note: Only filter_by takes precedence in this way. Other editorial query string parameters detailed in Discovery Editorial Query String Parameters can be used in conjunction with profiles.

Thus, early on in your design, you should decide to use either profiles or filter_by, but not both.

We recommend that you use profiles.

Avoid the query string/huge limit trap.

Discovery editorial query string parameters (see Discovery Editorial Query String Parameters) are applied to a base set of recommendations returned by the system.

A common trap developers fall into is to use the filtering query string parameters to such an extent that it appears that much of the base set of recommendations is excluded, sort of "whittled away", resulting in few or no recommendations to display.

In consequence, some developers increase the value of the limit query string parameter in an attempt to increase the number of base set recommendations and then apply the query string filtering. This does not work, however, for two reasons. First, it still does not guarantee that Discovery will return the number of results desired, for the reasons described above. Second, it introduces a significant amount of latency in the API request (given the large number of request results that need to be fetched and returned), which can cause can timeout.

The solution to this problem is to use discovery profiles and avoid the filtering query string parameters altogether.

Use labels, not asset metadata.

Ooyala recommends using labels for filtering in discovery profiles. Backlot uses custom metadata to allow customers to store the proprietary data associated with an asset.

Labels provide scalable support for indexing, caching, and querying when used via the APIs. The Discovery APIs are designed to be called by a consumer-facing website. The Backlot APIs do not provided this feature.

For information about creating labels, see Labels. For information about using labels in discovery profiles, see Discovery Profiles.

Disable the Pause screen for mid-roll ads.

The Pause screen displays information you choose whenever the user pauses the video. If you are serving mid-roll ads, Ooyala recommends that you avoid displaying Discovery recommendations on the pause screen because your video analytics metrics might become unclear. For example, is a pause event due to the pause screen or a mid-roll ad?

To disable the Pause Screen, log on to the Backlot user interface and select: Publish > Discovery.

Click the checkbox to disable the Display Discover Tray in Pause Screen option.