Freewheel Player Integration Guide
The Freewheel IAS PEM (Player Extension Module) can be run globally across desktop and mobile web HTML5 inventory. It enables viewability, fraud and brand safety reporting for publishers.
Implementation Steps
The Client and their IAS and Freewheel account teams easily activate the IAS PEM via email:
1) Client to:
a. Provide the player profile list to Freewheel account team
b. Enable Freewheel API access for IAS for user-friendly name mapping (mandatory before Publisher certification)
2) IAS to:
a. Provide Client ID to the Freewheel account team
b. Provide Custom Reporting Fields setup to the Freewheel account team
3) Freewheel account team to:
a. Configure the IAS PEM and confirm when implemented
4) IAS to:
a. Smoke Test the PEM
b. Confirm data is pulling into UI and complete mapping for user-friendly names
5) Client to:
a. Provide IAS reporting by Section ID for discrepancy analysis
Technical Prerequisites
1. To facilitate accurate measurement, Client to confirm the following for the video display base element whose id is provided to Freewheel's AdManager via the
Context.registerVideoDisplayBase method:
a. Is an HTML element, attached to a rendered document at the time of ad playback, with an attribute nodeType === 1
i. Ensure this is not a proxy object.
b. Does not have styling, on itself or on a parent, that renders it invisible (such as display:none or visibility:hidden)
i. Verify that yourDisplayBaseNode.getBoundingClientRect().width > 0 &&yourDisplayBaseNode.getBoundingClientRect().height > 0
2. Client to confirm the following is true of the page environment where the PEM is used:
a. window.document.readyState !== "loading" before + during ad playback
b. Allows injection of additional elements into the page (under the ad node) to facilitate measurement.
Standard Reporting Field Support
Do not use these Freewheel macros (for example {ad.advertiser.id}), when creating CM pixels for Freewheel. Instead use pixel macros with a # in front, for example: #{ad.advertiser.id}
IAS UI Description | Freewheel Parameter Name | Freewheel Macro | Freewheel API Name |
"Advertiser" | advertiserId | {ad.advertiser.id} | Advertiser API v3 |
"Size" | timePositionClass | {slot.timePositionClass} | N/A |
"Order" | campaignId | {slot.timePositionClass} | Campaign API v3 |
"Creative" | creativeId | {ad.creative.id} | Creative API v4 |
"Line Item" | placementId | {ad.placement.id} | Placement API v3 |
"Ad Unit" | sectionId | {section.id} | Site API v4 |
"Custom 1" | custom | Publisher must specify | TBD- See below |
"Custom 2" | custom | Publisher must specify | TBD- See below |
"Custom 3" | custom | Publisher must specify | TBD - See below |
Custom Reporting Field Support
IAS supports 3 custom macro fields in the IAS UI. Activation steps:
1) Client to select the custom fields from the table below
Note: Unique reporting values must adhere to IAS UI limits (10k unique entries/values).
2) IAS & Freewheel to configure the PEM to pass those parameters with the names "custom" / "custom2" / "custom3"
Freewheel Parameter Name | Freewheel Macro | Freewheel API Name | Description/Example |
reqNetworkId | {request.networkId} | N/A | Network (equivalent to our team) where the request is made. i.e. reqNetworkId=654321 |
adNetworkId | {ad.networkId} | N/A | Defines where (which FreeWheel Network) the Ad is coming from if client allows partners to sell on their content. If Direct sold it should be the same as request.networkId. i.e. adNetworkId=654321 |
ioId | {ad.io.id} | Insertion Order API v3 | Insertion Order sits between a Campaign and a Placement. In many cases it is a way for clients to split a deal by Quarter. As a reminder here is the hierarchy of a Campaign: Campaign > Insertion Order > Placement > Ad Unit > Creative This particular Id is the FreeWheel ID automatically assigned at creation i.e. ioId=7654321 |
ioExternalId | {ad.io.externalId} | Insertion Order API v3 | This particular Id is the Client’s Insertion Order ID, given by the client at creation. This ID, as every external IDs, is usually used by the client to link other systems they are using (i.e. Order Mgmt Systems) i.e. ioExternalId=98765432 |
adUnitId | {ad.adUnit.id} | Ad Unit Node API v3 | Ad Unit ID is the type of ads the creative under will be. This is defined at each Network level and created by the client (i.e. Preroll Ad Unit) i.e. adUnitId=54321 |
seriesId | {series.id} | Video API V4 | Series are groups of Video assets. Series are one level of Video groups in addition to Video Groups themselves. Videos can belong to as many Series and or Groups as they want.Series can belong to as many Groups as they want. Note the "g" in front of the number that defines the concept of Group in FreeWheel's IDs in ad responses i.e. seriesId=g54321 |
assetId | {asset.id} | Video API V4 | This is the actual Content/Video asset the end user is watching (not the Ad!) i.e. assetId=123456789 |
assetCustomId | {asset.customId} | Video API V4 | Asset ID coming from Client and probably referenced by this ID within their CDN or other systems i.e. assetCustomId=1234567 |
siteId | {site.id} | Site API v4 | Sites are groups of Sites Sections. Site Section represent WHERE the video is being played (i.e BrandOne - Mobile - iOS - Phone). Sites are one level of Site groups in addition to Site Groups themselves. This can become very handy for Publishers, especially since a Site Section can only belong on one Site i.e. seriesId=g54321 |
renditionId | {ad.creative.rendition.id} | Creative Library v3 | Renditions are formats of a creative. A creative could have several formats (i.e .mp4, .flv, etc). Depending on the Player profile settings one or several formats will return, ensuring only compatible formats are returned to the player. i.e. renditionId=6543210 |
renditionDuration | {ad.creative.rendition.duration} | Creative Library v3 | Duration of the Creative's rendition, in seconds i.e. renditionDuration=20 |
pageType | {request.keyValue (\pageType\")} | N/A | i.e. pageType=homepage |
slotDim | #{slot.width}x#{ slot.height} | N/A | Screen resolution i.e. slotDim=1920x1080 |
Enabling API Access for User-Friendly Name Mapping
Standard Reporting Fields
IAS requires access to the following Freewheel APIs in order to map IDs to user-friendly values in the IAS UI:
v3/placement
v3/advertisers
v3/campaign
v4/creative
v4/site_sections
For site sections, access by individual ID is required
For v3 access: Client creates API access token for IAS
For v4 access: Client requests "API Documentation Form" from Freewheel (for contact, put IAS Solutions Engineering and for the email, use the appropriate regional SE email address, for example ias-se-na@integralads.com) and completes needed entries. IAS will input the IP addresses from which the API will be accessed.
Custom Reporting Fields
If the selected Custom Reporting Fields require mapping to friendly names, IAS can support a manual mapping process:
Client supplies spreadsheet of IDs + friendly names
IAS to complete mapping
Unsupported Metrics
% Full Screen - this value is not a standard Freewheel API, custom work is required on IAS end to determine full screen events
FAQs
Q: Can Publishers using SmartXML method for working with FreeWheel leverage the integration?
A: No, IAS integrations would not work as the publisher is not using the FreeWheel AdManager for HTML5 (which sends a JSON response) for rendering the ad, in this case the publishers video player handles the ad rendering
Q: Can publisher enable PEM on select campaigns or across entire player profile?
A: Only across entire profile
Q: Do I use the Freewheel macros for standard CM pixel creation?
A: No, do not use the Freewheel macros (for example {ad.advertiser.id}), when creating CM pixels for Freewheel. Instead use pixel macros with a # in front, for example: #{ad.advertiser.id}