Customer Sign In

upLynk

Ad Server Integration: Freewheel

Overview

Learn how to define the following FreeWheel ad configurations:

FreeWheel Ad Requests

Upon setting the Server URL parameter, our service constructs the following GET request in order to request ads for your content:

http://[customerId].v.fwmrm.net/ad/g/1?[globalParams];[keyValues];[ParamsForSlot1];[ParamsForSlot2];...;[ParamsForSlotN];

The query string for the above request is constructed according to the parameters passed to our service as described below.

  • [globalParams]: Most of the parameters described in the FreeWheel Ad Parameters section will be applied globally to all ad units.
  • [keyValues]: The Key-Value Pairs parameter (ad.kv) defines key-value pairs that may either be passed or retrieved from FreeWheel.
  • [ParamsForSlotN]: The Ad Units parameter (ad.slau) determines whether we add slot-specific parameters (i.e., [ParamsForSlot1];[ParamsForSlot2];...;[ParamsForSlotN];) to the above query string.

Ad Placement

An ad unit defines the available spaces where an ad may be inserted. Common types of ad units are described below.

Note: FreeWheel refers to ad units as slots.

  • Pre-Roll: Allows ads to be inserted prior to the start of playback.
  • Mid-Roll: Allows ads to be inserted during breaks in playback.
  • Post-Roll: Allows ads to be inserted after the end of the live stream.

Note: Insert ads into your content by adding the desired ad offsets to your live and/or on-demand content via a Slicer.

Toggling Ad Units

Ad placement is handled slightly different between live and on-demand streaming.

Live Streaming

Toggle ad units by setting the Ad Units parameter (ad.slau) to a comma-separated list of ad unit types. Only ad unit types that are defined within this parameter will be requested.

Learn more.

Example

The following value will only request mid-roll ads during this playback session of the live stream.

ad.slau=,midroll

On-Demand Content

By default, ads will be requested for pre-roll, mid-roll, and post-roll ad units.

FreeWheel Ad Parameters

This section describes parameters that our service will insert into the GET request sent to the FreeWheel ad server.

Name Parameter Required Description
Server URL ad.serverurl Required

Defines the base URL to the desired FreeWheel ad decision server.

Example: ad.serverurl=http://g1.v.fwmrm.net/ad/p/1?

Tip: A default value for this parameter may be defined from within the CMS. Take advantage of this functionality to avoid exposing your customer_id.
Learn how to set a default value for this parameter.

Note: This parameter takes precedence over the Customer ID parameter (ad.customer_id).

Location Description (Custom Site Section ID) ad.locationDesc Required

Defines a description for the playback location.

Example: ad.locationDesc=web

Learn how to set a default value for this parameter.

Note: This parameter takes precedence over the Custom Site Section ID parameter (ad.csid).

Network ID ad.nw Required

Sets the distributor’s FreeWheel network ID (i.e., adRequest@networkId).

Example: ad.nw=14611

Learn how to set a default value for this parameter.

Player Profile ad.prof Required

Sets the player's profile (i.e., adRequest@profile).

Example: ad.prof=14611:Vod

Learn how to set a default value for this parameter.

Pre-Roll Duration ad.predur Required (Live Streaming Only)

Sets the duration, in seconds, of a live stream's pre-roll ad unit.

Example: ad.predur=45

Duration ad.rdur Optional

Defines a default duration. This duration is only applicable for ad breaks without an explicitly defined duration.

Default Value: 240

Example: ad.rdur=120

Minimum Duration ad.mind Optional

Sets the minimum duration, in seconds, for mid-roll ad units within a live stream. This duration is only used when the duration of the ad unit is unknown.

Example: ad.mind=15

Default Value: The default minimum duration is set by the Duration parameter (ad.rdur). If it is not set, then the default duration is determined by the duration passed to the Live Slicer.

Maximum Duration ad.maxd Optional

Sets the maximum duration, in seconds, for mid-roll ad units within a live stream.

Note: This parameter only supports integers.

Example: ad.maxd=50

Default Value: By default, the maximum duration is the duration passed to the Live Slicer.

