SSAI User Guide for VOD Assets

This document describes how to use SSAI for VOD assets for the two Ad Servers supported by Ooyala’s SSAI offering - Pulse and DFP. For information on integrating SSAI with the Ooyala Live stream, please see here. For an end-to-end guide to SSAI, please see here.

Step-by-Step Guide for VOD SSAI with DFP Ad Server

Complete the following steps to use Server Side Ad Insertion (SSAI) on your customer content with DFP Ad Server.



You can enable the SSAI service for all assets in a Backlot account, or on a per-asset basis. The initial enablement of the SSAI service must be completed by the Ooyala team.

  1. Make a request with Ooyala to enable SSAI VOD.
  2. Make sure to specify whether you need account level enablement or asset level enablement in your enablement request.
    • If you are requesting asset-level enablement, you must also provide a value for ssai_vod_enabled custom metadata for the desired assets for SSAI in order to enable SSAI for these assets. If you leave this value empty, SSAI is disabled by default for the respective asset(s). The allowed values are TRUE or FALSE.
    • If you are requesting provider-level enablement, all relevant assets are served up through SSAI for the providers of this content.

Onboard DFP Ad Provider

There are three ways to enable DFP SSAI for a given asset. If all three options are set for an asset, the SSAI service takes the highest priority out of the following three:

These are described in more detail below.

Ad Set Option (Priority 3)

  1. Click the Monetize tab inbacklot.
  2. Click New to create a new Ad Set. Select Google IMA V3 as Ad Source:

  3. Ad Tag is the tag url obtained from DFP and is used to retrieve ads.
  4. Your DFP account must be whitelisted for SSAI. To do this, you must contact DFP and requesting approval. If you are not whitelisted and just want to test the functionality, make sure the tag url contains &ss_req=0 at the end of the query string. With this setting, however, impression counts and geo targeting might not function correctly.
  5. The DFP Ad tag request call should return VAST. Information on how to manually create this tag can be found here. In addition, DFP has some tools to help create this tag.
    • The url can contain the following macros that SSAI resolves when making ad calls:
      • [timestamp]
      • [referrer_url]
      • [random]
      • [cache_buster]
    • Ad Position is used to select the position where these ad(s) will be inserted. Currently, Ad Rules is not supported.
    • When Ad Position is set to In-Stream, you must also specify when the ad should play. SSAI only supports the time option and not percent.
    • All other fields are ignored by SSAI.
    • You must add an entry for each position where you want ads inserted.
    • Once VOD content is added to Backlot, it must be associated with an Ad Set. To do this, select VOD content in Backlot and then click on the Monetize tab.

Override Ad Set with Custom Metadata (Priority 2)

After content is associated with an Ad Set, ad breaks will be inserted using information from the Ad Set. This information can be overridden by adding custom metadata.When overriding Ad Set information for DFP, one option exists.

Add a custom metadata entry with the name custom_params. This field will contain json that contains the override information. If this field exists in custom metadata, all other custom metadata is ignored.

Example data for the custom_params field:

Ad positions are in milliseconds.

 "google-ima-ads-manager": {
  "metadata": {
   "all_ads": [{
    "position": "70000",
    "tag_url": "[referrer_url]&cust_params=ibc_test_unit%3Dat&ss_req=0"
   }, {
    "position": "20000",
    "tag_url": "[referrer_url]&cust_params=libc_test_unit%3Dma&ss_req=0"
   }, {
    "position": "10000",
    "tag_url": "[referrer_url]&cust_params=ibc_test_unit%3Dsa&ss_req=0"
   }, {
    "position": "90000",
    "tag_url": "[referrer_url]&cust_params=ibc_test_unit%3Dtj&ss_req=0"

Backlot has a 2048 character limit for custom metadata fields. If the size of the json exceeds 2048 characters, you can put the data into multiple custom metadata entries using the naming convention custom_params1, custom_params2, etc. Each entry would have the same json structure with elements of all_ads array spread across the custom metadata entries.

Override custom metadata with Player Page level parameters (Priority 1)

Ad tags set in custom metadata information can also be overridden at the player page level. This method takes precedence over custom metadata.

Add a querystring entry with the name player_params. This field will contain url encoded json that contains the override information. If this field exists in querystring, all other querystring fields are ignored. An example is the same json described in the custom metadata for DFP.

Ad CMS Video Retention Policy

When the SSAI service encounters a new ad, it is downloaded from DFP server at run time. This means for the first few playback requests, the ad is not inserted while it is being transcoded to match the correct HLS bitrate of the VOD content. Ooyala’s AD CMS maintains these transcoded Ad Sets in storage.

Once an ad is transcoded, it is kept as long as the ad is being used. After seven continuous days of inactivity, the ad is deleted from Ooyala’s Ad CMS. After seven days of inactivity, if the ad is used again, SSAI service redownloads and re-transcodes it. This setting of seven days can be modified.

Step-by-Step Guide for VOD SSAI with PULSE Ad Server

SSAI VOD enabling

If you only want some of your content served up through SSAI, you can enable only the desired assets.
  • Add the ssai_vod_enabledssai_vod_enabled movie custom metadata value. If this value is empty, SSAI is disabled for this asset. Set the value to hls to enable SSAI.

Enabling ad provider

Create an Ad Set under the Monetize tab in backlot.

For AdTech(Pulse):
  • Click New to create a new Ad Set. Select Videoplaza as Ad Source.
  • Ad Position: select the desired location to insert ads.
  • vpDomain: This is the sub-domain value in your Pulse account. It should not include https:// or http://.
  • Player level midroll ad breaks is a comma delimited list of positions(seconds) within video where ads are inserted.
  • Player level tags are the Pulse tags you want to associate with the video.
  • Player level shares is the Pulse category you want to associate with the video.
  • Account ID is the account id value in your pulse account.
  • All other fields are ignored by SSAI.

Using Ad Set and/or Custom Metadata