Player V3 LiveRail Ad Integration

Overview

LiveRail ad sets can be associated with an asset or multiple assets. This documentation describes the LiveRail integration with Player V3. LiveRail VAST ads are supported in Player V4. For documentation on the LiveRail integration with Player V4, see VAST and VPAID Ad Plugin.

Prerequisites

To use Ooyala's LiveRail ad integrations, log into the Customer Portal and submit a ticket requesting that this ad source be added to your account. Once it's enabled you'll be able to create ad sets for LiveRail.

Step 1: Create a LiveRail Ad Set

Follow these steps to integrate with LiveRail via ad sets:

For instructions on how to create an ad set using the Backlot UI, see Creating Ad Sets for Integrating with Ad Sources. For instructions on how to create an ad set programmatically, see Ad Sets.
Note: You will see three LiveRail options when creating an ad set. Choose the "LiveRail" option. This integration can handle both in-stream and overlay ads via the LiveRail ads manager.
The required ad set fields for creating a LiveRail ad set are:
  • Ad Set name: You will enter a name for the ad set.
  • Publisher ID: A unique account value provided by LiveRail.
  • Use Custom Metadata: You will set this to Yes to enable the ad manager to pass LiveRail run-time parameters via the ad manager.
The optional fields for creating a LiveRail ad set are:
  • Partner IDs: If you are syndicating your content to a partner and are loading a unique ad set for each partner, include a value here. You must create the Partner ID in Liverail if you want to use this value.
  • Tags: You could add comma-separated keywords describing the video content here. These tags will be included as targeting run-time parameters for all ad requests associated with the LiveRail ad set.
  • Ad Map: The default ad map setting for LiveRail is a single pre-roll. If you would like to apply a different ad map, this value may be updated. For example, adding the value in::0;ov::5,35 to this field would include a pre-roll starting at 0 seconds and an overlay from 5 seconds to 35 seconds during playback. Whatever values you add here will apply to all videos with which the LiveRail ad manager is associated.
Note: The Tracking Pixel URL field is not relevant for the LiveRail ad manager integration. Leave this field blank.

Step 2: Assign the LiveRail Ad Set to an Asset or Multiple Assets

You can assign an ad set to an asset or multiple assets using the Backlot UI, Player API, or Backlot API.

Backlot UI: For instructions on how to assign your LiveRail ad set to a single asset, see Managing Monetization. For instructions on how to assign your LiveRail ad set to multiple assets, see Bulk Applying Settings.

Player API: With the Player API you can only associate an ad set with an asset on your web page. To associate an ad set with an asset on multiple players you must replicate the code for each player. To associate an ad set with an asset using the Player API, see Assigning Ad Sets Dynamically.

Backlot API: With the Backlot API you can associate an ad set with an asset more concretely. That is, when you associate an asset with an ad set using the Backlot API the asset and the ad set will be paired together on any player and page you play the asset on. To associate an asset with an ad set using the Backlot API, see Associate Ad Set with Asset.

Step 3: Assign Targeting and Run-Time Parameters

The Liverail ad manager uses run-time parameters to enable content targeting. As an example, you could target specific ads to run only on news and sports videos. Or, you could allow only one advertiser to run on a particular set of videos -- maybe Ford bought all the ad space (“inventory”) on car-related videos, for instance. The run-time parameters are identifiable by the prefix "LR_" and can be added via Backlot or directly to your web page.

To see a full list of available run-time parameters, go to LiveRail's Support Center.

Note: The LiveRail ad manager automatically ingests and passes the following LR_params with every ad request:
  • LR_TITLE
  • LR_PUBLISHER_ID
  • LR_VIDEO_ID

LR_ADMAP

The standard way for defining when ads should play in video stream is by using the Liverail run-time parameter LR_ADMAP. Full details on the format for this key/value pair are available in LiveRail's Support Center.

The syntax for LR_ADMAP is LR_ADMAP=Type:Inventory_scenario_id:Time.

Variable Input Based on Use Case
Type

For in-stream ads, set to "in".

For overlay ads, set to "ov".