Use Live Break Duration ad.ulbd Optional

Sets ad unit duration for on-demand content to the duration defined when the source live stream was sliced. Set this parameter to 1.

Example: ad.ulbd=1

Mode ad.mode Optional

Overrides the default request mode (i.e., adRequest@mode) for ad units.

Valid values are:

  • live
  • ondemand

Syntax:

  • Live Streaming: ad.mode=[Pre-Roll Ad Units],[Mid-Roll Ad Units]

    Default Value: live

    Example: ad.mode=ondemand,live

    Note: If this parameter only defines a single mode, then that mode will be applied to all ad units.

  • On-Demand Content: ad.mode=[All Ad Units]

    Default Value: ondemand

    Example: ad.mode=live

Learn how to set a default value for this parameter.

Flags ad.flags Optional

Enables flags that define the player's capabilities.

  • Append Flags: Enable the default set of flags along with additional flags by setting this parameter to the desired set of flags.

    Example: ad.flags=+play+sync

  • Specified Flags Only: Only enable specific flags by setting this parameter to a colon followed by the desired set of flags.

    Example: ad.flags=:+amcb

    Note: The Advanced Callbacks parameter (ad.ametr) determines whether FreeWheel will use impressions with advanced callbacks instead of quartile callbacks. If you choose to only enable specific flags, then the Advanced Callbacks parameter will only work when you include the Advanced Callbacks flag.

Note: Please refer to FreeWheel's documentation for more information (e.g., valid flag combinations).

Default Value: +slcb+sltp+fbad+qtcb+vicb+emcr

Advanced Callbacks ad.ametr Optional

Allows FreeWheel to use impressions with advanced callbacks. Set this flag to 1.

Note: FreeWheel may not be configured to use impressions with both advanced and quartile callbacks.

Note: By default, the Flags parameter includes the Requires Quartile Callback URLs flag (qtcb). Override the default value to enable the Advanced Callback flag instead of the Requires Quartile Callback URLs flag.

Example: ad.ametr=1

HyLDA ad.hylda Optional.

Activates FreeWheel’s HyLDA feature. Set this flag to 1.

Note: Use this flag with the Acid flag.

Note: Upon enabling these flags, FreeWheel will automatically generate: aiid, abid, and abwct.

Example: ad.hylda=1

Acid ad.acid Optional

Adds Acid as a value in the HyLDA keyword.

Note: This parameter is only applicable when the HyLDA flag has been enabled.

Example: ad.acid=Acid

Default Ad Capabilities ad.metr Optional

Defines the default capabilities for all ads. Set this parameter to an integer that maps bits to capabilities.

Note: Please refer to FreeWheel's documentation on the "metr" parameter for more information.

Example: ad.metr=8

Default Value: 7

Asset Network ID ad.asnw Optional

Adds a video asset network ID (i.e., videoAsset@videoAssetNetworkId) to the FreeWheel GET ad request.

Learn how to set a default value for this parameter.

Example: ad.asnw=14611k

Custom Asset ID ad.caid Optional

Sets the custom asset ID (i.e., videoAsset@customId) that will be included with the FreeWheel GET ad request.

Syntax:

  • @[Key-Value-Name]: Sends the value assigned to an asset's key-value pair to FreeWheel.

    Example: ad.caid=@custom_id

  • $[Field-Name]: Sends the value defined within an asset's metadata field to FreeWheel.

    Example: ad.caid=$my_custom_id_field

  • Custom Value: Sends a custom value to FreeWheel.

    Example: ad.caid=Asset123456

Default Value: By default, the custom asset ID sent to FreeWheel is determined by the first available value from the following list:

  1. The external ID defined in the asset's metadata (i.e., asset.ad_meta.external_id)
  2. Asset's external ID (i.e., asset.external_id)
  3. Asset ID (i.e., asset.id)
Key-Value Pairs ad.kv Optional

Passes or retrieves key-value pair(s) using the FreeWheel GET ad request.

By default, use a comma to delimit:

  • A key from a value.
  • Key-value pairs

