Parameter Reference

This page describes the configuration options available in the Pulse SDKs and what they are used for. This should be used as a complement to the reference and implementation documentation available for the SDKs.

SDK Initialisation

The Pulse SDKs perform most of the logic needed for a successful integration between your video player and Ooyala Pulse for ad serving. When the SDK has been initialised successfully, it parses Pulse responses into native objects for easy use and manages the tracking of the correct ad event URLs for a given ad in HTML5, iOS and Android.

The SDK is initialised with the following parameters:
  • host URL: When the SDK is initialised, the host for the Ooyala Pulse account must be provided. This is used to identify which Pulse account to request ads from. The host is derived from the "sub-domain” found in the Pulse UI and is formulated like this:
    http://[sub-domain].videoplaza.tv
    Note: The host URL may use the https protocol, but only in case HTTPS is enabled on your account. Verify with your Account Manager that this is the case before doing so.
  • 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 third party cookies, such as iOS and Android native applications, this automatic id management does 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 devices and reuse DMP tracking data across devices and platforms.

    In case you set the persistent ID to the nil UUID (00000000-0000-0000-0000-000000000000), then Pulse does not take any personally identifiable information (PII) into account for campaign and ad selection, no cookies are returned from Pulse, and all ad requests to Pulse are considered under the same conditions as when the viewer has set 'Do Not Track' in their browser. For more information, see What Are the Requirements for Uniqueness Tracking? and 'Do Not Track' Setting in Browsers.

Request Setting

The previous section covered player specific settings and should never change for any 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.

These settings should be updated when the ad request's technical conditions change. The request setting values are configured in the object:
  • RequestSettings (HTML5)
  • OORequestSettings (iOS)
  • RequestSettings (Android)
The request settings object contains the following parameters:
Note: The height, width, max bandwidth, and asset filtering parameters all affect the media file references returned for an ad, but the used SDK also automatically sends in the platform information (HTML5, iOS, or Android) to Pulse. Based on the platform, only certain media files are made available. To get an indication of default media file sizes and bit rates for different platforms and devices, see Defaults for Bandwidth, Width, and Height
  • height: The height of the video player. This is used to determine the best size of the delivered media files.

  • width: The width of the video player. This is used to determine the best size of the delivered media files.

  • max bandwidth: The maximum bandwidth in Kbps that your device has access to.

    The HTML5 Pulse SDK has built-in functionality to detect the bandwidth, but can be overridden when you set your own value. The Android and iOS Pulse SDKs do not perform any bandwidth tests, because we do not want to 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. However, you should only set maximum bandwidht if you have a reliable way of determining the actual available bandwidth.

  • 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 (AAID) for Android or the Identfier for Advertising (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 and iOS). 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: Enable or disable the addition of the [CACHEBUSTING] macro to tracking URLs in third 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.

  • VAST skip offset: This parameter only applies to the HTML5 SDK. Enable or disable using the skip offset defined in third party VAST tickets over using the skip offset defined in the insertion policies in Pulse. By default, the skip offset from Pulse is used.

  • seek mode: Set how the session behaves when a viewer seeks or scrubs past one or more mid-roll ad breaks. The different modes allow you to ignore any scrubbed ad breaks (default), play all scrubbed ad breaks, play only the first scrubbed ad break, or play only the last scrubbed ad break.

  • live: This parameter identifies the request to be specifically for a live event, where you expect high volumes of concurrent viewers. It enables you to turn off certain tracking, secondary lookup requests, real-time bidding requests, and/or cookie syncing, to ensure the high volumes of ad delivery and subsequent tracking to go smoothly, and to increase your revenue and viewer retention.
    Note: If you are using a third party company to stitch ads into any of your live content, then they must incorporate this parameter in the requests they send to Pulse on your behalf.
    Note: The live parameter does not interfere with or override any specific tracking you have set with the st parameter.
    Note: Any external trackers, set globally or for the ad specifically, are not affected by this parameter, and are always included in the response. However, you may want to disable some of this tracking, to avoid flooding your own or third party servers with requests when a high concurrency live event is in progress. It is recommended to turn off global trackers on the campaigns set up for your live events. See Campaign Overview and Global Tracking for more information on global trackers.
    The following options are available:
    • DISABLE_ALL (default if an empty list is set): This turns off:
      • all tracking, except for impression and click-through tracking,
      • session lookup requests, which affects frequency capping rules,
      • location lookup requests, which disables selection of any campaigns and goals with geo targeting, and disables reporting on location,
      • real-time bidding requests and their associated cookie syncing.
    • ALL_TRACKINGS: This turns off everything else except all tracking.
    • SESSION_LOOKUP: This turns off everything else except session lookup requests.
    • LOCATION_LOOKUP: This turns off everything else except location lookup requests.
    • REAL_TIME_BIDDING: This turns off everything else except real-time bidding requests and their associated cookie syncing.
    Warning: You should never send all parameters at once, because it is as if the live parameter was not set. This means no action is taken because DISABLE_ALL turns off everything and other parameters re-enable everything.
  • GDPR parameters:
    • GDPR: This parameter is to indicate that an ad request is subject to GDPR regulations.
    • GDPR personal data: This parameter is to indicate if the ad request's URL parameters contain any personal data. The only location where you can enter personal data in the request is through the custom parameters of the content metadata settings.

Content Metadata Settings

This 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)
  • OOContentMetadata (iOS)
  • ContentMetadata (Android)
The content metadata object contains the following parameters:
  • 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 third party trackers and to Pulse for reporting. This value can be added to request URLs for third party ad requests or additional tracking URLs through 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
  • tags: Tags are freeform keywords that can be used for targeting and reporting purposes. Although the tags keywords are able to handle UTF-8 characters, we recommend refraining from using special characters like quotes (‘ and ") ampersand (&) comma (,) semi-colon (;).

  • custom parameters: The custom parameters are passed in as an array of key-value pairs, and may contain any information you want to pass on in the ad request. These parameters are generally used to pass information through custom macros into third party tags, external trackers and click-through URLs. For more information, see Custom macros.

https://help.ooyala.com/sites/all/libraries/dita/en/video-advertising/oadtech/ad_serving/dg/pulse_sdks_parameter.html

Was this article helpful?