Inventory_scenario_id The id value associated with a specific scenario.
Time

For in-stream ads, set to "n", where n is either the number of seconds or the percentage of time into the content. Ex: LR_ADMAP=in:test_scenario:100%. Ex: LR_ADMAP=in::0

For overlay ads, set to "n;m", where n is either the number of seconds into the content or percentage of time to start into content and m is either the number of seconds or percentage of time into content to stop the overlay. Ex: LR_ADMAP=in::0;in::100%

Add Parameters via Backlot UI

In order for Custom metadata to be used as LiveRail runtime parameters, you will input the parameters as custom metadata key/value pairs on the Custom Metadata subtab on the MANAGE page for each asset. The 'Use Custom Metadata' dropdown needs to be set to 'Yes' on the LiveRail Ad Set associated to the videoFor instructions on how to add custom metadata to assets in Backlot, see Adding Custom Metadata in the User Documentation.

This example shows targeting parameters you could input to target specific ads to run only on sports an news videos.

When the LiveRail ad manager is loaded, it automatically includes all of these custom metadata values when making subsequent ad requests. You can define which ads run where by creating ad targeting rules on the LiveRail platform.

Integrate the LiveRail Ad Manager with the Ooyala Player via Player Embedded Parameters

Note: Ad sets that are loaded at the page level will override the ad set associated with the asset in Backlot.

Load LiveRail Ad Manager with OO.Player.create

To load the ad manager programmatically, use OO.Player.create. See Assigning an Ad Set with OO.Player.create for instructions on how to use OO.Player.create.

Here is a short example of how to load the LiveRail ad manager programmatically:
  var videoPlayer =
  OO.Player.create("playerwrapper", "embed_code", {
    height: "100%",
    width: "100%",
    "liverail-ads-manager": {
        ...
    }
  });        

Here is a more robust example of LiveRail integration with the Ooyala Player on your web page. The player_branding_id of a player and the embed code of an asset can be found in the Embed tab on the MANAGE page of Backlot (the player_branding_id is in bold and the embed code is italicized in this example).

<html>

<head>
  <script src="http://player.ooyala.com/v3/1217310cfc944c6abc338a459554666"></script>
</head>

<body>
  <div id="ooyalaplayer" style="width:640px;height:360px"></div>
  <script>
    OO.ready(function () {   
      OO.Player.create("ooyalaplayer", "MxcTUxNTplNGXE5aAnKFdon1e6h9CB_a", {
        "liverail-ads-manager": {
          "LR_PUBLISHER_ID": "1331"
        },
        onCreate: function (player) {
            ...
        },

      }); 
    });
  </script>
</body>

</html>

Add Parameters Directly to Your Web Page

To add additional LiveRail run-time or targeting parameters directly to your web page, use OO.Player.create. See Assigning an Ad Set with OO.Player.create for instructions on how to use OO.Player.create.

Here is an example of adding additional LiveRail run-time parameters programmatically:
<script>
  OO.ready(function () {
    OO.Player.create("container", EMBED_CODE, {
      "liverail-ads-manager": {
        LR_PUBLISHER_ID: "1331",
        LR_TAGS: "demo",
        LR_ADMAP: "in::0;in::100"
      }
    });
  });
</script>        

LiveRail and Mobile

To serve ads using LiveRail for mobile environments, you should download your LiveRail account VAST tag from your LiveRail account. The tag will look something like this:

http://ad4.liverail.com/?LR_ORDER_ID=12345&LR_ORDER_LINE_ID=345677&LR_PUBLISHER_ID=13517&LR_SCHEMA=vast2&LR_URL=[URL]

This tag is effectively a VAST wrapper, meaning that it will make an ad request to LiveRail, and LiveRail will make subsequent ad calls to whatever ad sources you have defined in your LiveRail account. Once you’ve downloaded the VAST tag, you should integrate it into your mobile app environment(s) using our Ooyala mobile SDKs. For more information about VAST, see Integrating VAST Ads with Player V3. See Ad Set Fields for LiveRail for descriptions of the fields you can input when creating a LiveRail ad set with VAST.

Was this article helpful?