Campaign Monitor Pixel Implementation
Campaign Monitor (CM) uses a "piggy back" monitoring pixel to interact with browser at the time of ad delivery to collect both verification and valuation signals, which feed into the rating models.
Those models then output the reporting metrics provided through either the UI or log-level data, or both. The pixel supports client ID attribution providing the ability to dynamically assign id values to every ad. The pixel supports up to five id attributes that aggregate daily and are available in the UI reporting, in addition, four ID attributes are available for log-level data output, refer to section 2.0 for more detail. The pixel is supported over http and https (secure) environments.
Note: Be certain to use the proper case for all IAS parameters, macros and attributes.
JavaScript Monitoring Pixel
For clients who traffic through multiple partners/channels including exchanges, ad networks, and DSPs, the JavaScript Monitoring Pixel is the preferred implementation method given it interacts closely with the browser to collect several signals and data points. This pixel is served through a lightweight JavaScript file sourced from a respective JavaScript tag. In situations where intermediary ad serving iframes are associated with the ad call, the JavaScript has the ability to "break out" of the child iframe and identify the parent or true page referrer.
This pixel type represents the optimal methodology to achieve desired page level visibility, collect viewability, and invalid traffic signals. The pixel is fired from JavaScript code wrapped in a JavaScript tag. This pixel method cannot be used or called from third party providers who require image sourced "piggy back" pixels or do not have capabilities to support third party JavaScript tags, or both.
IAS recommends publishers do not add a cache-buster to the pixel for performance reasons.
Specification
JavaScript Structure
<script type="text/javascript" src="http://pixel.adsafeprotected.com/jload?anId=[Client ID]&advId=[ADVERTISER ID]&campId=[CAMPAIGN ID]&pubId=[PUBLISHER ID]&chanId=[CHANNEL ID]&placementId=[PLACEMENT ID]&adsafe_par&bidurl=[bidURL_macro]&bidPr=[WinningBidPrice_macro]&uId=[UserId_macro]&impId=[ImpressionId_macro]&dealId=[Deal ID]&bundleId=[BUNDLE ID]"> </script>Where:
ID | Description |
anId | Your IAS Client Services representative assigns and provides the Client ID during implementation. |
advId | Advertiser or Buyer ID (see 'ID Attribution Specifications' for more details). |
bundleId | Mobile application bundle ID (for mobile application ads) |
campId | Campaign associated to specific advertiser / buyer running multiple campaigns. |
dealId | The ID that is assigned to a Private Marketplace (PMP) deal upon its creation used to identify the deal between the buyers and sellers for both targeting and reporting. |
pubId | Publisher or Seller ID. |
chanId | Secondary Seller or Channel ID. |
placementId | Ad Unit or Placement or Creative ID. |
ias_xps | Autoplay or click-to-play. |
ias_xpb | Break position (also known as video placement type). |
ias_xar | Autorefresh |
In scenarios where the pixel is placed on a bidder or Real Time Bidding (RTB) environment, the following information can be collected in logs to support additional ROAS analysis and log-level data. Population of this data is optional and your IAS Client Services representative will provide more detail during integration.
ID | Description |
bidurl | URL received in bid request. This is mandatory for all Segment API platform integrations, and optional for other integrations. |
bidPr | Cleared price of the ad. This information is suggested for all Segment API integrations, and optional for other integrations. |
uId | Unique user ID assigned by client system. This information is suggested for all Segment API platform integrations, and optional for other integrations. |
impId | Unique event identifier assigned by client system. This information is suggested for all Segment API integrations, and optional for other integrations. |
Verified Monitoring Pixel
The Verified Monitoring Pixel supports clients capable of passing the page referrer in the pixel call through use of internal or upstream adserver macros, or both. In this scenario, IAS parses the passed referrer from the call as opposed to relying on the referrer provided in the get request header or identified by 3.1 JavaScript, or both.
Specification
JavaScript Structure
<script type="text/javascript" src="http://pixel.adsafeprotected.com/jload?anId=[Client ID]&advId=[ADVERTISER ID]&campId=[CAMPAIGN ID]&pubId=[PUBLISHER ID]&chanId=[CHANNEL ID]&placementId=[PLACEMENTID]&vURL=[Macro and or source code which identifies and assigns page/site referrer]&adsafe_par&bidurl=[bidURL_macro]&bidPr=[WinningBidPrice_macro]&uId=[UserId_macro]&impId=[ImpressionId_macro]&dealId=[Deal ID]&bundleId=[BUNDLE ID]"> </script>Where:
ID | Description |
anId | Your IAS Client Services representative assigns and provides the Client ID during implementation. |
advId | Advertiser or Buyer ID (see 'ID Attribution Specifications' for more details). |
bundleId | Mobile application bundle ID (for mobile application ads) |
campId | Campaign associated to specific advertiser / buyer running multiple campaigns. |
dealId | The ID that is assigned to a Private Marketplace (PMP) deal upon its creation used to identify the deal between the buyers and sellers for both targeting and reporting. |
pubId | Publisher or Seller ID. |
chanId | Secondary Seller or Channel ID. |
placementId | Ad Unit or Placement or Creative ID. |
vURL | URL assigned by client ad server at load time. |
bidurl | URL received in bid request. This is optional and intended for log-level data. |
bidPr | Cleared price of the ad. This is optional and intended for log-level data. |
uId | Unique user ID assigned by client system. This is optional and intended for log-level data. |
impId | Unique event identifier assigned by client system. This is optional and intended for log-level data. |
ias_xps | Autoplay or click-to-play. |
ias_xpb | Break position (also known as video placement type). |
ias_xar | Autorefresh |
Example - Client trafficking through the Right Media Exchange can assign vURL using the following RMX macro:
<script type="text/javascript">(new Image).src = http://pixel.adsafeprotected.com?anId=1&pubId=1483&advId=712&vURL=${SOURCEURLENC}</script>Standard Monitoring Pixel
The Standard Monitoring Pixel supports clients who can't pass the page referrer in the pixel call using the JavaScript Monitoring Pixel or Verified Monitoring Pixel. The page referrer is collected from the http get request header passed by the browser. The pixel must be placed or called directly from the publisher page to assure page referrer pass. Pixels firing within nested iframe scenarios will most likely obfuscate the pass of the actual page referrer, thus resulting in a poor see-through rate. This pixel supports brand safety monitoring only and does not fully support the collection of viewability, invalid traffic, and placement data.
Specification
JavaScript Structure
http://pixel.adsafeprotected.com?anId=[Client ID]&advId=[ADVERTISER ID]&campId=[CAMPAIGN ID]&pubId=[PUBLISHER ID]&chanId=[CHANNEL ID]&placementId=[PLACEMENT ID]&dealId=[Deal ID]&bundleId=[BUNDLE ID]Where:
ID | Description |
anId | Your IAS Client Services representative assigns and provides the Client ID during implementation. |
advId | Advertiser or Buyer ID (see 'ID Attribution Specifications' for more details). |
bundleId | Mobile application bundle ID (for mobile application ads) |
campId | Campaign associated to specific buyer running multiple campaigns. |
dealId | The ID that is assigned to a Private Marketplace (PMP) deal upon its creation used to identify the deal between the buyers and sellers for both targeting and reporting. |
pubId | Publisher or Seller ID. |
chanId | Secondary Seller or Channel ID. |
placementId | Ad Unit or Placement or Creative ID. |
ias_xps | Autoplay or click-to-play. |
ias_xpb | Break position (also known as video placement type). |
ias_xar | Autorefresh |
Redirect Monitoring Pixel
Clients requiring the option to perform a redirect to a third-party pixel call as opposed to using an IAS hosted pixel can use the Redirect option. In the following spec/example, the client uses their Dart server side macro capabilities to populate the ID parameters. The &redir get parameter instructs IAS to bypass IAS's hosted and served 1x1 image and instead redirect to an alternative third party pixel.
Specification and Example:
<script type="text/javascript" src="http://pixel.adsafeprotected.com/jload?anId=[ClientID]&pubId=%epid!&advId=%eadv!&campId=%ebuy!&dealId=[Deal ID]&bundleId=[BUNDLE ID]&redir=http://secure-us.imrworldwide.com/cgibin/m?ci=usade&cg=12088&; si=%eadv!_%ebuy!_%esid!_%epid!_%eaid!_%ecid!&pr=iag.sid,2500011436&pr=iag.tfid,1141&pr=iag.brn,%eadv!&pr=iag.cte,%ecid!&pr=iag.pageid,%epid!&pr=iag.cmpid,%ebuy!&pr=iag.stid,%esid!&pr=iag.impid,%ecid!&pr=iag.advid,%eadv!&cc=1&rnd=%n>Where:
ID | Description |
anId | Your IAS Client Services representative assigns and provides the Client ID during implementation. |
bundleId | Mobile application bundle ID (for mobile application ads) |
dealId | The ID that is assigned to a Private Marketplace (PMP) deal upon its creation used to identify the deal between the buyers and sellers for both targeting and reporting. |
pubId | Publisher ID or Primary ID assigned to client defined ID named value pair |
campId | Campaign ID or Secondary ID assigned to client defined ID named value pair |
advId | Advertiser ID or additional ID assigned to client defined ID named value pair |
redir | Client provided third party pixel call |
ias_xps | Autoplay or click-to-play. |
ias_xpb | Break position (also known as video placement type). |
ias_xar | Autorefresh |
Notes:
A value must be assigned to all &redir parameters. Failure to assign a value (null or blank) will result in a 404 error at browser resulting from a null populated image call.
The &redir parameter must be the last GET (&) statement in the call, placing this value in a different order will break the redirect.
Post Bid IAS Monitor Pixel
Platforms are required to support the IAS Monitor Pixel for post bid ad level reporting. Your IAS Client Services representative provides the related implementation details and implementation guides. The following requirements pertain to real time data signals integrations:
Platforms provide IAS the respective server macro names to assign values to IAS support ID parameters: including the bid URL macro, which is a mandatory requirement. The platform macros are responsible for assigning/writing out the necessary ID value within the platform ad container at the time of delivery/bid execution.
Platforms support third party pixels either via the piggy back method, where the platform or buyer append the IAS pixel tag directly on creatives prior to platform upload, or via platform supported creative templates (where ideally, a pixel is auto inserted with all supported macros on all creatives that have IAS targeting active).
IAS encourages that ad level information pertaining to user, bidder, and ad are also passed via a macro. Note this information is used, along with the bid URL macro, for IAS internal troubleshooting/analysis initiated by either platform or buyer. IAS uses this information for troubleshooting.
In video viewability targeting scenarios, platforms are responsible for supporting and trafficking IAS VAST/VPAID wrapper tags as opposed to client provided VAST/VPAID tags during implementation testing. The IAS wrapped tags are necessary to capture and record the necessary VPAID events to effectively measure and report upon viewability. Your IAS Client Services representative provides more details, initiates testing of such tags during integration, and provides more information during the integration process.
Mobile
OMID SDK
Mobile app video requires AVID and OMID nodes in the tag and doesn't require the video wrapper. See the following example and table for details.
Google Ad Manager Mobile Tag Template
<![CDATA[ https://company.com/omid.js ]]>Other Ad Server Mobile Tag Template
For mobile app, you can assign a viewability provider to an Ad Manager line item. See the Ad Manager help website for implementation instructions.
Template
<Extensions> <Extension type="AdVerifications"> <AdVerifications> <Verification vendor="company.com-omid"> <JavaScriptResource apiFramework="omid" browserOptional="true"> <![CDATA[ https://company.com/omid.js ]]> </JavaScriptResource> </Verification> </AdVerifications> </Extension></Extensions>Verification Configuration Field | Description | IAS Specific Notes |
VendorKey | The key that the vendor acquires from the IAB. The vendor provides this during configuration. | integralads.com |
JavaScriptResource | URI Location of the vendor's OM SDK script (should be prefixed with protocol). | Add the IAS Campaign Monitoring (CM) display pixel. |
VerificationParameters/ URL Parameters | A free text string of data that needs to be passed to the verification node in the OM SDK. The structure of the string is specific to the vendor's implementation (some could be ordinal based, while others are key-value based). | Ignored/not required. |
Rejection tracker URL | The URL that should be pinged if the verification script cannot be run. | Ignored/not required |
CM Wrapper
The CM Wrapper is one of the IAS methods for measuring video. IAS wraps an advertiser Video Ad Serving Template (VAST) ad tag with Flash or JavaScript, and produces a Video Player-Ad API Definition (VPAID) wrapper tag to be delivered in the video player. When an ad request is made, IAS returns the VPAID wrapper to the video player, which delivers the original VAST tag and performs video measurements. A VPAID wrapper tag can only be used for VPAID video inventory.
Wrapper Generation Process
The following are the steps for generating CM wrapper tags:
Client provides IAS with a VAST URL tag, along with any macros
An IAS representative creates a VPAID wrapper tag using the VAST URL and all other inputs. An example VAST URL is http://www.samplevideoad.com/videoad1.xml
IAS returns a generated VPAID wrapped tag to the client for trafficking into video players
CM Wrapper Tag
The CM Wrapper Structure is shown on the right.
CM Wrapper Structure
http://vast.adsafeprotected.com/vast?anId=[Client ID]&advId=[Advertiser ID]&campId=[Campaign ID]&pubId=[Publisher ID]&placementId=[Placement ID]&chanId=[Channel ID]&originalVast=[VAST URL]&dealId=[Deal ID]&bundleId=[BUNDLE ID]&dealId=[DEAL ID]&ias_xps=[Autoplayed or Not]&ias_xbp=[Break position]&ias_xar=[Autorefreshed or Not]Sample Tag
http://vast.adsafeprotected.com/vast?anId=1111&advId=2222&campId=3333&pubId=4444&placementId=5555&originalVast=http://www.samplevideoad.com/videoad1.xml&dealId=6666&bundleId=7777&dealId=8888&ias_xps=autoplayed&ias_xbp=2&ias_xar=1ID Attribution Specifications
The following table summarizes the values that clients can populate using the macros available through the ad server. The UI will label all assigned macro names to the appropriate IAS / UI naming convention. If client taxonomy and syntax is different, client must make note of mapping when referencing the IAS Signal. Clients can provide any attribution ID in their taxonomy required for UI Monitor reporting with one caveat, the ID cannot be a unique value (cookie, bid, user, date/time id). IAS supports up to 50 alphanumeric characters for all client provided ID attributes.
Note: Be certain to use the proper case for all IAS Named Parameters.
Information Type | IAS Named Parameter | Appears in UI as | Requirement | IAS Specification |
Client ID | anId | NA | Required | Integer IAS provides |
Publisher ID | pubId | Publisher/Primary Seller | Required | Alphanumeric 50 character limit Unique Value Limit = 5000 |
Campaign ID | campId | Campaign | Required | Alphanumeric 50 character limit Unique Value Limit = 500 |
Autoplayed Macro | ias_xps | NA | Required | |
Break Position Macro | ias_xpb | NA | Required | Break position (when in a video that ad played). Possible values include: "1" - pre-roll, "2" - mid-roll, "3" - post-roll, "4" - stand-alone |
Autorefresh Macro | ias_xar | NA | Required | Autorefresh. Possible values include: "0" - false, "1" - true |
Advertiser ID | advId | Advertiser | Optional | Alphanumeric 50 character limit Unique Value Limit = 500 |
Channel ID | chanId | Secondary Seller | Optional | Alphanumeric 50 character limit Unique Value Limit = 5000 |
Deal ID | dealId | Deal ID | Optional | Alphanumeric 50 character limit Unique Value Limit = 5000 |
Placement ID | placementId | Ad Unit | Optional | Alphanumeric 50 character limit Unique Value Limit = 7500 |
Bundle ID | bundleId | NA | Required | |
Redirect Pixel | redir | NA | Optional | URI Encoded |
Verified URL | vURL | NA | Optional | vURI URL Encoded |
Bid URL | bidurl | NA | Optional | Client can include a bid URL for post-bid delivery analysis |
Bid Price | bidPr | NA | Optional | Client can include a bid price for post-bid pricing analysis |
User ID | uId | NA | Optional | Client can include a user id for post-bid user targeting analysis |
Ad ID | impId | NA | Optional | Client can include an ad ID for post-bid user ad analysis |
Notes on Data Type Specifications:
Client can assign any ID values up to 50 alphanumeric to these named value pairs. IAS truncates the values when exceeding 50 alphanumeric characters. IAS recommends the pass of publisher and campaign attributes however they are not mandatory.
Clients can remove parameters (get &) for which they are not populating.
IAS does not support unique Ids for external id parameters; unique Ids can be delivered in the log-level post bid analysis. Please refer to the specification provided in the table or contact your IAS Client Services representative for more information.
Clients should not use characters other than alphanumeric. If required, our Professional Services team can map the characters.
Native Ad Implementation Overview
IAS introduced a new way to properly locate native ads. In order to trigger the native ad logic, you need to do the following:
Use a unique CSS ID selector with the placement.
Append the ias_adpath parameter to the tag.
Additional information:
This works for CM and Open Web pixels.
This functionality works as expected in direct and friendly iframe scenarios.
This is not supported in cross-domain iframe scenarios.
Step 1 - Use a unique CSS ID selector with the Placement.
You need to make sure the placement has a unique CSS ID selector. This ID selector can be either already on the placement's div or dynamically set at runtime. In both cases, it needs to be on the page before our tag is placed.
Step 2 - Append the ias_adpath parameter to our tag.
Once IAS knows the ID, IAS provides it to the tag:
http://fw.adsafeprotected.com/jload?anId=92301&advId=ViewabilityTest&;ias_adpath=%23our-adThis tag now attempts to find an HTML element with 'our-ad' CSS ID.
Notice the %23 in above tag. This is the URL encoded # symbol that you need to include.
Note: Adding the param in the following way does not work:
ias_adpath=our-ad
%23 needs to be inserted here.
Using the Native Ad Solution with HTML5 Ads
The IAS tag normally assumes that it is in the same container as the ad creative. With native ad support, you can specify another ID in a separate container to track the ad.
Using the Native Ad mechanism, IAS can point to a specific div inside the HTML5 structure. See the following diagram for more information:
