Customer Sign In

upLynk

Playback Replacement Plugins

Overview

Newer versions of the playback code have a feature called “replacement plugins”. If you are unsure whether your account uses a version that supports replacement plugins, please contact support. These plugins are developed and maintained internally. Replacement plugins are loaded server-side when the repl playback URL parameter is provided. When a plugin is loaded, it can optionally replace content that would normally be played with other content. Whether to replace content or not is determined by the plugin’s logic.

Authorization

Before an Owner can load and use a plugin they must be granted authorization to use a specific plugin. If you wish to use a plugin please contact support with a request including your account name and which plugin to enable.

Loading a Plugin

Owners can load a replacement plugin during a playback session by providing the repl parameter in their playback URL. For example, to use a replacement plugin with my test player at http://content.uplynk.com/player/6ZpnSRiEmjj3fMdnzDaV00sc.html and the plugin I want to load is named plug, I would use:

http://content.uplynk.com/player/6ZpnSRiEmjj3fMdnzDaV00sc.html?repl=plug

Plugin Parameters

Some plugins accept parameters. To pass parameters to a replacement plugin, use URL parameters with names of repl.[param_name]. For example, if a replacement plugin plug takes param1 and param2 and I want to pass value1 and value2 respectively, I would use:

http://content.uplynk.com/player/6ZpnSRiEmjj3fMdnzDaV00sc.html?repl=plug&repl.param1=value1&repl.param2=value2

Most plugins also support reading these parameters from the channel's custom metadata. As the database we use behind the scenes doesn't support the '.' character, these parameters are specified with '-' in the custom metadata key field. To build on the previous example, the parameters and values specified could also be put on the channel's custom metadata:

keyvalue
repl-param1value1
repl-param2value2

Available Plugins

Conditional Blackout

Load parameter: repl=blackout

The blackout plugin enables content providers to blackout certain assets from their channel’s timeline. In order for an asset to be blacked out, it must contain custom metadata blackout_id that matches the value associated with the playback replacement parameter boid. If they match, the channel’s blackout slate (or if not defined, the owner’s blackout slate) will be played. If they don’t match, the asset will play.

Parameters:

Name Type Required Description
boid string No The blackout ID to use when determining whether an asset in a timeline should be blacked out. If the value provided with this parameter matches the blackout_id custom metadata on the asset, the channel or owner blackout slate will play. If there is no match, the asset will play.

Note that this plugin does not currently support specifying the boid in channel metadata.

Example:

Using the meta parameter on the slicer’s content_start method to set the asset’s custom metadata, I now have an asset that contains meta.blackout_id=blackout_01. If I then play a channel that contains this asset with the following URL params:

http://…?repl=blackout&repl.boid=blackout_01

Because the repl.boid value and the meta.blackout_id match, when the timeline reaches this asset the viewer will see blackout slate instead of the asset.

Reverse Blackout

Load parameter: repl=rbo

The rbo, or “reverse blackout”, plugin works in reverse of the blackout plugin described above. If the blackout plugin defaults to letting all content through and filters those that match the rules, the rbo plugin defaults to letting no content through and allows only those that match the given parameters.

Parameters:

Name Type Required Description
prop,val.<id> string No

The prop,val.<id> parameters are the method by which the caller can specify what asset property to use for filtering. <id> must be replaced by a unique identifier for each property/value pair. A meaningful string identifier is fine, or an incrementing integer value would work, as well. Filename-type wildcards can also be used in the value, where '*' matches multiple characters, and '?' matches one character. Note that the match is case-insensitive.

Example:

Let’s say I have multiple assets in a timeline and I wish to black out all content except those with a desc property of either “Nightly News” or "Good Morning, USA". Let's also say that the assets with a description of "Good Morning, USA" are always that exact string. Further, let's say that in the "Nightly News" case the description could also include a suffix, such as "Nightly News - 01", which means I will want to match any descriptions that start with "Nightly News". I would use the following playback URL parameters to accomplish this:

http://…?repl=rbo&repl.prop,val.nightlynews=desc,Nightly%20News%2A&repl.prop,val.gmusa=desc,Good%20Morning,%20USA

Note that the spaces and the '*' are URL-encoded (%20 and %2A, respectively), but unencoded characters can also be passed as long as the client sends them properly.

As an alternative to using the URL parameters, I could specify the repl-prop,val-<id> parameters (note '.' has been replaced with '-' in the key name) in channel custom metadata by specifying the following custom metadata on the channel.

keyvalue
repl-prop,val-nightlynewsdesc,Nightly News*
repl-prop,val-gmusadesc,Good Morning, USA

Regional Blackout

Load this plugin by adding this query string parameter to the playback URL:

repl=aboi

The Regional Blackout plugin allows content providers to distribute programming based on the viewer's location. Regional Blackout requires a program to contain custom metadata (i.e., blackout_id) that identifies a blackout rule within the corresponding channel. The CMS takes into account a viewer's location and this blackout rule to determine whether standard or alternate programming (i.e., slate, an alternate slicer, or VOD) will be streamed to the viewer.

Parameters

A viewer's location may be overriden via parameters. Additionally, a specific blackout zone may be assigned to a viewer via the following parameter:

Name Type Required Description
cbz string No Overrides a viewer's location to a specific blackout zone. Identify a blackout zone by its name or ID. Blackout zone names should be URL encoded.

Example:

In this sample scenario, a program is assigned a regional blackout rule with an ID of "blackout_01." This rule is configured to black out the west coast of the United States. By default, viewers within that region will view alternate content, while those outside of this region will view standard programming.

Standard playback URL:

http://…?repl=aboi

This behavior may be overridden for a specific viewer by adding the cbz query string parameter to the playback URL.

Location-override playback URL:

http://…?repl=aboi&repl.cbz=blackoutzone1

The above playback URL overrides the viewer's location to one that matches the blackout zone called "blackoutzone1." If the blackout rule applied to the current program excludes the specified blackout zone, then the viewer will play back alternate content instead of the regularly scheduled program.