Note: Retrieve a field value by using the "$" macro. For example, "ad.kv=genre,$genre" will attempt to retrieve the value assigned to the "genre" field for the current asset.

Note: Use the Key-Value Separator parameter (ad.kvsep) to define a different delimiter.

Example: ad.kv=key_1,value_1,key_2,value_2

Key-Value Separator ad.kvsep Optional

Determines the delimiter that must be used when defining key-value pairs through the Key-Value Pairs parameter.

Example: ad.kvsep=/

Default Value: ,

Site Section Network ID ad.ssnw Optional

Sets the site section network ID (i.e., siteSection@siteSectionNetworkId) included with the FreeWheel GET ad request.

Example: ad.ssnw=112233

Learn how to set a default value for this parameter.

Video Asset Fallback ID ad.afid Optional

Sets the video asset fallback ID (i.e., videoAsset@fallbackId) included with the FreeWheel GET ad request. This ID is used when an ad request's video asset ID is not recognized.

Example: ad.afid=AssetFallBackId

Learn how to set a default value for this parameter.

Visitor Custom ID ad.vcid Optional

Sets the visitor's custom ID included with the FreeWheel GET ad request. This ID is the equivalent to the visitor/@customId attribute in the XML request.

Example: ad.vcid=CustomVisitorID

Learn how to set a default value for this parameter.

Note: This parameter takes precedence over the End-User ID parameter (ad.euid).

Site Section Fallback ID ad.sfid Optional

Sets the site section fallback ID included with the FreeWheel GET ad request. This ID is used when an ad request's site section ID is not recognized.

Example: ad.sfid=global

Learn how to set a default value for this parameter.

Pre-Roll Ad Unit ad.preroll Optional

Requests a pre-roll ad unit. Set this parameter to 1.

Example: ad.preroll=1

Default Value: 0

Ad Units ad.slau Optional

Determines whether pre-roll, mid-roll, and post-roll ad units will be requested from FreeWheel.

Valid values are:

  • preroll
  • midroll
  • postroll

Usage information:

  • Live Stream: Set this parameter to a comma-separated list of the desired types of ad units.

    Syntax: ad.slau=[Pre-Roll Ad Units],[Mid-Roll Ad Units],[Post-Roll Ad Units]

    Default Value: By default, the type of ad unit that is requested is determined by its position within the live stream.

    Use this parameter to:

    • Request Ad Units: Each type of ad unit defined in the above parameter will be requested from FreeWheel. Leave an ad unit type blank to prevent it from being requested.

      Example: ad.slau=preroll,midroll,

      Note: In this example, post-roll ad units will not be requested.

    • Mapping Ad Unit Types: This parameter maps each type of ad unit that will be requested from FreeWheel.

      Example: ad.slau=midroll,midroll,postroll

      Note: In this example, a mid-roll ad unit will be requested instead of a pre-roll ad unit. Mid-roll and post-roll ad units will be handled normally.

  • On-Demand Content: By default, pre-roll, mid-roll, and post-roll ad units are requested from FreeWheel.
Response Format ad.resp Optional

Sets the response format (i.e., adRequest@responseFormat).

Valid values are:

  • vast3
  • vast2
  • vmap1
  • smrx

Example: ad.resp=vmap1

Asset Duration ad.vdur Optional

Overrides an asset's duration (i.e., videoAsset@duration).

Example: ad.vdur=3600

Default Value: By default, this duration is determined by the CMS asset.

Tag (FreeWheel Ad Request) ad.tag Optional

Sets a FreeWheel GET ad request URL that will be used instead of a POST Smart XML request.

Example: ad.tag=http://demo.v.fwmrm.net/ad/g/1?flag=+emcr+slcb+sltp&nw=96749&prof=global-as3&csid=CBPTestSite.02&caid=[CUSTOM_ASSET_ID]&vdur=[VIDEO_DURATION]&resp=xml;module=DemoPlayer&feature=simpleAds;

Primary Content Type ad.prct Optional

Defines a global primary content type for all non-temporal, user-generated ad units.

