Ad Sets

Ad sets are ad configurations that control the ad experience of an asset during playback.

Note: For more information about Backlot REST API commands, see the Backlot API Reference.
The ad set routes create, delete, and change the names of ad sets and assign ad sets to assets. All other ad behavior must be defined in the Backlot UI.

Create Ad Set

[POST]/v2/ad_sets{  
   properties
}

Add an Ad to Ad Set

[POST]/v2/ad_sets/ad_set_id/ads{
   properties
}

List Ad Sets

[GET]/v2/ad_sets

Get Ad Set

[GET]/v2/ad_sets/ad_set_id

Modify Ad Set

[PATCH]/v2/ad_sets/ad_set_id{  
   properties
}

Delete Ad Set

[DELETE]/v2/ad_sets/ad_set_id

Remove Ad from Ad Set

[DELETE]/v2/ad_sets/ad_set_id/ads/ad_id

Route Attributes

The following table describes all attributes that can be expressed through the route.

Route Attribute Description
ad_id The ID of the ad.

Type: String

Default: None

Example: da1c1a4bd90c48c39d7ce3e8347bd758

ad_set_id

The ID of the ad set. To get a list of ad sets, perform a get against the /v2/ad_sets route.

Type: String

Default: None

Example: /ad_sets/IzNnllMjphu2XF3_UgPROoCi9B2BwtSg

Properties

The following table describes all properties that can be associated with an ad set.

Property Description Required?
default

If ‘true’ then this ad set is automatically applied to videos added to your content library. Only one ad set can have this field set to ‘true’.

Type: String

Valid Values: true | false

Example: "true"

Yes
id Ad set's unique identifier.

Example: "Erk3j4k98dh34kshdjf892kjvmF7Diew"

Yes
name Name of your Ad Set.

Type: String

Example: "asset"

Yes

The following table describes all properties that can be associated with an ad.

Property Description Required?
ad_source

Source of ad.

Type: String

Valid Values: assets | ad_network_id. See "Supported Ad Providers" below for a list of the supported ad providers.

Default: video

Example: "video"

Yes
ad_type

Type of ad.

Type: String

Valid Values: preroll | postroll | midroll | cuepoint

Note: cuepoint is not a valid value for the Google IMA V3 ad source. To associate your DFP ad rules with your Google IMA V3 ad, use "ad_type": "rules".

Default: asset

Example: "preroll"

 
click_url

URL where to redirect the user when they click the ad.

Type: String

Default: None

Example: "http://www.myclickurl.com"

Yes
duration

Indicates the length of your ad in milliseconds.

Type: String

Default: None

Conditions: ad_source set to “assets”

Example: "My Movie"

Conditional
embed_code

Identifier of asset used as your ad.

Type: Integer

Default: None

Conditions: ad_source set to “assets”

Example: "01M2F0MTr3SWBB9dfAPT5xEsg8Gpy-jP"

Conditional
id String that uniquely associates an ad with an ad set.

Type: String

Valid Values: assets | ad_network_id

Default: video

Example: "video"

Yes
name

Identifier of asset used as your ad.

Type: Integer

Default: None

Conditions: Required for videos.

Example: "10000"

Conditional
plays_before

Ad is first shown after the first x plays.

Type: Integer

Default: None

Example: "3"

Yes
plays_between

Ad is first shown every x plays.

Type: DateTime

Default: None

Example: "3"

No
position

Indicates when the ad will be played during your movie.

Type: String

Default: None

Conditions: ad_source set to “midroll”

Example: "3000"

Conditional
position_type

Indicates whether the position is measured in milliseconds or a percentage of movie duration.

Type: String

Valid Values: milliseconds | percent

Default: None

Conditions: ad_source set to “midroll”

Example:

Conditional
tag_url

URL to the XML file containing your ad tag.

Type: String

Default: None

Conditions: applies to third-party ads.

Example: "http://cdn.mycdn.com/mytag2.xml"

Conditional
tracking_pixel_url

This URL is pinged whenever the ad is played.

Type: String

Default: None

Example: "http://www.mytrackingpixel.com"

No

This example creates an ad set:

[POST]/v2/ad_sets{  
   "name":"My new Ad Set",
   "default":true
}

Backlot returns a response similar to the following:

{  
   "default":"true",
   "id":"ed4a4c6abdfc4ab8aa3e7b8a05f31ec6",
   "ads":[  

   ],
   "name":"My new Ad Set"
}
Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. To launch the Scratchpad, go to Ooyala API Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad.

This example adds an ad to an ad set:

[POST]/v2/ad_sets/ed4a4c6abdfc4ab8aa3e7b8a05f31ec6/ads{  
   "ad_source":"assets",
   "ad_type":"preroll",
   "embed_code":"01M2F0MTr3SWBB9dfAPT5xEsg8Gpy-jP",
   "plays_before":0,
   "plays_between":1,
   "click_url":"http://www.myclickurl.com",
   "tracking_pixel_urls":[  
      "http://www.mytrackingpixel.com"
   ]
}

Backlot returns a response similar to the following:

{  
   "click_url":"http://www.myclickurl.com",
   "ad_type":"preroll",
   "id":"da1c1a4bd90c48c39d7ce3e8347bd758",
   "tracking_pixel_urls":[  
      "http://www.mytrackingpixel.com"
   ],
   "ad_source":"assets",
   "embed_code":"xkdG43NjrlM92YJ1HzaqiWQ3SZpO5da7",
   "name":"bleebleblobble 2.mov",
   "duration":"5038"
}
Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. To launch the Scratchpad, go to Ooyala API Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad.

Actively Supported Ad Providers

Ooyala actively supports the following ad providers. These ad integrations are developed and maintained by the Ooyala engineering team.

  • Ooyala Pulse (formerly known as Videoplaza)
  • FreeWheel
  • Google IMA V3
  • LiveRail
  • VAST 2.0
  • VAST 3.0 (Player V4 only)
  • VPAID 1.0 (Player V3 and Player V4 with Google IMA only)
  • VPAID 2.0 (Player V4 only)

Supported Ad Providers

Ooyala supports the following ad providers. These ad integrations are developed and maintained by a team at Ooyala or third party developers.

  • Adapt.tv
  • Tremor
  • Yahoo

Legacy Ad Providers

The following ad providers were previously supported but are no longer actively updated. These modules still exist and the functionality is still there, but Ooyala does not actively update and test these integrations.

  • Adify (In-Stream)
  • AdTech (In-Stream, Overlay, Companion)
  • Atlas (In-Stream, Companion)
  • Brightroll (In-Stream, Companion)
  • CBSi (In-Stream)
  • DART Enterprise
  • DoubleClick (via Google IMA V3 ad source)
  • Google AdSense (via Google IMA V3 ad source)
  • Lightningcast (In-Stream, Companion)
  • Open AdStream (In-Stream, Overlay, Companion)
  • OpenX (In-Stream, Overlay)
  • ScanScout (In-Stream)
  • SpotXchange (In-Stream, Companion)
  • TV2N (In-Stream)
  • YuMe*

*YuMe is now a third party provider of ads that will use Backlot VPAID modules. YuMe now uses the VPAID OPF module for Flash players. For a guide on how to handle the migration, see Migrating from YuMe to VPAID Ad Source.

Was this article helpful?