Ooyala Video Advertising SDK Parameter Reference
The Ooyala Pulse Integration Toolkit SDKsThe Ooyala Pulse Integration Toolkit SDKs add support for requesting ads from the Ooyala Pulse Ad server, parsing the response into native objects for easy use and managing the tracking of the correct ad event URLs for a given ad in HTML5, iOS and Android. The naming conventions and some of the techniques used are aligned with the coding convention of their respective platform and may vary slightly. Coding conventions aside, the individual modules that comprise the SDKs provide the same assistance and manage the same basic set of information.
The AdCall / AdRequestor / AdRequester ModuleThe main module that manages the requesting and parsing of ads utilises three settings objects to compose the final ad request to the Pulse ad server. I will describe each settings object and their importance below. The main ad requesting module is called the following on the different platforms:
- adCallModule (HTML5)
- VPAdCallModule (iOS 1.x) or VPAdRequester (iOS 2.x)
- AdRequestor (Android 1.x) or AdRequester (Android 2.x)
General Configuration of the AdCall / AdRequestorThere are additional, optional, settings that can be applied to each ad request. The SDK holds these setting in a custom object that is applied to the ad requesting module.
- VPAdCallModuleSettings (iOS 1.x) or passed in as parameters for initialising the VPAdRequester (iOS 2.x)
- AdRequestorSettings (Android 1.x) or passed in as parameters for initialising the AdRequester (Android 2.x)
device container: The device container in Ooyala Pulse is used for targeting and reporting purposes. This device container attribute is only used if you want to override the Pulse device detection algorithm on the Pulse ad server. This should only be set if normal device detection does not work and only after consulting Ooyala personnel. An incorrect device container value can result in no ads being served or incorrect ad delivery and reports.
persistent identifier: The persistent identifier is used to identify the end user and is the basis for frequency capping, uniqueness, DMP targeting information and more. Ooyala will normally generate and attempt to save a persistent ID as a cookie on your device. In environments that do not support 3rd-party cookies, such as iOS and Android native applications, this automatic id management will not work and it is then up to the integration to provide an id that is consistent for the individual end user and that persists between sessions.
This ID can be any string as long as it is unique to each individual end user, although the GUID or UUID format is recommended. If the application has a login or other user id that is consistent across devices, this ID can be used to track uniqueness across device and reuse DMP tracking data across devices and platforms.
The previous section covered player specific settings and should never change for any one individual user over time. This section covers the technical conditions surrounding the actual ad request.
The Ooyala Pulse ad server has a built-in asset selection algorithm that attempts to select the best possible video creative for your device. Pulse uses device detection to determine the best codec for your device and these request setting values are key for determining the best size and weight of the video creatives for your particular situation.
- requestSettings (HTML5)
- VPRequestSettings (iOS 1.x and 2.x)
- RequestSettings (Android 1.x and 2.x)
height: The height of the video player. This is used to determine the best size of the delivered asset.
width: The width of the video player. This is used to determine the best size of the delivered asset.
max bandwidth: The maximum bandwidth in Kbps that your device has access to. You should only set this value if you have a reliable way of determining the actual available bandwidth. If you do not set anything here we will default to 400 Kbps.
The Ooyala Pulse HTML5 and mobile SDKs, by design, do not perform bandwidth tests because there is no reliable generic way to do this on HTML5 and we do not want consume unnecessary data volume on mobile devices. For this reason it is up to the individual developer to implement bandwidth detection if they choose to.
The one exception to this is Ooyala Video Advertising iOS 1.x SDK (not available in version 2.x). iOS has a reliable way of detecting if the device has access to WiFi, so if we detect that it is connected to WiFi, we will perform a bandwidth test for you. Explicitly providing a max bandwidth in the request settings will override any measured values.
insertion point type: This is the point, in relation to the main content, where the ad spot should be inserted. This will determine what type of ads are requested by the SDK. The insertion point types are defined as constants in the SDKs and are as follows:
On before content: Linear ads that are played before the main content starts (Pre-rolls).
On content end: Linear ads that are played after the main content has ended (Post-rolls).
On playback position: Linear ads that are to be displayed at a certain point on the main content's timeline (Mid-rolls). This value requires that you also set the playback position (see playback position).
On pause content:Linear ads that are played when the content is paused.
On playback time: This is for non-linear ads that should be displayed after the user has viewed the main content for X seconds (Overlays).
playback position: This is the point on the main content timeline, in seconds, that the "on playback position" (Mid-roll) ad slot should be displayed. A warning may be triggered if this value is higher than the duration of the main content.
referrer URL: To override the URL from where the ad requests originate in the HTTP header's referrer property.
max break duration: Set the maximum duration for a linear ad break in seconds. For more information about this feature and its limitations, refer to Time Based Breaks.
- sell-side platform parameters: These parameters only apply to our
mobile SDKs (Android 2.x and iOS 2.x), and are mandatory in case you use the
sell-side platform in Pulse:
- advertising ID: the Google advertising ID for Android or the IDFA for iOS.
- application name: the name of your application.
- application version: the version of your application.
- application bundle: the bundle ID of your application, which has the format com.domainname.applicationname for both Android and iOS applications.
- application ID: the ID of your application. For Android apps, this parameter is the same as the application bundle. For an iOS app, this parameter is the Apple Team ID followed by the application bundle, for example, A1B2C3D4E5.com.domainname.applicationname.
- store URL: the URL where you can download your application.
- asset filtering: This parameter only applies to our mobile SDKs (Android 2.x and iOS 2.x). Enable or disable asset filtering based on the viewer's user agent. If you disable asset filtering, you receive references to all media files available for an ad, even those that may not be suitable for playback. By default, asset filtering is enabled.
- cache busting: This parameter only applies to our mobile SDKs (Android 2.x and iOS 2.x). Enable or disable the addition of the [CACHEBUSTING] macro to tracking URLs in 3rd party VAST 2.0 tickets. The macro adds a randomised number to the tracking URL each time the associated event is triggered to ensure tracking. Without the randomised number, the URL may be cached and not handled properly. By default, cache busting is enabled.
Content Metadata SettingsThis final section covers content-specific metadata. These values define the specific video content's rules, targeting options and metadata. These values are added to the metadata object:
- contentMetadata (HTML5)
- VPContentMetadata (iOS 1.x and 2.x)
- ContentMetadata (Android 1.x and 2.x)
category: The category is a string that is used to associate content with a category that has been defined for the client's account in the Ooyala Pulse UI. The value of the category can be the Pulse native ID of the category found in the Pulse UI or a human readable "alias” that has been associated with the category in the Pulse UI. Categories are used for reporting and targeting purposes in Pulse UI. It is also possible to apply individual ad policies to each category, controlling how many and what type of ads are returned.
content form: A piece of video content can be defined as either long form or short form content. Long form content can be the entire episode of a program, a full-length feature movie, or just a piece of content that is more than 10 minutes long. It is up to the client to define the threshold between short and long form. In the Pulse UI it is possible to configure individual ad policies for long and short form, adding an additional ad policy dimension to a category.
content ID: Content ID is used for forwarding the ID of the main content to 3rd-party trackers. This value is not used or tracked by Ooyala Pulse but can be added to request URLs for 3rd-party ad requests or additional tracking URLs via a placeholder macro in the Pulse UI.
content partner: The content partner is used to add an additional reporting dimension to the ads that are displayed. The content partner value can use the Pulse native ID of the content partner found in the Pulse UI or a human readable "alias” that has been associated with the content partner in the Pulse UI.
duration: This is the total duration of the main content.
flags: The flags are used to apply special rules and conditions to an ad request. For example, a piece of premium content has been sponsored and no pre-rolls should be displayed. Adding the flag "noprerolls” will prevent pre-rolls from being returned but mid-rolls and post-rolls will be available as normal.Supported flags are:
- nocom: No ads are returned at all
- noprerolls: No pre-rolls are returned
- nomidrolls: No mid-rolls are returned
- nopostrolls: No post-rolls are returned
- nooverlays: No overlays are returned