Pulse SDKs 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 at http://pulse-sdks.videoplaza.com.

SDK initialisation

The Pulse SDKs perform most of the logic needed for a successful integration between your video player and 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 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:
    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 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 our personnel. An incorrect device container value can result in no ads being served or incorrect ad delivery and reports.

  • persistent identifier: The persistentId is used to identify the end user and is the basis for frequency capping, uniqueness, DMP targeting information and more. For more information, see Persistent identifier (PID).

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 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
Note: The height and width parameters are mandatory in case you use the sell-side platform in Pulse. In addition, when integrating an application with one of our mobile SDKs and using the sell-side platform in Pulse, then the sell-side platform parameters are also mandatory.
  • height: The height of the video player. This is used to determine the best size of the delivered media files.

    This parameter is generally optional, but is mandatory in case you use the sell-side platform in Pulse.

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

    This parameter is generally optional, but is mandatory in case you use the sell-side platform in Pulse.

  • 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 bandwidth 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, see 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 Identifier 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.
  • General Data Protection Regulation (GDPR) parameters:
    • GDPR: This parameter is to indicate that an ad request is subject to GDRP regulations.
    • GDPR personal data: This parameter is to indicate if the ad request 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.
  • Timeout parameters: there are three timeouts, which apply to all ad requests, set by the Account Manager when first setting up your account. The following parameters, all expressed in amount of seconds, allow you to override these timeout settings.
    • Start ad timeout: This parameter indicates the maximum amount of time the player or integration should wait for the ad to start playback before reporting inventory.
    • Third-party timeout: This parameter indicates the maximum amount of time the player or integration should wait to unwrap and load a third-party ad before reporting inventory.
    • Total passback timeout: This parameter indicates the maximum amount of time the passback player should wait to find a working ad in the passback chain before moving to the last ad in the chain or reporting inventory.
  • mid-roll break number: This parameter allows you to override the number of the mid-roll ad break targeted by the ad request, in order to request mid-roll ads from goals targeting a specific mid-roll ad break. The value of this parameter is a positive integer, where 1 marks the first mid-roll ad break.
    Note: This feature applies to mid-roll ad breaks only and needs to be enabled for your account. Contact your Account Manager if you want to use the Mid-roll Break Targeting feature. Enabling the Mid-roll Break Targeting feature also allows you to use the Advanced Mid-roll Break Management feature.

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 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.

  • account custom parameters: Account custom parameters allow you to request ads targeted to specific values of the account custom parameters defined for your account. The parameter is structured as a key-value pair in the form of acp.paramName=value. In the content metadata object, you provide the paramName which needs to match the ad request parameter name defined for your Pulse account.

    You can only pass in one value for each of the account custom parameters defined for your account. The account custom parameter values cannot contain any spaces or any of the following characters: comma (,), semicolon (;), double quote/quotation mark ("), single quote/apostrophe ('), backslash (\), pipe (|), tilde (~), or ampersand (&). For more information, see Account custom parameters.

    Note: If your account custom parametes are set as Required in ad request, then all ad request URLs must contain the acp.paramName parameter for each of the account custom parameters where you selected this as required, otherwise the request fails.