Partner Measurement API Implementation Guide
This document provides a technical overview of the IAS partner measurement API.
Overview & General Details
The partner measurement API allows Integral Ad Science (IAS) partners to send IAS their display and video ad level signals using a REST API, with JSON-formatted data. You send IAS a signal for each of the events, with accompanying properties for each event object. As a general rule with the partner measurement API, if you are unable to measure an optional property, don't send that property, nor a value for it, to IAS. Additionally, you only need optional properties for the initial event associated with a particular ad.
The following conventions are used throughout this document:
Terminology | Definition |
Event Type | An ad tech condition that should be reported. For example, if at least 100 percent of an ad is in view, it meets the '100% threshold'. IAS mapped the event name closely to the Event Type. For example, '100% threshold' is mapped to the IAS event '100-percent'. |
IAS Event Object | An IAS event object name corresponding to an ad tech condition that should be reported. The event is named similar to the Event Type. For example, the IAS event 'second-quartile' is mapped to the 'Second Quartile' Event Type. |
property | IAS event objects have values, or properties, to further describe the event. For example, the video event 'completed' has the property 'fullScreen' which might be true or false. |
Event Property Type | The type of the property which might be a boolean, integer, number, null, object or a string. |
Note: Contact your IAS representative for access to the JSON display and video schemas on GitHub.
Base URL
Base URL
http://pmi.adsafeprotected.comUse the following domain to send events to IAS: http://pmi.adsafeprotected.com. Then use the following endpoints depending on which events you are sending.
Endpoints
Endpoint | Events |
/v1/display | Display ad events |
/v2/display | Display events with ID properties as string type |
/v1/video | Video ad events |
/v2/video | Video events with ID properties as string type |
Note: If you're using on-premise pipelines, your endpoint may be customized with your company name like this:
https://pmi.adsafeprotected.com/{company_name}Test Your PMI Object Schemas for Validity
You can test and validate your object schemas, and the API responds with whether your object schema is valid or not. If your schema is not valid, it sends you the API error messages you would receive, and examples of valid payloads.
You can test in these two ways:
1. Send a POST request to:
http://etl-pm-sv-api-2-prod-924086945.us-east-1.elb.amazonaws.com/api
Include your payload object in your request body. Use these endpoints depending on your API version and ad type:
/v1/display
/v1/video
/v2/display
/v2/video
2. Use this test sandbox: http://etl-pm-react-sv-1-prod-111412727.us-east-1.elb.amazonaws.com/
This sandbox has a glossary that defines all payload keys, and also allows you to send test payloads with these instructions:
Copy the JSON object payload you want to validate.
From the top of the validator, choose either v1 or v2 from the drop down, depending on which API version you are testing.
From the dropdown menu to the right, choose whether your object is video or display.
Paste your object into the command line.
Click Submit.
Other Headers
For Partner identification, each request contains a "X-Partner-Id" HTTP request header, where X-Partner-Id carries your source ID.
Example HTTP Request Header:
Content-Type: application/jsonX-Partner-Id: 00Request Format
POST requests with a JSON body and a Content-Type header set to application/json.
Return Codes
All of the JSON reports use the following return codes.
Code | Description |
201 Created | Created |
400 Bad Request | Invalid arguments passed in parameters |
IAS Tags and IDs
You will have an internal ID generated by your system for any ad campaign running on your company's platform. IAS also generates internal IDs for every campaign. IAS associates its ID for a campaign to your ID by generating an IAS ad tag and sending it to you. An IAS tag is needed as a mechanism for conveying our campaign ID to you.
Please note that you do not have to traffic this tag. This implementation guide's purpose is to layout a framework for server-to-server integrations between IAS and companies like yours so that no tag from IAS will be trafficked on your platform.
The workflow is as follows:
An advertiser lets both IAS and your company know that they want IAS measurement enabled on your inventory for a campaign.
IAS generates a single tag (a 1x1 pixel) for this campaign. This tag contains IAS's own internal ID for the campaign.
IAS sends this tag to either you directly, or to the advertiser/agency who then passes it along to you.
Treat the tag as a block of text instead of trafficking the IAS tag. Then parse it for its campaign ID.
You store IAS's campaign ID in a mapping table that provides the relationship between IAS's ID for the campaign with your own ID for the campaign.
Whenever you send IAS signals for that campaign, send them with both your campaign ID (as provided in the "campaignID" attribute, described more fully in a later section) and the IAS campaign ID (as provided in the "iasAdvEntityID" attribute, also described more fully in a later section).
Note: Multiple "iasAdvEntityID" attributes cannot be mapped to one "campaignId" attribute.
As shown in bold in the 1x1 pixel template below, the IAS campaign ID that needs to be parsed from this is contained in the "advEntityID" placeholder:
<NOSCRIPT> <IMG SRC="https://pixel.adsafeprotected.com/rfw/st/"advEntityID"/"pubEntityID"/s keleton.gif" BORDER=0 WIDTH=1 HEIGHT=1 ALT="" /></NOSCRIPT>Note: Above, the placeholder "pubEntityID" will be replaced with an ID number in an actual tag. This corresponds to the "iasPubEntityID" attribute discussed more below.
Authentication
This API uses OAuth 2.0. Get a client ID and client secret from your IAS representative.
v1 Authentication
Use one of the following grant flows:
client_credentials - You only need one set of credentials, and you do not need access to IAS Signal. Get a token through the following command:
curl --user {client ID}:{client Secret} --data 'grant_type=client_credentials' https://auth.adsafeprotected.com/uaa/oauth/tokenThe event POST requests can pass the access_token in HTTP header:
Authorization: bearer nnNnnNnnOnNNN...Once generated, you can re-use the token with multiple requests to the Partner Measurement API until the token expires (which is indicated with the error 'invalid_token' and an error description 'Access token expired').
password - One set of client credentials and one username and password with access to the IAS Signal needed. Get a token through the following command:
curl --user {client ID}:{client Secret} --data 'username={userName}&password={userPassword}&grant_type=password' https://auth.adsafeprotected.com/uaa/oauth/tokenv2 Authentication
client_credentials - You only need one set of credentials, and you do not need access to IAS Signal. Get a token through the following command:
curl -H "Accept:application/json" -u {client ID}:{client Secret} https://auth.adsafeprotected.com/uaa/oauth/token -d grant_type=client_credentialsThe event POST requests can pass the access_token in HTTP header:
Authorization: bearer nnNnnNnnOnNNN...Once generated, you can re-use the token with multiple requests to the Partner Measurement API until the token expires (which is indicated with the error 'invalid_token' and an error description 'Access token expired').
v2 Authentication Response
See an example response in the code sample section below:
{ "jti": "x0x0x000-0x0x-0000-x0x0-x00x0xx000x0", "scope": "00:{client ID}:write", "expires_in": 12345, "token_type": "bearer", "access_token": "nnNnnNnnOnNNN..."}v1 and v2 Authentication SchemaValue | Description |
{client ID}:{client Secret} | client ID and secret, separated by a colon |
grant_type | set to either client_credentials or password |
username | the IAS Signal username |
password | the password for the IAS Signal username |
Authentication Token URL | https://auth.adsafeprotected.com/uaa/oauth/token |
ID-Name Mapping and daily SFTP transfer
Since your company's system already has its own IDs for such entities as advertiser, campaign, etc., when you pass data to IAS's partner measurement API, you use your IDs. However, IAS needs to know what these IDs mean in order to present the correct human-readable labels for these IDs in IAS's reports.
This section outlines a mechanism for providing IAS with the correct mapping of names to your system IDs via an API (preferred method) or SFTP.
Note: IAS plans to deprecate use of an SFTP transfer to provide your ID-Name mapping. IAS recommends you update your implementation to use the ID-Name Mapping API.
ID-Name Mapping API
The ID-Name Mapping API is is a REST JSON request to send IAS your ID and name.
This is the preferred method to send your ID-Name mapping; see authentication for more information.
V1
Endpoints
Use the appropriate endpoint for your use case:
https://pmi.adsafeprotected.com/v1/mapping/advertiser
https://pmi.adsafeprotected.com/v1/mapping/campaign
https://pmi.adsafeprotected.com/v1/mapping/placement
https://pmi.adsafeprotected.com/v1/mapping/creative
then send the following JSON, setting the proper id and name values:
{ "mapping": { "id": 12345, "name": "foo" } }
Curl
curl -X POST https://pmi.adsafeprotected.com/v1/mapping/advertiser -H 'Content-Type: application/json' -H 'Authorization: Bearer <token>' -d '{"mapping": {"id": 12345, "name": "foo"}}'
Return Codes
Error code | Description |
200 | Success |
400 | Client Error |
500 | System Error |
V2
Endpoints
Use the appropriate endpoint for your use case:
https://pmi.adsafeprotected.com/v2/mapping/advertiser
https://pmi.adsafeprotected.com/v2/mapping/campaign
https://pmi.adsafeprotected.com/v2/mapping/placement
https://pmi.adsafeprotected.com/v2/mapping/creative
then send the following JSON, setting the proper id and name values:
{ "mapping": { "id": "abc123xyz", "name": "bar" } }
Curl
curl -X POST https://pmi.adsafeprotected.com/v2/mapping/advertiser -H 'Content-Type: application/json' -H 'Authorization: Bearer <token>' -d '{"mapping": {"id": "abc123xyz", "name": "bar"}}'
Return Codes
Error code | Description |
200 | Success |
400 | Client Error |
500 | System Error |
ID-Name Mapping and daily SFTP transfer (legacy)
Note: IAS plans to deprecate use of an SFTP transfer to provide your ID-Name mapping. IAS recommends you update your implementation to use the ID-Name Mapping API.
Since your company's system already has its own IDs for such entities as advertiser, campaign, etc., when you pass data to IAS's partner measurement API, you use your IDs. However, IAS needs to know what these IDs mean in order to present the correct human-readable labels for these IDs in IAS's reports.
This section outlines a mechanism to provide IAS the correct mapping of names to your system IDs via an SFTP transfer.
Entities that Require ID-Name Mapping
IAS needs to know the IDs and names for:
advertiser
campaign
placement
creative
Additionally, for each message you send to the partner measurement API, IAS needs to know which ad server was involved, regardless of whether these ad servers are internal to your company, or third-party ad servers. This is to allow IAS to deal with possible ID collisions for the other entities.
For example, say your company has 2 ad servers, adServer1 and adServer2. There may be an advertiser ID of 449 on both of those ad servers – but for AdSrv1, the advertiser ID of 449 means Alice's West Coast Ad Agency, while for AdSrv2, the advertiser ID of 449 means Bob's Chicago Ad Agency.
ID-Name Lookup Files
To communicate ID-name mappings to IAS, please provide the following lookup files (in CSV format) on the IAS SFTP server each day by 4 AM East Coast Time. (Daily files ensure IAS stays current on new IDs created in your company's system.) The files should be organized in the following folder structure:
./inbound/nameMappings/adServer<#>/Comma Separated File | CSV Structure |
advertiser_{partnerName}_{YYYYMMDD}.csv | advertiser ID,advertiser name |
campaign_{partnerName}_{YYYYMMDD}.csv | campaign ID,campaign name |
placement_{partnerName}_{YYYYMMDD}.csv | placement ID,placement name |
creative_{partnerName}_{YYYYMMDD}.csv | creative ID,creative name |
Note 1: You must include a header row in these files.
Note 2: YYYYMMDD is the date in Eastern Time.
You need to create this set of CSV files needs for each of your ad servers. Work with your IAS representative to create a folder on the IAS SFTP for each of your ad servers, then put the relevant lookup files for each ad server into the appropriate folder.
For example, if you are using two ad servers (adServer1 and adServer2), then you need to send IAS the following 8 CSV files:
./inbound/nameMappings/adServer1/advertiser_generic_20160317.csv ./inbound/nameMappings/adServer1/campaign_generic_20160317.csv ./inbound/nameMappings/adServer1/placement_generic_20160317.csv ./inbound/nameMappings/adServer1/creative_generic_20160317.csv ./inbound/nameMappings/adServer2/advertiser_generic_20160317.csv ./inbound/nameMappings/adServer2/campaign_generic_20160317.csv ./inbound/nameMappings/adServer2/placement_generic_20160317.csv ./inbound/nameMappings/adServer2/creative_generic_20160317.csvThe lookup files are comma separated with the ID and the name you use to identify the advertiser, campaign, placement, and creative. For example, here is a sample advertiser lookup file:
"advertiser_id","advertiser_name""1153","Acme""1997","Beta"Then, a sample campaign lookup file:
"campaign_id","campaign_name""3000093","Soda Pop Olympics""3100068","Jeans Oscars"A sample placement lookup file:
"placement_id","placement_name""950001","placement1""950003","placement2"Finally, a creative lookup file:
"creative_id","creative_name""880001","creative1""880003","creative2"Note: Contact your IAS Solution Engineer for the SFTP details.
Discrepancy Management
To ensure alignment between your company's reporting and IAS's, IAS recommends producing and sending IAS your daily aggregated ad counts. IAS can then calculate the daily discrepancy rate by comparing your count of how many ads you saw and sent signals to IAS for, with IAS's own counts of how many signals it received.
Some amount of discrepancies is to be expected, since messages from one system to another can be "lost" or "dropped" for any number of reasons (for example, temporary network or server outages). Ideally, however, the discrepancy rate will be quite low. In order to ensure this, IAS recommends you send to IAS's SFTP the following CSV file in plain text:
Name: discrepancy_counts_<YYYYMMDD>.csv
./inbound/discrepancy/adServer1/discrepancy_counts_20160317.csv./inbound/discrepancy/adServer2/discrepancy_counts_20160317.csvNote: <YYYYMMDD> is the date in East Coast Time.
Fields:
Date
Advertiser ID
Campaign ID
Placement ID
Creative ID
Total Impressions
Measurable Impressions
Measurable Rate
MRC Viewable Impressions
MRC Viewable Rate
Your discrepancy file must include a header row. All values must be double quoted, with commas separating the column values. IAS expects the IDs to be BIGINTs.
Note: Other metrics of interest can be added as needed to this file, however please discuss with your IAS Solutions Engineer before using those metrics.
/v2/display POST
v2 endpoints are identical to v1 endpoints except for the types of the following parameters.
/v2/display Request Example:
curl -v -H "X-Partner-Id: 00" -H "Content-Type: application/json" \ -H "Authorization: bearer ${TOKEN}" \ -X POST \ -d '{ "event": { "type": "impression", "advertiserId": "012345678901", "campaignId": "012345678901", "creativeId": "012345678901", "iasAdvEntityId": 123456, "iasPubEntityId": 0, "impressionId": "-123412341234123412341234123412341642498858147041405143097623748123412341234", "placementId": "0", "timestamp": 1636647861763, "userAgent": "{useragent}", "autoPlay": true, "duration": 6000, "format": "html5", "ipHashed": "x1xx88x91234161234x12x41xxxx61xxxxxx514xx3xxx5d57x1234x9x081234", "measurable": 0, "inView50": false, "inView100": false, "skippable": false, "fullScreen": false, "volume": 0.0 } }' \ https://pmi.adsafeprotected.com/v2/displayThese parameters are integer type in v1, but are string type in v2:
Property name | type |
advertiserId | string |
campaignId | string |
creativeId | string |
inventoryType | string |
placementId | string |
Besides these parameters, everything else is the same in v1 and v2. Consequently, you can use the next /v1/display section for all v2 information you need:
/v1/display POST
The following table explains which IAS display value to send when you receive a specific display Event Type. For example, if you register an In-View Event Type because the ad reaches the MRC standard, send the JSON event property in-view.
Event Type | Description | IAS Event Object |
Impression | Signals that an ad occurred. | impression |
Unload | When the page which contains the ad is unloaded or the user closed the browser window. | unload |
In-View | Ad reached MRC standard (at least 50 % in view for 1 second or 30 % if ad was >= 242,500 pixels). | in-view |
In-View Full | Ad was 100 % in view for any period of time. | 100-percent-in-view |
In-View 5 seconds | Ad was at least 50 % in view for a cumulative 5 seconds. | in-view-5s |
In-View 15 seconds | Ad was at least 50 % in view for a cumulative 15 seconds. | in-view-15s |
Display Object Schema
The following tables show you all the properties in the display and video event objects. For each property, the table shows which events have that property.
The following table shows you the display events and which properties are required or optional.
R: Required
O: Optional
If there isn't an R or an O, do not send that property for the event
Display Events | ||||||
Display Property | impression | in-view | in-view-5s | in-view-15s | 100-percent-in-view | unload |
advertiserId | R | R | R | R | R | R |
campaignId | R | R | R | R | R | R |
creativeId | R | R | R | R | R | R |
iasAdvEntityId | R | R | R | R | R | R |
iasContentId | O | O | O | O | O | O |
iasPubEntityId | O | O | O | O | O | O |
impressionId | R | R | R | R | R | R |
inventoryType | O | O | O | O | O | O |
inview50 | R | O | O | O | O | O |
ip | O | |||||
ipHashed | O | |||||
measurable | R | O | O | O | O | O |
nonContinuousPlayTime | O | O | O | O | O | O |
placementId | O | O | O | O | O | O |
suspicious | O | |||||
timestamp | R | R | R | R | R | R |
type | R | R | R | R | R | R |
userAgent | R | R | R | R | R | R |
Display Events
Send the following JSON object with the associated property when you receive a signal that matches a display event. Signals include required and optional properties (noted in the event's Required column). If you are unable to measure an optional property, don't send that property, nor a value for it, to IAS.
Optional properties are only needed for the initial event associated with a particular ad.
Event | Definition |
impression | Signals that an ad occurred. |
in-view | Ad reached MRC standard (at least 50 % in view for 1 second or 30 % if ad was >= 242,500 pixels). |
in-view-5s | Ad was at least 50 % in view for a cumulative 5 seconds. |
in-view-15s | Ad was at least 50 % in view for a cumulative 15 seconds. |
100-percent-in-view | Ad was 100 % in view for any period of time. |
unload | When the page which contains the ad is unloaded or the user closed the browser window. |
impression
Signals that an ad occurred.
{ "event": { "type": "impression", "advertiserId": 12345, "campaignId": 123456, "creativeId": 1234, "impressionId": "1234567", "measurable": 1, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
ip | false | string | The IP address which generated the ad. |
measurable | true | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard. |
placementId | false | integer (string in v2) | This is your ID for the placement. |
suspicious | false | boolean | Whether the impression is suspected to be from invalid traffic. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000 is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
in-view
Ad reached MRC standard (at least 50 % in view for 1 second or 30 % if ad was >= 242,500 pixels).
{ "event": { "type": "in-view", "advertiserId": 12345, "campaignId": 123456, "creativeId": 1234, "impressionId": "1234567", "measurable": 1, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard. |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
in-view-5s
Ad was at least 50 % in view for a cumulative 5 seconds.
{ "event": { "type": "in-view-5s", "advertiserId": 12345, "campaignId": 123456, "creativeId": 1234, "impressionId": "1234567", "measurable": 1, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard. |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
in-view-15s
Ad was at least 50 % in view for a cumulative 15 seconds.
{ "event": { "type": "in-view-15s", "advertiserId": 12345, "campaignId": 123456, "creativeId": 1234, "impressionId": "1234567", "measurable": 1, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard. |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
100-percent-in-view
Ad was 100 % in view for any period of time.
{ "event": { "type": "100-percent-in-view", "advertiserId": 12345, "campaignId": 123456, "creativeId": 1234, "impressionId": "1234567", "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard. |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
unload
When the page which contains the ad is unloaded or the user closed the browser window.
{ "event": { "type": "unload", "advertiserId": 12345, "campaignId": 123456, "creativeId": 1234, "impressionId": "1234567", "measurable": 1, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard. |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
/v2/video POST
v2 endpoints are identical to v1 endpoints except for the types of these parameters. These parameters are integer type in v1, but are string type in v2:
/v2/display Request Example:
curl -v -H "X-Partner-Id: 00" -H "Content-Type: application/json" \ -H "Authorization: bearer ${TOKEN}" \ -X POST \ -d '{ "event": { "type": "impression", "advertiserId": "012345678901", "campaignId": "012345678901", "creativeId": "012345678901", "iasAdvEntityId": 123456, "iasPubEntityId": 0, "impressionId": "-123412341234123412341234123412341642498858147041405143097623748123412341234", "placementId": "0", "timestamp": 1636647861763, "userAgent": "{useragent}", "autoPlay": true, "duration": 6000, "format": "html5", "ipHashed": "x1xx88x91234161234x12x41xxxx61xxxxxx514xx3xxx5d57x1234x9x081234", "measurable": 0, "inView50": false, "inView100": false, "skippable": false, "fullScreen": false, "volume": 0.0 } }' \ https://pmi.adsafeprotected.com/v2/displayProperty name | type |
advertiserId | string |
campaignId | string |
creativeId | string |
inventoryType | string |
placementId | string |
Besides these parameters, everything else is the same in v1 and v2. Consequently, you can use the next /v1/video section for all v2 information you need:
/v1/video POST
As a general rule with the partner measurement API, if you are unable to measure an optional property, don't send that property, nor a value for it, to IAS. Additionally, optional properties are only needed for the initial event associated with a particular ad.
The following table explains which IAS video value to send when you receive a specific video Event Type. For example, if you register a First Quartile Event Type when the ad reached the 25 % of the ad, send the JSON event property first-quartile.
Event Type | Description | IAS Event Object |
Impression | Signals the video ad occurred. | impression |
Ad Started | When the ad started. | started |
Ad Paused | When the ad is paused. | paused |
Ad Resumed | When the ad transitions from a paused state to a playing state. | resumed |
Ad Skipped | When the ad was skipped. | skipped |
Unload | When the ad stopped or the page unloaded. | unload |
First Quartile | When the 25 % point of the ad played. | first-quartile |
Second Quartile | When the 50 % point of the ad played. | second-quartile |
Third Quartile | When the 75 % point of the ad played. | third-quartile |
Completed | When the 100 % point of the ad played. | completed |
50 % Viewable | When 50 % of the area of the ad is in view for at least 2 continuous seconds. | in-view-50 |
Three seconds in view | When 50 % of the ad is in view for at least 3 cumulative seconds. | 3-seconds-view |
100 % in view and sound on (no sound required for native publishers), for half of ad duration Note: Contact your GroupM representative to confirm your publisher category. | When 100 % of the ad is in view, with the sound on (no sound required for native publishers), and at least half of the ad played or the ad played for 15 seconds. | 100-percent-in-view |
100 % in view for 2 continuous seconds | When 100 % of the ad is in view for at least 2 continuous seconds. | 100-percent-in-view-2-seconds |
Ad Volume Changed | When the video's volume changed. | volume-changed |
Ad Resized | When the ad was resized. |
Video Object Schema
The following table shows you the video events and which properties are required or optional.
R: Required
O: Optional
If there isn't an R or an O, do not send that property for the event
Video Events | ||||||||||||||||
Video Property | completed | first-quartile | impression | in-view-50 | 100-percent-in-view | 100-percent-in-view-2-seconds | paused | resized | resumed | second-quartile | skipped | started | third-quartile | 3-seconds-view | unload | volume-changed |
advertiserId | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R |
autoPlay | O | O | ||||||||||||||
campaignId | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R |
creativeId | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R |
duration | O | O | ||||||||||||||
format | O | O | ||||||||||||||
fullScreen | O | O | R | O | O | O | O | R | O | O | O | O | O | O | O | O |
iasAdvEntityId | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R |
iasContentId | O | O | O | O | O | O | O | O | O | O | O | O | O | O | O | O |
iasPubEntityId | O | O | O | O | O | O | O | O | O | O | O | O | O | O | O | O |
impressionId | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R |
inventoryType | O | O | O | O | O | O | O | O | O | O | O | O | O | O | O | O |
inView50 | O | O | O | O | O | O | O | O | R | O | O | O | O | |||
inView100 | O | O | O | O | O | O | O | O | R | O | O | O | O | |||
ip | O | |||||||||||||||
measurable | O | O | R | O | O | O | O | O | O | O | O | R | O | O | O | O |
nonContinuousPlayTime | O | O | O | O | O | O | O | O | O | O | O | |||||
placementId | O | O | O | O | O | O | O | O | O | O | O | O | O | O | O | O |
position | O | O | ||||||||||||||
skippable | O | O | ||||||||||||||
suspicious | O | O | ||||||||||||||
timestamp | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R |
type | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R |
userAgent | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R |
volume | O | O | O | O | O | O | O | O | O | O |
Video Events
Send the following JSON object with the associated property when you receive a signal that matches a video event. Signals include required and optional properties (noted in the event's Required column). If you are unable to measure an optional property, don't send that property, nor a value for it, to IAS.
Optional properties are only needed for the initial event associated with a particular ad.
Event | Description |
completed | When the 100 % point of the ad played. |
first-quartile | When the 25 % point of the ad played. |
impression | Signals the video ad occurred. |
in-view-50 | When 50 % of the area of the ad is in view for at least 2 continuous seconds. |
100-percent-in-view | When 100 % of the ad is in view, with the sound on (no sound required for native publishers), and at least half of the ad played or the ad played for 15 seconds. Note: Contact your GroupM representative to confirm your publisher category. |
100-percent-in-view-2-seconds | When 100 % of the ad is in view for at least 2 continuous seconds. |
paused | When the ad is paused. |
resized | When the ad was resized. |
resumed | When the ad transitions from a paused state to a playing state. |
second-quartile | When the 50 % point of the ad played. |
skipped | When the ad was skipped. |
started | When the ad started. |
third-quartile | When the 75 % point of the ad played. |
3-seconds-view | When 50 % of the ad is in view for at least 3 cumulative seconds. |
unload | When the ad stopped or the page unloaded. |
volume-changed | When the video's volume changed. |
completed
When the 100 % point of the ad played.
{ "event": { "type": "completed", "volume": 0.10, "nonContinuousPlayTime": 0, "advertiserId": 0, "creativeId": 1234, "fullScreen": true, "iasAdvEntityId": 1234, "iasPubEntityId": 12345, "impressionId": "1234567", "measurable": 1, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
fullScreen | true | boolean | true if the full screen mode is set or false if not in full screen mode. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
inView50 | false | boolean | true if at least 50 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria.true if at least 50 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. true if at least 50 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. true if at least 50 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
inView100 | false | boolean | true if 100 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard |
nonContinuousPlayTime | true | integer | The time, in milliseconds, that the ad played. |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
volume | false | number | The volume level from 0.00 to 1.00, where 0.00 is when there isn't any volume or the volume is muted. If you are unable to measure volume, do not pass the volume property, nor a value for it, to IAS. |
first-quartile
When the 25 % point of the ad played.
{ "event": { "type": "first-quartile", "advertiserId": 0, "campaignId": 1234, "creativeId": 1234, "fullScreen": true, "iasAdvEntityId": 1234, "iasPubEntityId": 12345, "measurable": 1, "impressionId": "1234567", "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
fullScreen | true | boolean | true if the full screen mode is set or false if not in full screen mode. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
inView50 | false | boolean | true if at least 50 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
inView100 | false | boolean | true if 100 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard |
nonContinuousPlayTime | true | integer | The time, in milliseconds, that the ad played. |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
volume | false | number | The volume level from 0.00 to 1.00, where 0.00 is when there isn't any volume or the volume is muted. If you are unable to measure volume, do not pass the volume property, nor a value for it, to IAS. |
impression
Signals that an ad occurred.
{ "event": { "type": "impression", "advertiserId": 0, "campaignId": 1234, "creativeId": 1234, "iasAdvEntityId": 1234, "iasPubEntityId": 12345, "impressionId": "1234567", "fullScreen": true, "measurable": 1, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
autoPlay | false | boolean | true if the auto play feature was on, false if it isn't on by default. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
duration | false | integer | The duration, in milliseconds, of the video ad. This is the length of the video creative itself, not necessarily the amount of time that the ad lasted. |
format | false | string | The video format, whether it's 'flash' or 'html5'. |
fullScreen | true | boolean | true if the full screen mode is set or false if not in full screen mode. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
inView50 | false | boolean | true if at least 50 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
inView100 | false | boolean | true if 100 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
ip | false | string | The IP address which generated the ad. |
ipHashed | false | string | The hashed value of the IP address. |
measurable | true | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard |
placementId | false | integer (string in v2) | This is your ID for the placement. |
position | false | string | The position of the ad, whether it is 'native', 'pre-roll', 'mid-roll' or 'post-roll'. |
skippable | false | boolean | true if the video ad is skippable or false if it isn't skippable. |
suspicious | false | boolean | Whether the impression is suspected to be from invalid traffic. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
in-view-50
When 50 % of the area of the ad is in view for at least 2 continuous seconds.
{ "event": { "type": "in-view-50", "advertiserId": 0, "campaignId": 1234, "creativeId": 1234, "iasAdvEntityId": 1234, "iasPubEntityId": 12345, "impressionId": "1234567", "fullScreen": true, "measurable": 1, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
fullScreen | true | boolean | true if the full screen mode is set or false if not in full screen mode. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
impressionId | true | string | Send impressionId for all events for an ad. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
100-percent-in-view
When 100 % of the ad is in view, with the sound on (no sound required for native publishers), and at least half of the ad played or the ad played for 15 seconds.
Note: Contact your GroupM representative to confirm your publisher category.
{ "event": { "type": "100-percent-in-view", "advertiserId": 0, "campaignId": 1234, "creativeId": 1234, "iasAdvEntityId": 1234, "iasPubEntityId": 12345, "impressionId": "1234567", "fullScreen": true, "measurable": 3, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
fullScreen | true | boolean | true if the full screen mode is set or false if not in full screen mode. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
maxContinuousViewablePlayTime50 | false | integer | The longest amount of continuous time, in milliseconds, a video ad played with 50 % of the ad in view. |
maxContinuousViewablePlayTime100 | false | integer | The longest amount of continuous time, in milliseconds, a video ad played with 100 % of the ad in view. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
100-percent-in-view-2-seconds
When 100 % of the ad is in view for at least 2 continuous seconds.
{ "event": { "type": "100-percent-in-view-2-seconds", "advertiserId": 0, "campaignId": 1234, "creativeId": 1234, "iasAdvEntityId": 1234, "iasPubEntityId": 12345, "impressionId": "1234567", "fullScreen": true, "measurable": 3, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
fullScreen | true | boolean | true if the full screen mode is set or false if not in full screen mode. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
maxContinuousViewablePlayTime50 | false | integer | The longest amount of continuous time, in milliseconds, a video ad played with 50 % of the ad in view. |
maxContinuousViewablePlayTime100 | false | integer | The longest amount of continuous time, in milliseconds, a video ad played with 100 % of the ad in view. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
paused
When the ad is paused.
{ "event": { "type": "paused", "advertiserId": 0, "campaignId": 1234, "creativeId": 1234, "fullScreen": true, "measurable": 1, "iasAdvEntityId": 1234, "iasPubEntityId": 12345, "impressionId": "1234567", "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
fullScreen | true | boolean | true if the full screen mode is set or false if not in full screen mode. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
inView50 | false | boolean | true if at least 50 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
inView100 | false | boolean | true if 100 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard |
nonContinuousPlayTime | true | integer | The time, in milliseconds, that the ad played. |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
volume | false | number | The volume level from 0.00 to 1.00, where 0.00 is when there isn't any volume or the volume is muted. If you are unable to measure volume, do not pass the volume property, nor a value for it, to IAS. |
resized
When the ad was resized.
{ "event": { "type": "resized", "size": { "width": 100, "height": 200 }, "advertiserId": 0, "campaignId": 1234, "creativeId": 1234, "fullScreen": true, "iasAdvEntityId": 1234, "iasPubEntityId": 12345, "impressionId": "1234567", "measurable": 1, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
fullScreen | true | boolean | true if the full screen mode is set or false if not in full screen mode. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
inView50 | false | boolean | true if at least 50 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
inView100 | false | boolean | true if 100 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard |
nonContinuousPlayTime | true | integer | The time, in milliseconds, that the ad played. |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
resumed
When the ad transitions from a paused state to a playing state.
{ "event": { "type": "resumed", "advertiserId": 0, "campaignId": 1234, "creativeId": 1234, "fullScreen": true, "iasAdvEntityId": 1234, "iasPubEntityId": 12345, "impressionId": "1234567", "measurable": 1, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
fullScreen | true | boolean | true if the full screen mode is set or false if not in full screen mode. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
inView50 | false | boolean | true if at least 50 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
inView100 | false | boolean | true if 100 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard |
nonContinuousPlayTime | true | integer | The time, in milliseconds, that the ad played. |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
volume | false | number | The volume level from 0.00 to 1.00, where 0.00 is when there isn't any volume or the volume is muted. If you are unable to measure volume, do not pass the volume property, nor a value for it, to IAS. |
second-quartile
When the 50 % point of the ad played.
{ "event": { "type": "second-quartile", "advertiserId": 0, "campaignId": 1234, "creativeId": 1234, "fullScreen": true, "iasAdvEntityId": 1234, "iasPubEntityId": 12345, "impressionId": "1234567", "measurable": 1, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
fullScreen | true | boolean | true if the full screen mode is set or false if not in full screen mode. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
inView50 | false | boolean | true if at least 50 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
inView100 | false | boolean | true if 100 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard |
nonContinuousPlayTime | true | integer | The time, in milliseconds, that the ad played. |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
volume | false | number | The volume level from 0.00 to 1.00, where 0.00 is when there isn't any volume or the volume is muted. If you are unable to measure volume, do not pass the volume property, nor a value for it, to IAS. |
skipped
When the ad was skipped.
{ "event": { "type": "skipped", "advertiserId": 0, "campaignId": 1234, "creativeId": 1234, "fullScreen": true, "iasAdvEntityId": 1234, "iasPubEntityId": 12345, "impressionId": "1234567", "measurable": 1, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
fullScreen | true | boolean | true if the full screen mode is set or false if not in full screen mode. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
inView50 | false | boolean | true if at least 50 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
inView100 | false | boolean | true if 100 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard |
nonContinuousPlayTime | true | integer | The time, in milliseconds, that the ad played. |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
volume | false | number | The volume level from 0.00 to 1.00, where 0.00 is when there isn't any volume or the volume is muted. If you are unable to measure volume, do not pass the volume property, nor a value for it, to IAS. |
started
When the ad started.
{ "event": { "type": "started", "advertiserId": 0, "campaignId": 1234, "creativeId": 1234, "fullScreen": true, "iasAdvEntityId": 1234, "iasPubEntityId": 12345, "impressionId": "1234567", "inView50": true, "measurable": 1, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
autoPlay | false | boolean | true if the auto play feature was on, false if it isn't on by default. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
duration | false | string | The duration, in milliseconds, of the video ad. This is the length of the video creative itself, not necessarily the amount of time that the ad lasted. |
format | false | string | The video format, whether it's 'flash' or 'html5'. |
fullScreen | true | boolean | true if the full screen mode is set or false if not in full screen mode. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inView50 | true | boolean | true if at least 50 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
inView100 | true | boolean | true if 100 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
maxContinuousViewablePlayTime50 | false | integer | The longest amount of continuous time, in milliseconds, a video ad played with 50 % of the ad in view. |
maxContinuousViewablePlayTime100 | false | integer | The longest amount of continuous time, in milliseconds, a video ad played with 100 % of the ad in view. |
measurable | true | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard |
nonContinuousPlayTime | true | integer | The time, in milliseconds, that the ad played. |
placementId | false | integer (string in v2) | This is your ID for the placement. |
position | false | string | The position of the ad, whether it is 'native', 'pre-roll', 'mid-roll' or 'post-roll'. |
skippable | false | boolean | true if the video ad is skippable or false if it isn't skippable. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
volume | false | number | The volume level from 0.00 to 1.00, where 0.00 is when there isn't any volume or the volume is muted. If you are unable to measure volume, do not pass the volume property, nor a value for it, to IAS. |
third-quartile
When the 75 % point of the ad played.
{ "event": { "type": "third-quartile", "advertiserId": 0, "campaignId": 1234, "creativeId": 1234, "fullScreen": true, "iasAdvEntityId": 1234, "iasPubEntityId": 12345, "impressionId": "1234567", "measurable": 1, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
fullScreen | true | boolean | true if the full screen mode is set or false if not in full screen mode. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
inView50 | false | boolean | true if at least 50 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
inView100 | false | boolean | true if 100 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard |
nonContinuousPlayTime | true | integer | The time, in milliseconds, that the ad played. |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
volume | false | number | The volume level from 0.00 to 1.00, where 0.00 is when there isn't any volume or the volume is muted. If you are unable to measure volume, do not pass the volume property, nor a value for it, to IAS. |
3-seconds-view
When 50 % of the ad is in view for at least 3 cumulative seconds.
{ "event": { "type": "3-seconds-view", "advertiserId": 0, "campaignId": 1234, "creativeId": 1234, "fullScreen": true, "iasAdvEntityId": 1234, "iasPubEntityId": 12345, "impressionId": "1234567", "measurable": 1, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
fullScreen | true | boolean | true if the full screen mode is set or false if not in full screen mode. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
inView50 | false | boolean | true if at least 50 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
inView100 | false | boolean | true if 100 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
unload
When the ad stopped or the page unloaded.
{ "event": { "type": "unload", "advertiserId": 0, "campaignId": 1234, "creativeId": 1234, "fullScreen": true, "iasAdvEntityId": 1234, "iasPubEntityId": 12345, "impressionId": "1234567", "measurable": 1, "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
fullScreen | true | boolean | true if the full screen mode is set or false if not in full screen mode. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
inView50 | false | boolean | true if at least 50 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
inView100 | false | boolean | true if 100 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard |
nonContinuousPlayTime | true | integer | The time, in milliseconds, that the ad played. |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
volume | false | number | The volume level from 0.00 to 1.00, where 0.00 is when there isn't any volume or the volume is muted. If you are unable to measure volume, do not pass the volume property, nor a value for it, to IAS. |
volume-changed
When the video's volume changed.
{ "event": { "type": "volume-changed", "advertiserId": 0, "campaignId": 1234, "creativeId": 1234, "fullScreen": true, "measurable": 1, "iasAdvEntityId": 1234, "iasPubEntityId": 12345, "impressionId": "1234567", "timestamp": 1331992264, "userAgent": "Mozilla/4.0" }}Property | Required | Type | Description |
advertiserId | true | integer (string in v2) | Set the advertiserId for all events for an ad. |
campaignId | true | integer (string in v2) | Set the campaignId for all events for an ad. The campaignId is your ID, not an IAS ID. |
creativeId | true | integer (string in v2) | The creative ID. |
fullScreen | true | boolean | true if the full screen mode is set or false if not in full screen mode. |
iasAdvEntityId | true | integer | IAS's advertiser entity ID. |
iasContentId | false | array of strings | Unique brand safety content ID created by the score API in the MMC API. |
iasPubEntityId | false | integer | This is IAS's ID for the placement. |
impressionId | true | string | Send impressionId for all events for an ad. |
inventoryType | false | integer | High level field to provide more granual description of the offering. Use inventoryType to identify the name of different types of ads, inventory, or other differentiation specific to their platform. |
inView50 | false | boolean | true if at least 50 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
inView100 | false | boolean | true if 100 % of the video is in view at the time of the event, or false if the video ad fails to meet this criteria. |
measurable | false | integer | Sets how the ad was measured. Set measurable to 0 when you are unable to collect viewability data. 0 – not measurable 1 – measurable by a 50 % in view standard 2 – measurable by a 100 % in view standard 3 – measurable by a 50 % and 100 % in view standard |
nonContinuousPlayTime | true | integer | The time, in milliseconds, that the ad played. |
placementId | false | integer (string in v2) | This is your ID for the placement. |
timestamp | true | integer | Set the timestamp to when this event took place in epoch milliseconds (the number of milliseconds that have elapsed since January 1, 1970 at 00:00:00 GMT). For example, "1331992264000" is Sat, 17 Mar 2012 13:51:04 GMT. |
type | true | string | The name of the event. |
userAgent | true | string | The User Agent string (for example: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.2; .NET4.0E)"). |
volume | false | number | The volume level from 0.00 to 1.00, where 0.00 is when there isn't any volume or the volume is muted. If you are unable to measure volume, do not pass the volume property, nor a value for it, to IAS. |
Example Real World Display and Video Event Sequence Scenarios
Impression events occur any time the ad loads on the page.
Display Example Sequence 1:
The ad loads. An
impressionevent occurs.The ad is fully in view for 3 seconds. The
in-viewandin-view-fullevents occur.The user closes their browser tab. The
unloadevent occurs.
Display Example Sequence 2:
The ad loads. An
impressionevent occurs.The ad is 70% in view for 10 seconds. The
in-viewevent occurs at 3 seconds, and thein-view-5-secondsevent occurs after 5 seconds.The user closes their browser tab. The
unloadevent occurs.
Display Example Sequence 3:
A small ad fewer than 242500 pixels loads and is 25% in-view for 20 seconds. Only the
impressionevent sends.
Video Example Sequence 1:
Video ad fully loads. An
impressionandad startedevent occurs.Ad is 100% in view for 2 seconds. An
100% in-view for 2 secondsevent occurs.Ad plays for 33% of the video. A
first quartileevent occurs.The user pauses the ad. An
ad-pausedevent occurs.
Video Example Sequence 2:
Video ad loads. An
impressionandad startedevent occurs.Ad is 50% in view for 5 seconds but never played. A
50%-viewableevent and3-seconds-in-viewevent occurs.The user closes the tab. An
unloadevent occurs.