Note: Override this global value for a specific ad unit by assigning it a primary content type.

Example: ad.prct=text/html_lit_js_wc_nw

Default Value: text/html_lit_js_wc_nw

Client IP Address ad.vip Optional

Overrides the client's IP address that will be included with the FreeWheel GET ad request.

Note: This parameter is typically used for testing.

Example: ad.vip=192.168.1.1

Default Value: The IP address of the device that requested the playback of your content.

Client Referrer ad._fw_h_referer Optional

Overrides the Referer header value that will be included with the FreeWheel GET ad request.

Note: This value should be URL encoded.

Example: ad._fw_h_referer=http://www.sampledomain.com

Default Value: By default, the value of the Referer header included with the playback request will be included with the FreeWheel GET ad request.

Client User Agent ad._fw_h_user_agent Optional

Overrides the value of the User-Agent header that will be included with the FreeWheel GET ad request.

Note: This value should be URL encoded.

Example: ad._fw_h_user_agent=Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.75 Safari/537.36

Default Value: By default, the playback request's User-Agent header value will be included with the FreeWheel GET ad request.

Customer ID ad.customer_id Required

Note: The Server URL parameter (ad.serverurl) takes precedence over this parameter. This parameter should not be specified if you plan on passing the Server URL parameter.

Sets the fourth-level domain, as indicated by [customerId] below, in the FreeWheel GET ad request.

FreeWheel GET ad request:
http://[customerId].v.fwmrm.net/ad/g/1

Example: ad.customer_id=demo

Note: This example configures the FreeWheel GET ad request URL to: http://demo.v.fwmrm.net/ad/g/1.

Custom Site Section ID ad.csid Required

Note: The Location Description parameter (ad.locationDesc) takes precedence over this parameter. This parameter should not be specified if you plan on passing the Location Description parameter.

Defines a description for the playback location.

Example: ad.csid=web

End-User ID ad.euid

Note: The Visitor Custom ID parameter (ad.vcid) takes precedence over this parameter. This parameter should not be specified if you plan on passing the Visitor Custom ID parameter.

Sets the custom visitor ID included with the FreeWheel GET ad request. This ID is the equivalent to the visitor/@customId attribute in the XML request.

Example: ad.euid=CustomVisitorID

Enabling FreeWheel Video View Feature

The parameter to enable FreeWheel's Video View by Callback feature differs depending on which version of the ping API will be used. This feature requires that you use the upLynk preplay and ping API's.

If using version 3 of the ping API (the current version), you need to add 2 to the value of the ad.pingf parameter in your preplay request. (see the "Calculating the pingf Parameter" section of the Features portion of the ping API v3 document.

If using version 2 of the ping API (past version), you need to include the ad.svv=1 param to your preplay request.

This feature also requires that you use the Smart XML response type as Video Views are not supported by VAST.

FreeWheel Creative Parameters

An ad response sent by FreeWheel may include creative parameters, such as the ones listed below:

  • _fw_ad_position_in_pod
  • _fw_ad_title
  • _fw_ad_unit_name
  • _fw_advertiser_name
  • _fw_asset_thumbnail_url
  • _fw_campaign_name
  • _fw_creative_name
  • hulu_industry
  • moat

Creative parameters provided with an ad response are automatically included in preplay and ping responses to the client. The client may then leverage these parameters for use with a custom integration (e.g., Integration of FreeWheel with Moat Analytics).

Ad Configuration

An ad configuration allows you to define default values for use with third-party ad servers (e.g., FreeWheel).

Define an ad configuration by performing the following steps:

  1. Navigate to the Ad Server page by clicking the tab and then selecting Ad Server from the side navigation tab.
  2. Click + Ad Config.
  3. In the Ad config name option, type the name that will be assigned to your ad configuration.
  4. From the Select ad server option, select "FreeWheel."
  5. Click Create
  6. In the serverURL option, type your FreeWheel GET ad request URL.
  7. In the networkID option, type the distributor’s FreeWheel network ID (i.e., adRequest@networkId).
  8. Define default values for any other desired FreeWheel parameters.
  9. Click Save.