Guide Change Log
Current Guide Version
| Guide Version | Date | Author | Description |
|---|---|---|---|
| v1 |
| Admin | Initial Release |
Historic
Table of Contents
1. Introduction
This guide outlines the steps to onboard a FW SSP client using a VAST connection to an upstream adserver such as the requisites to onboard and the technical parameters required to make HTTP GET ad requests to the Freewheel system. To set up a VAST connection to Freewheel, there will be a number of pre-requisites to full-fill and your Freewheel account team will need to share several parameters.
1.1 Integration Diagram
This diagram illustrates the end to end process of a VAST ad request leaving the adserver and Freewheel returning programmatic demand in the VAST ad response to the upstream ad server and end user
Pre-requisites
Before starting this integration, please ensure you have the following to start:
- Expected QPS volumes (daily max and average)
- Estimated traffic per geo
- Ensure ads.txt, app ads.txt and sellers.JSON are up to date
- Freewheel account team to provide:
- Expected ad request tag which will point to the dedicated client endpoint and include expected parameters (you can find an example in the section below)
- Network IDs to be integrated for ads.txt and the expected format
2. Endpoint
Clients will be provided with a unique endpoint for which to send ad requests that is exclusive to their networks. Endpoints will have a variable prefix ID which is the Network ID in hexadecimal format that will need to be included at the front of every VAST ad request. The Endpoint Prefix ID will need to be added as a prefix within the URL. As you'll see in the Parameters section below, this endpoint url will be built out to include specific parameters to pass relevant information points on the ad request.
| https://(prefixID).v.fwmrm.net/ad/g/1 |
- Format
- https://prefixID.v.fwmrm.net/ad/g/1
- Example with custom prefix ID included
- https://83b96.v.fwmrm.net/ad/g/1
3. Ad Request Parameters
The below repository lists out the different parameters for inclusion on HTTP GET ad requests - note that some are mandatory and are needed to make the ad request work or for successful monetization, whereas others might be recommended depending on the client set up and requirements. Depending on your region, your account team may provide tags with extra parameters but these should be considered as the minimum to get a functional tag. Additionally, the expectation is that there will be 3rd party macros to include on the tag in order to pass datapoints for the end user that depend on the adserver used. Note that the ad requests parameters are broken out into 3 types and it's very important that clients respect the taxonomy of the tags we provide you to ensure correct functionality.
- Global parameters - necessary for the correct functioning of the ad request. You sill specifically need to know the client vhost, network ID, profile ID and site section tag. These will be provided by your Freewheel rep.
- Key value pairs - often recommended/required to pass extra required contextual information such as Standard Attributes so Freewheel can monetize your supply and best align demand.
- Slot parameters - required to pass information around the slot such as the roll type, duration etc...
Please note that each parameter section is separated by a semicolon (;) and the tag may not work if this isn't included nor if parameters aren't passed in the correct section of the tag!
If a client has both live and on demand inventory, separate tags will need to be provided
Scroll to the right to see the full table
| Parameter Name | Required vs Recommended | Description and format | Freewheel Placeholder | SpringServe Macro (not in hub) | Publica Macro (not in hub) | Elemental Macros (not in hub) | GAM Macros (not in Hub) | |
|---|---|---|---|---|---|---|---|---|
| https://[CLIENT_VHOST].v.fwmrm.net/ad/g/1? | Required | Client specific Vhost. The alphanumeric ID is the client's network ID Hexadecimal encrypted. For example:
| Global Parameters | |||||
| nw=[NETWORK_ID_PLACEHOLDER] | Required | Network ID - integer | ||||||
| resp=vast4 | Required | Response format - string | ||||||
| prof=[PROFILE_PLACEHOLDER] | Required | Player profile. Specifies which types and formats of ads can be returned in this player environment - string 54321:fw_ssp_VAST_clientname | ||||||
| csid=[SITE_SECTION_PLACEHOLDER] | Required | Custom site section ID. Indicates "where" the video is played. This is an alpha-numeric value and is considered the tag for the site section - string | ||||||
| caid=0 | Required | Custom video asset ID. Hardcoded to '0' or '1'. - integer | ||||||
| pvrn= | Required | Page View Random. A random number generated per page view. Used for cache busting - integer | [CACHEBUSTER_PLACEHOLDER] | {{CACHEBUSTER}} | [CACHEBUSTER] | ${CB} | %%CACHEBUSTER%% | |
| vprn= | Required | Video Player Random. A random number generated per video instance (re-randomize on a new video play even on the same page). Used for cache busting - integer | [CACHEBUSTER_PLACEHOLDER] | {{CACHEBUSTER}} | [CACHEBUSTER] | ${CB} | %%CACHEBUSTER%% | |
| flag=+fwssp+amcb+nucr | Required | The flag section turns on or off specific capabilities that are needed to make the integration work. "+" means to turn on and "-" means to turn off. String | ||||||
| metr=1023 | Required | Signals the default metrics supported for all ads returned in the response. It's a bitmap representing whether this integration supports some pre-defined metrics like clickable, pausable, mutable, etc - Integer | 1023 | |||||
| vip= | Required | End user IP address - string | [IP_ADDRESS_PLACEHOLDER] | {{IP}} | [IP] | ${IP} | %%USER_IP%% | |
| mode=live | Required | Stream type of the video asset, acceptable values are "on-demand" or "live" - string | live | |||||
| ; | Global Parameter (Above) Key Values (Below) - please take note of the separator value | Global Parameter (Above) Key Values (Below) | ||||||
| _fw_h_user_agent= | Required | End user user agent - string | [USER_AGENT_PLACEHOLDER] | {{USER_AGENT}} | [%UA%] | ${UA} | %%USER_AGENT%% | Key Values |
| _fw_h_referer= | Required for OLV | End user referrer URL. Not required for non-web environments - string | [REFERER_URL_PLACEHOLDER] | {{ENCODED_URL}} | %%REFERRER_URL_ESC%% | |||
| _fw_vcid2= | Required | Custom user ID, used for frequency capping and audience lookup - string | [DEVICE_ID_PLACEHOLDER] | {{DEVICE_ID}} | [DID] | ${DEV_ID} | %%ADVERTISING_IDENTIFIER_PLAIN%% | |
| _fw_did= | Required | End user device ID, used for frequency capping and audience lookup - string | [IFA_TYPE_PLACEHOLDER] | {{IFA_TYPE}} | [IFA_TYPE] | ${IFA_TYPE} | %%ADVERTISING_IDENTIFIER_TYPE%% | |
| _fw_deviceMake= | Recommended | Device make (e.g. Apple) - string | [DEVICE_MAKE_PLACEHOLDER] | {{DEVICE_MAKE}} | [%DEVICE_MAKE%] | ${DEV_MAKE} | GAM uses the pattern macro where by the key is declared in this format: %%PATTERN:key%% Please replace the key string with the relevant key that you wish to use for custom targeting An example might be %%PATTERN:dev_make%% | |
| _fw_player_width= | Recommended | Player width - integer | [WIDTH_PLACEHOLDER] | {{WIDTH}} | [WIDTH] | ${WIDTH} | %%WIDTH%% | |
| _fw_player_height= | Recommended | Player height - integer | [HEIGHT_PLACEHOLDER] | {{HEIGHT}} | [HEIGHT] | ${HEIGHT} | %%HEIGHT%% | |
| _fw_playback_method=1 | Recommended | Integer with the following possible values: 1 Initiates on Page Load with Sound On | ||||||
| _fw_playback_end= | Recommended | Integer - the following table lists the various modes for when playback terminates. | [PLAYBACK_END_PLACEHOLDER] | |||||
| _fw_app_name= | Required for in app | App Name - string | [APP_NAME_PLACEHOLDER] | {{APP_NAME}} | [%APP_NAME%] | ${APP_NAME} | GAM uses the pattern macro where by the key is declared in this format: %%PATTERN:key%% Please replace the key string with the relevant key that you wish to use for custom targeting An example might be %%PATTERN:app_name%% | |
| _fw_app_bundle= | Required for in app | App Bundle ID - string | [APP_BUNDLE_PLACEHOLDER] | {{APP_BUNDLE}} | [%APP_BUNDLE%] | ${APP_BUNDLE} | GAM uses the pattern macro where by the key is declared in this format: %%PATTERN:key%% Please replace the key string with the relevant key that you wish to use for custom targeting An example might be %%PATTERN:app_bundle%% | |
| _fw_app_store_url= | Required for in app | App store URL - string | [APP_STORE_URL_PLACEHOLDER] | {{APP_STORE_URL}} | [%APP_STORE_URL%] | ${APP_URL} | GAM uses the pattern macro where by the key is declared in this format: %%PATTERN:url%% In this case the url will be expanded to that of the app store An example might be %%PATTERN:www.myappstoreurl.com%% | |
| _fw_inventorypartnerdomain= | Recommended | Declaration of inventory partner domain for ads.txt - string | [INVENTORY_PARTNER_DOMAIN_PLACEHOLDER] | {{INV_PARTNER_DOMAIN}} | [%PARTNER_DOMAIN%] | ${INV_PARTNER_DOMAIN} | GAM uses the pattern macro where by the key is declared in this format: %%PATTERN:key%% Please replace the key string with the relevant key that you wish to use for custom targeting An example might be %%PATTERN:inv_partner_domain%% | |
| _fw_is_lat= | Recommended | Used to identify if a user has opted in or out of Limit Ad Tracking. Value should be 1 (user has enabled limit ad tracking) or 0 (user has not enabled limit ad tracking) - integer | [LIMITED_AD_TRACKING_PLACEHOLDER] | {{LMT}} | [LIMITED_AD_TRACKING] | ${LMT} | %%ADVERTISING_IDENTIFIER_IS_LAT%% | |
| _fw_us_privacy= | Recommended | In support of CCPA and future US privacy regulations, FW supports the IAB privacy string https://hub.freewheel.tv/display/Resources/California+Consumer+Privacy+Act+%28CCPA%29+-+Implementation+Guidelines+for+MRM+Clients - string | [US_PRIVACY_PLACEHOLDER] | {{US_PRIVACY}} | [US_PRIVACY] | ${US_PRIVACY} | %%US_PRIVACY%% | |
| _fw_gdpr= | Recommended | GDPR boolean flag - integer | [GDPR_PLACEHOLDER] | {{GDPR}} | [GDPR] | ${GDPR} | ||
| _fw_gdpr_consent= | Recommended | GDPR Consent String - string | [GDPR_CONSENT_PLACEHOLDER] | {{CONSENT}} | [CONSENT] | ${GDPR} | ${GDPR_CONSENT_XXXX} | |
| _fw_coppa= | Recommended | COPPA boolean flag - integer | [COPPA_PLACEHOLDER] | {{COPPA}} | [COPPA] | ${COPPA} | %%TFCD%% | |
| ltlg= | Recommended | Latitude, Longitude *Must be comma separated - string | [LATITUDE_PLACEHOLDER],[LONGITUDE_PLACEHOLDER] | {{LAT}},{{LON}} | [LAT],[LON] | ${LAT},${LON} | ||
| _fw_content_programmer_brand= | Required | Programmer- Brand Standard Attributes. Programmer is inferred from brand value. _fw_content_programmer_brand=FWNewsUS - string | [PROGRAMMER_BRAND_PLACEHOLDER] | |||||
| _fw_content_genre= | Required if IAB content category - _fw_content_category= cannot be passed | Content genre - string | [CONTENT_GENRE_PLACEHOLDER] | {{CONTENT_GENRE}} | [%CONTENT_GENRE%] | ${CONTENT_GENRE} | GAM uses the pattern macro where by the key is declared in this format: %%PATTERN:key%% Please replace the key string with the relevant key that you wish to use for custom targeting An example might be %%PATTERN:genre%% | |
| _fw_content_rating= | Strongly recommended for effective monetization | Content rating - string | [CONTENT_RATING_PLACEHOLDER] | {{RATING}} | [%CONTENT_RATING%] | ${CONTENT_RATING} | GAM uses the pattern macro where by the key is declared in this format: %%PATTERN:key%% Please replace the key string with the relevant key that you wish to use for custom targeting An example might be %%PATTERN:rating%% | |
| _fw_site_category= | Recommended | Site category name - string | [CONTENT_CATEGORY_PLACEHOLDER] | {{IAB_CATEGORY}} | [CONTENT_CAT] | ${CONTENT_CAT} | %%IAB_CATEGORIES%% | |
| _fw_content_category= | Strongly recommended for effective monetization | Content category - string | [CONTENT_CATEGORY_PLACEHOLDER] | {{IAB_CATEGORY}} | [CONTENT_CAT] | ${CONTENT_CAT} | %%IAB_CATEGORIES%% | |
| _fw_content_channel= | Strongly recommended for effective monetization | Content channel name - string | [CONTENT_CHANNEL_PLACEHOLDER] | {{CHANNEL_NAME}} | [%CONTENT_CHANNEL%] | ${CHANNEL} | GAM uses the pattern macro where by the key is declared in this format: %%PATTERN:key%% Please replace the key string with the relevant key that you wish to use for custom targeting An example might be %%PATTERN:channel%% | |
| _fw_content_network= | Recommended | Content network name - string | [CONTENT_NETWORK_PLACEHOLDER] | {{NETWORK_NAME}} | [%CONTENT_NETWORK%] | ${NETWORK} | GAM uses the pattern macro where by the key is declared in this format: %%PATTERN:key%% Please replace the key string with the relevant key that you wish to use for custom targeting An example might be %%PATTERN:network%% | |
| _fw_content_title= | Recommended | Content title - string | [CONTENT_TITLE_PLACEHOLDER] | {{CONTENT_TITLE}} | [%CONTENT_TITLE%] | ${CONTENT_TITLE} | %%VIDEO_TITLE%% | |
| _fw_content_language= | Strongly recommended for effective monetization | Content language - string | [CONTENT_LANGUAGE_PLACEHOLDER] | {{LANGUAGE}} | [CONTENT_LANGUAGE] | ${CONTENT_LANGUAGE} | GAM uses the pattern macro where by the key is declared in this format: %%PATTERN:key%% Please replace the key string with the relevant key that you wish to use for custom targeting An example might be %%PATTERN:lang%% | |
| _fw_content_length= | Recommended | Content length expressed in seconds - integer | [CONTENT_LENGTH_PLACEHOLDER] | {{DURATION}} | [CONTENT_LENGTH] | ${CONTENT_DUR} | %%VIDEO_AD_DURATION%% | |
| _fw_content_producer_name= | Recommended | Content producer name - string | [CONTENT_PRODUCER_NAME_PLACEHOLDER] | {{CONTENT_PRODUCER_NAME}} | [%CONTENT_PRODUCER_NAME%] | ${PRODUCER_NAME} | GAM uses the pattern macro where by the key is declared in this format: %%PATTERN:key%% Please replace the key string with the relevant key that you wish to use for custom targeting An example might be %%PATTERN:producer_name%% | |
| _fw_production_quality= | Recommended | Content production quality - string | [CONTENT_PRODUCTION_QUALITY_PLACEHOLDER] | {{PRODUCTION_QUALITY}} | [CONTENT_PROD] | ${PRODUCTION_QUALITY} | GAM uses the pattern macro where by the key is declared in this format: %%PATTERN:key%% Please replace the key string with the relevant key that you wish to use for custom targeting An example might be %%PATTERN:content_prod%% | |
| _fw_bidfloor= | Optional | Dynamically pass programmatic bid floor price in ad request i.e. '12.23'. This is similar to setting floor price in: UI > Admin > Programmatic Management > Network Floor Price. -OR- UI > Network Items (SG, S or SS only) > Programmatic Management. Value format = float | [NET_BIDFLOOR_PLACEHOLDER] | |||||
| _fw_bidfloorcur= | Optional | Currently of floor price set in '_fw_bidfloor', example value 'USD'. If no currency, ADS will use CRO default network currency. Please see MULTI_CURRENCY_SUPPORT for multiple currency support. Currency specified using 3-character ISO-4217 alpha codes. Value format = string | [NET_BIDFLOOR_CURRENCY_PLACEHOLDER] | |||||
| schain= | Recommended, but could have downstream revenue consequences if not included | String - this can be passed in the ad request with key ver,complete!asi,sid,hp,rid,name,domain,ext Example: &schain=1.0,1!customer.name,5af190fb073ef4546a085a53,1,,name,yourdomain.com | [SCHAIN_PLACEHOLDER] | {{SCHAIN}} | [SCHAIN] | ${SUPPLY_CHAIN} | ||
| ; | Key Values (Above) Slot Parameter (Below) - please take note of the separator value | Key Values (Above) Slot Parameter (Below) | ||||||
| tpcl=[AD_UNIT_POSITION] | Required | Supported values: preroll, midroll, postroll - string | [PREROLL_OR_MIDROLL_OR_POSTROLL] | midroll | [POSITION] *Publica clients can customize Position values i.e. the position macro can return 'midroll', 'mid' or 'm'. Consult with the Pub AM prior to using the Publica Position macro to confirm expected values. | midroll | Slot Parameters | |
| ptgt=a | Required | Type of slot. This is a required parameter - string ptgt=a: temporal slot | a | |||||
| mind=[MIN_SLOT_DURATION_PLACEHOLDER] | Required | Minimum slot duration - integer | ||||||
| maxd=[MAX_SLOT_DURATION_PLACEHOLDER | Required | Maximum slot duration ) - integer | ||||||
4. Sample Ad Request Tag
Please see below an example of an ad request tag in its expected format based on the above parameters:
https://1a2bC.v.fwmrm.net/ad/g/1?nw=54321&resp=vast4&prof=54321:fw_ssp_VAST_clientname&csid=my_site_section&caid=0&pvrn=[CACHEBUSTER_PLACEHOLDER]&vprn=[CACHEBUSTER_PLACEHOLDER]&flag=+fwssp+amcb+nucr&metr=1023&vip=[IP_ADDRESS_PLACEHOLDER]&mode=live;_fw_h_user_agent=[USER_AGENT_PLACEHOLDER]&_fw_h_referer=[REFERER_URL_PLACEHOLDER]&_fw_vcid2=[DEVICE_ID_PLACEHOLDER]&_fw_did=[IFA_TYPE_PLACEHOLDER]:[DEVICE_ID_PLACEHOLDER]&_fw_deviceMake=[DEVICE_MAKE_PLACEHOLDER]&_fw_player_width=[WIDTH_PLACEHOLDER]&_fw_player_height=[HEIGHT_PLACEHOLDER]&_fw_playback_method=1&_fw_playback_end=[PLAYBACK_END_PLACEHOLDER]&_fw_app_name=[APP_NAME_PLACEHOLDER]&_fw_app_bundle=[APP_BUNDLE_PLACEHOLDER]&_fw_app_store_url=[APP_STORE_URL_PLACEHOLDER]&_fw_inventorypartnerdomain=[INVENTORY_PARTNER_DOMAIN_PLACEHOLDER]&_fw_is_lat=[LIMITED_AD_TRACKING_PLACEHOLDER]&_fw_us_privacy=[US_PRIVACY_PLACEHOLDER]&_fw_gdpr=[GDPR_PLACEHOLDER]&_fw_gdpr_consent=[GDPR_CONSENT_PLACEHOLDER]&_fw_coppa=[COPPA_PLACEHOLDER]<lg=[LATITUDE_PLACEHOLDER],[LONGITUDE_PLACEHOLDER]&_fw_content_programmer_brand=[PROGRAMMER_BRAND_PLACEHOLDER]&_fw_content_genre=[CONTENT_GENRE_PLACEHOLDER]&_fw_content_rating=[CONTENT_RATING_PLACEHOLDER]&_fw_site_category=[CONTENT_CATEGORY_PLACEHOLDER]&_fw_content_category=[CONTENT_CATEGORY_PLACEHOLDER]&_fw_content_channel=[CONTENT_CHANNEL_PLACEHOLDER]&_fw_content_network=[CONTENT_NETWORK_PLACEHOLDER]&_fw_content_title=[CONTENT_TITLE_PLACEHOLDER]&_fw_content_language=[CONTENT_LANGUAGE_PLACEHOLDER]&_fw_content_length=[CONTENT_LENGTH_PLACEHOLDER]&_fw_content_producer_name=[CONTENT_PRODUCER_NAME_PLACEHOLDER]&_fw_production_quality=[CONTENT_PRODUCTION_QUALITY_PLACEHOLDER]&_fw_bidfloor=[NET_BIDFLOOR_PLACEHOLDER]&_fw_bidfloorcur=[NET_BIDFLOOR_CURRENCY_PLACEHOLDER];tpcl=[PREROLL_OR_MIDROLL_OR_POSTROLL]&ptgt=a&mind=30&maxd=500
5. Inventory Standardization
In order for Freewheel to successfully monetize your supply, we have developed "Standard Attributes" which allow clients to classify their inventory and facilitate inventory sharing and targeting for any buyers in the following ways:
Enhance clarity and discoverability: Sellers can standardize inventory by passing Standard Attribute values either dynamically on the ad request (recommended), or declaratively on Network items in order to increase transparency for buyers in the Marketplace Platform. Standard attributes are organized into categories by content, geo, device/environment types and roll types, This makes buyers more likely to discover your inventory and to better understand it.
Improve targeting: Buyers can target standard attributes for inventory acquired through the Marketplace Platform on their programmatic and direct sold demand.
Increase the accuracy of reporting and forecasting projections.
The more Standard Attributes that a client can pass, then the more likely we can monetize your supply and we highly recommend a standarization rate of 80%- 100% depending on the Standard Attribute. Please refer to section 3. Ad Request Parameters above for guidance on how to pass these on a VAST ad request as well as indicators as to what is required/recommended.
6. User Sync
As part of setting up a FW SSP client, Freewheel will automatically set up the user sync on their side for any OLV inventory to fire on the impression tracker in the ad response. For programmatic demand, Freewheel will use the user id passed in the _fw_vcid2 parameter as a basis to user sync with upstream DSP buyer IDs and pass this in the user.buyeruid. In cases where it may not be possible to fire our user sync from the client player, the Freewheel AM may recommend additional set up steps depending on your specific set ups. Additionally if the ad server you use is a net new adserver for Freewheel, there could be additional steps involved to set up user syncing with your system.
7. Ads.txt, AppAds.txt, Sellers.JSON
Your Freewheel account management team with provide the relevant ads.txt lines to implement as well as ensure that your sellers.JSON is up to date for your relevant seller relationships. Please refer to https://hub.freewheel.tv/display/MUG/ads.txt+and+app-ads.txt+setup#ads.txtandappads.txtsetup-FreeWheelSSP for details on the expected set up for a FW SSP customer.
8. Troubleshooting
In the case where you have issues such as
- Ad requests not being sent
- Ad requests being sent but no demand returned
First steps:
- Make sure the tag taxonomy is respected as in the notes above and that no important parameters crucial for functionality are being missed.
- Ensure that ads.txt and app.ads.txt are up to date with your expected ads.txt lines provided by the Freewheel AM to ensure that the supply can be correctly monetized by DSP partners who may not bid on this supply in case of inconsistencies
- We also recommend passing any Standard Attribute values that your Freewheel AM has recommended so we can better align demand to your supply.
In case the issue persists, we recommend that you file a ticket via your Zendesk access (your Freewheel AM will provide this) to our support teams for further investigation.