Contents

Segment API - Segments for Platforms API Guide

This document provides a technical overview of segment specifications, steps, and processes necessary to implement the Integral Ad Science (IAS) segment API.

Introduction

The Pre-bid Targeting - API Segments for Platforms integration is a data information exchange service that enables customers to query the IAS to obtain information regarding a specific URL (page), IP Address, or bundle ID (mobile app). This data provides valuable information and a better understanding of content risk, content categorization, viewability, and media quality. The service is designed to use an API directly from the platform's servers to IAS. This API can be integrated to support clients' bidder lookup through wired calls over public networks resolved by IAS data centers.

During the pre-sales or integration process, you are assigned an IAS Solution Engineer representative, who provides additional documentation and support. Please use this guide, along with the Pre-bid Targeting Segments for Platforms Reference Guide to complete your integration.

Post-bid

Platforms must support IAS post-impression monitoring solution for post bid ad level reporting for post bid ad level reporting. Your IAS Solution Engineer representative provides the related implementation details and implementation guides. The following requirements are for Pre-bid targeting 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 ad level information for user, bidder, and ad are passed via a macro. This information is used, along with the bid URL macro, for IAS internal troubleshooting/analysis initiated by either platform or buyer.

  • 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 Solutions Services representative provides more details, initiates testing of such tags during integration, and provides more information during the integration process.

Usage Report Implementation Details

You need to send a usage report if you handle billing on a CPM or percent of ad spend basis.

Prior to using the Pre-Bid Segment API, you must send the following spreadsheet to:

  • Client Reporting at clientreporting@integralads.com

  • Financial Planning & Analysis at fpa@integralads.com

Also, copy your IAS DSP representative when sending the spreadsheet. Your terms and conditions agreement with IAS defines the frequency when to send this spreadsheet.

This spreadsheet is an XLS file with the following header fields. Include all fields in this exact order but you may leave optional fields empty:

Field

Type

Is Required

Notes

Date

Text

Yes

mmddyyyy format

Partner Name

Text

Yes

The name of the buying entity (agency). For example: ACME IE

Partner ID

General

Yes

For example: 12345

Advertiser Name

Text

Yes

For example: Widget IE

Advertiser ID

General

Yes

For example: 1234

Country/region/state (buying)

Text

No

For example: germany

Line item Name/Campaign Name

Text

Yes

For example: OLY-IE-WID-DESKTOP-EX

Line ID/Campaign ID

General

No

For example: 123456

Format

Text

Yes

Slash separate multiple values. Possible values:

Audio

Display

Video

For example: Display/Video

Environment

Text

Yes

Slash separate multiple values. Possible values:

In-App

Web

For example: Web/In-App

Device Type

Text

Yes

Slash separate when more than one value. Possible values:

Tablet

Desktop

Mobile

CTV

For example: Tablet/Desktop

Segment Type/Category

Text

Yes

IAS segment type. Possible values:

Brand Safety

Viewability

IVT

Context control avoidance

Context control targeting

Quality Impression

Segment Category ID

General

No

Segment Category ID defined by a DSP. Consult your DSP for a list of segment category IDs.

Context Control Specific ID

General

No

IAS specific segment ID for the context control segment. For example: 1500195

Impressions

Number

Yes

Zero decimal places. For example: 9,876,543,210

Segment CPM Rate

Currency

No

The Segment CMP rate which follows the rate card. If not using the rate card, indicate the preferred pricing. Use USD for the currency, unless your terms and conditions agreement specifies differently. For example: $.05

Revenue

Currency

Yes

Use USD for the currency, unless your terms and conditions agreement specifies differently. For example: $123,456.78

For example:

prebidDetails

The Pre-bid API endpoint response is accessible over HTTP. This API returns the segment IDs (alpha description) or segment codes (integer values) as a JSON response which you must parse to support your bidder infrastructure.

http://{API Host Name}/db2/client/{Client ID}/{Data Method}

Resource

Value

Description

API Host Name

Desktop / Mobile Web or Mobile App specific

Hostname

Client ID

IAS supplied

Static client ID IAS supplies to determine authorization and permission to access the API

Data Method

seg or segt

Determines how IAS returns results. seg = code response segt = ID response

Desktop / Mobile Web Segments

http://api.adsafeprotected.com/db2/client/{client ID}/{Data Method}?adsafe_url={URL}&adsafe_ip={IP address}

The Desktop / Mobile Web Segments have the following query parameters:

Query Parameter

Value

Description

adsafe_url

Primary key URL to be rated

An optional parameter, adsafe_url is a URL coming from the client's bidder to obtain an IAS rating. The URL can be percent- encoded/URL encoded or non-URL encoded.

IAS rates the adsafe_url on brand safety protection, invalid traffic, and viewability segments.

adsafe_url can be used with adsafe_ip, or separately.

adsafe_ip

IPv4 address from the bid request

An optional parameter,

adsafe_ip is the IPV4 address you want to evaluate for invalid traffic.

adsafe_ip provides real-time invalid traffic prevention against bots and machines.

adsafe_ip can be used with adsafe_url, or separately.

Examples for adsafe_url

The following examples show a segment code and ID.

Data Method = seg

Method

Example

Request

http://api.adsafeprotected.com/db2/client/{client ID}/seg?adsafe_url={URL to be rated}

Response

{"segment_codes":["ESA","ESAHM","ESAV","ESAHMV","EHAD", "EHMAD","EHADV","EHMADV","EHAL","EHMAL","EHALV","EHMALV","EHDL","EHMDL", "EHDLV","EHMDLV","EHDG","EHMDG","EHDGV", "EHMDGV","EHHT","EHMHT","EHHTV","EHMHTV", "EHOF","EHMOF","EHOFV","EHMOFV", "EUNR","EUNRV","EHVIO","EHMVIO","EHVIOV", "EHMVIOV","VTOP35","VTOP50","VTOP75","VV40"]}

Data Method = segt

Method

Example

Request

http://api.adsafeprotected.com/db2/client/{client ID}/segt?adsafe_url={URL to be rated}

Response

{"segment_ids":["307649","307746", "307804","402116","402117", "402119","402120","402121","402122", "402123","402124","402125","402126", "402127","402129","402142","560997","1344417","1344423","1464917"]}

Examples for adsafe_ip

The following examples show a segment code and ID.

Data Method = seg

Method

Example

Request

http://api.adsafeprotected.com/db2/client/123/seg?adsafe_ip=<IP>

Response

segment_codes:["ESAIPH"]}

Data Method = segt

Method

Example

Request

http://api.adsafeprotected.com/db2/client/123/segt?adsafe_ip=<IP>

Response

{segment_ids:["411"]}

Example for adsafe_url and adsafe_ip

The following examples show a segment code and ID.

Data Method = seg

Method

Example

Request

http://api.adsafeprotected.com/db2/client/123/seg?adsafe_url=http://www.example.com&adsafe_ip=111.222.333.444

Response

{"segment_codes":["ESA","ESAHM","ESAV", "ESAHMV","EHAD","EHMAD","EHADV", "EHMADV","EHAL","EHMAL","EHALV","EHMALV", "EHDL","EHMDL","EHDLV","EHMDLV","EHDG","EHMDG", "EHDGV","EHMDGV","EHHT","EHMHT","EHHTV","EHMHTV", "EHOF","EHMOF","EHOFV","EHMOFV","EUNR","EUNRV", "EHVIO","EHMVIO","EHVIOV","EHMVIOV","VTOP35", "VTOP50","VTOP75","VV40","ESAIPH"]}

Data Method = segt

Method

Example

Request

http://api.adsafeprotected.com/db2/client/123/segt?adsafe_url=http://www.example.com&adsafe_ip=111.222.333.444

Response

{"segment_ids":["307649","307746","307804","402116","402117", "402119","402120","402121","402122","402123","402124", "402125","402126","402127","402129","402142","560997", "1344417","1344423","1464917","411"]}

Caching Guidelines

IAS recommends the following caching guidelines/best practices:

  • 8 hours for IP Address

  • 23 hours for URL

Mobile App REST Endpoint

IAS created a dedicated endpoint exclusive to mobile app Pre-bid API requests which follows a standard level-2 REST style API. IAS recommends using the mobile app REST endpoint for integrating partners with mobile app for existing and new clients.

IAS offers the endpoint appapi.adsafeprotected.com sub-domain for clients who require segment data responses to be backwards compatible with the existing web specific endpoints.

You must preserve case when sending package names to the Pre-bid API. Otherwise, IAS may use the wrong app, or even fail to identify any app (which returns an empty segment response).

Query Parameter

Value

Description

bundle_id

Apple IDs are numeric, while Android IDs are stringsApple and Android package names are strings.

Identifies an app and is required. Apple or Android store ID, or software package name.

app_store

apple or android

The app store value, either for Apple or Android

content_id

String

Content identifier that allows IRIS-enabled publishers to share video-level data for advertising applications

encoded_user_agent

Encoded user agent from bid request

Use when the App Store value is not available

Data Method = seg

Method

Example

Request

GET http://appapi.adsafeprotected.com/db2/client/{client ID}/seg?bundle_id={bundle ID to be rated}&app_store={APP STORE}

Response

{"segment_codes":["EHALA","EHMALA","EHDLA","EHMDLA","EHDGA","EHMDGA"]}

Data Method = segt

Method

Example

Request

GET http://appapi.adsafeprotected.com/db2/client/{client ID}/segt?bundle_id={bundle ID to be rated}&app_store={APP STORE}

Response

{"segment_ids":["4000","4001","4002","4003","4004","4005","4006","4007","4008"]}

Mobile App Parameters

All responses match the response format setup on the current display/video api.adsafeprotected.com endpoint.

Bundle ID

There are two ways to specify a bundle_id to identify an app:

  • Apple or Android store ID – Apple IDs are numeric, while Android IDs are strings.

  • Software package name – both Apple and Android package names are strings. Android package names are always the same as the Android store IDs.

Examples of bundle IDs:

  • Apple App Store: 416580485.

  • Android Play store: bbc.iplayer.android

  • Apple package name: bbc.iplayer.ios

App store

To retrieve brand safety scores for a mobile app, IAS requires an App Store value (or an encoded user agent when the App Store value is not available). For example:

http://appapi.adsafeprotected.com/db2/client/{client ID}/{Data Method }?bundle_id={BUNDLE ID}&app_store={APP STORE}

Encoded user agent

Provide an encoded user agent when the App Store value is not available. For example:

http://appapi.adsafeprotected.com/db2/client/{client ID}/{Data Method }?bundle_id={BUNDLE ID}&encoded_user_agent={ENCODED USER AGENT}

Caching Guidelines

IAS recommends a 24 hour caching guidelines/best practice for the bundle ID.

Cache-Control

IAS recommends the following aching guidelines/best practices:

  • 24 hour for the bundle ID

  • 8 hours for IP Address

  • 23 hours for URL

Cache-Control Header

The Pre-bid API for Desktop/Mobile Web and Mobile App uses the HTTP header Cache-Control with max-age= set to the cache time in seconds. If there are any internal errors, IAS sets Cache-Control: no-cache.

Environment

max-age in Seconds

Desktop/Mobile Web

28800

Mobile App

82800

If there are any internal errors on Desktop/Mobile Web, IAS sets Cache-Control: no-cache. (Mobile App doesn't support no-cache.)

During the pre-sales or integration process, IAS assigns a representative to provide additional documentation and support.

No cache HTTP header:

HTTP/1.1 200 OK
Server: abc
Date: Fri, 31 Mar 2020 18:37:10 GMT
Content-Type: text/html;charset=utf-8
Content-Length: 0
Connection: keep-alive
Cache-Control: no-cache

Max age HTTP header for Desktop/Mobile Web:

HTTP/1.1 200 OK
Server: abc
Date: Fri, 31 Mar 2020 18:37:10 GMT
Content-Type: text/html;charset=utf-8
Content-Length: 0
Connection: keep-alive
Cache-Control: max-age=28800

Max age HTTP header for Mobile App:

HTTP/1.1 200 OK
Server: abc
Date: Fri, 28 Aug 2020 18:37:10 GMT
Content-Type: text/html;charset=utf-8
Content-Length: 0
Connection: keep-alive
Cache-Control: max-age=82800

Authentication

IAS uses the OAuth 2.0 Authorization Framework for authorization with the Pre-bid API. OAuth 2.0 provides enhanced security on restricted resources adding an extra level of data security without sending a username and password in each request.

You need to register with IAS to get a client ID and secret which are used to obtain a token. Then the token is used to make the request to the Pre-bid API.

Area

URI

Token URI

https://auth.adsafeprotected.com/uaa/oauth/token

Desktop / Mobile Web Segments URI Base

http://api.adsafeprotected.com/db2/client/<client ID>/seg

Mobile App Segment URI Base

http://appapi.adsafeprotected.com/db2/client/<client ID>/seg

Summary of steps:

  1. Coordinate with IAS on client ID and secret

  2. Acquire token

  3. Make requests using the token

See Authentication Sample for a complete example.

Step 1. Coordinate Client ID and Secret

Consult with your IAS Solution Engineer representative for a client ID and client secret which you use when you request a token.

Step 2. Get the Token

You must use the client_credentials grant type to obtain a token. Once generated, you can re-use the token with multiple requests to the Pre-bid API until the token expires (the expiration time is specified in the response JSON which includes the access token, the token type, and the scope).

An authentication example using the Unix curl utility and sample output.

curl -H "Accept: application/json" -u clientID:clientSecret https://auth.adsafeprotected.com/uaa/oauth/token -d grant_type=client_credentials
{ "access_ token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsicHJlQmlkIl0sInNjb3Bl IjpbInByZUJpZC5zZWciXSwiZXhwIjoxNTA0NjU5MzEzLCJqdGkiOiI2MWJmZDQ5OC1mYzE2LTQ3Y jItYTYwMi0yZGY1ZmI5MDc4MTQiLCJjbGllbnRfaWQiOiIxMTkyMiJ9.vloa0uLR2xQ_ nmoFUkLowran6TneiIPzmHMzW2mtduo", "token_type":"bearer", "expires_in":21599, "scope":"preBid.seg", "jti":"6ccae353-161e-4a41-a1f3-aadd7a1e5898" }

Parameter

Description

{client ID}:{client secret}

client ID and secret, separated by a colon

grant_type

set to

client_credentials

The token request returns JSON with the following values:

Value

Description

access_token

token to use in the authorization header for requests to the Pre-bid API

token_type

defines how the

access_token

was generated and how to make requests

expires_in

token expiration time in seconds

scope

where the token is applicable

jti

identifier used for IAS's internal diagnostics

Step 3. Use the Token

Use the token in an authorization header GET request to the Pre-bid API. IAS has an end point for desktop / mobile web and mobile app segments. See API Endpoint Information Details for more information on the desktop / mobile web and mobile app segments.

Desktop / Mobile Web

curl -H "Authorization:bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsicHJlQmlkIl0sInNjb3BlIjpbInByZUJpZC5zZWciXSwiZXhwIjoxNTA0NjU5MzEzLCJqdGkiOiI2MWJmZDQ5OC1mYzE2LTQ3YjItYTYwMi0yZGY1ZmI5MDc4MTQiLCJjbGllbnRfaWQiOiIxMTkyMiJ9.vloa0uLR2xQ_nmoFUkLowran6TneiIPzmHMzW2mtduo "http://api.adsafeprotected.com/db2/client/123/seg?adsafe_url=http://www.example.com&adsafe_ip=11.222.333.44"
{"segment_codes": ["Passed","EHAD","EHMAD","EHAL","EHMAL","EHDL","EHMDL","EHDG","EHMDG","EHHT", "EHMHT","EHOF","EHMOF","LANEN","EHADV","EHMADV","EHALV","EHMALV","EHDLV","EHM DLV","EHDGV","EHMDGV","EHHTV","EHMHTV","EHOFV","EHMOFV","EHVIO","EHMVIO","EHV IOV","EHMVIOV","ERBSV","EHMLDLV","ERBS","EHMLDL"]}

Mobile App

curl -H "Authorization:bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsicHJlQmlkIl0sInNjb3BlIjpbInByZUJpZC5zZWciXSwiZXhwIjoxNTA0NjU5MzEzLCJqdGkiOiI2MWJmZDQ5OC1mYzE2LTQ3YjItYTYwMi0yZGY1ZmI5MDc4MTQiLCJjbGllbnRfaWQiOiIxMTkyMiJ9.vloa0uLR2xQ_nmoFUkLowran6TneiIPzmHMzW2mtduo" "http://appapi.adsafeprotected.com/db2/client/48956/seg?bundle_id=123456789"
{ "segment_codes": ["EHADA", "EHMADA", "EHALA", "EHMALA", "EHDLA", "EHMDLA", "EHDGA", "EHMDGA", "EHGA", "EHMGA", "EHOFA", "EHMOFA", "EHVIOA", "EHMVIOA", "EUNRA" ]}
curl -v -H "Authorization:bearer <token>" "http://appapi.adsafeprotected.com/db2/client/<client ID>/seg?bundle_id=123456789""

Responses

The OAuth 2.0 server returns the following responses:

Response Code

Response

Description

200

OK

The request passed

403

Forbidden

The OAuth 2.0 server found an error with an invalid, forbidden, a No Token or an expired token. If the token is expired, you need to acquire a new token as detailed in the section Step 2. Get the token.

API Segment Categories

IAS API segments are divided into Desktop/Mobile Web and Mobile App Segments.

Viewability Targeting

IAS viewability targeting benefits from the highest accuracy and precision. IAS recommends you choose one segment per campaign based upon your business needs. Each segment contains inventory that includes that level of viewability and higher. The presence of the segment means it is good to serve the ad. IAS requires new DSPs observe a two-week warm-up period for only test traffic, while IAS collects data and calibrates the segments. Additional targeting parameters may affect realized results for any specific campaign.

Note: As of the publication date of this document, the IAB qualification for a display viewable ad is 50% of the ad is in view for 1 continuous second and for a viewable video ad is 50% of the ad is in view for 2 continuous seconds.

Desktop/Mobile Web Segments/All

MRC

Seg Code

Seg ID

Segment Description

Format

Channel

PM40D

140

Target 40% viewability or higher for display campaigns

Display

All

PM50D

150

Target 50% viewability or higher for display campaigns

Display

All

PM60D

160

Target 60% viewability or higher for display campaigns

Display

All

PM70D

170

Target 70% viewability or higher for display campaigns

Display

All

PM40DD

940

Target 40% viewability or higher for display campaigns

Display

Desktop

PM40DM

640

Target 40% viewability or higher for display campaigns on mobile web

Display

Mobile Web

PM40V

92640

Target 40% viewability or higher for video campaigns

Video

All

PM40VD

92040

Target 40% viewability or higher for desktop video campaigns

Video

Desktop

PM40VM

92340

Target 40% viewability or higher for mobile web video campaigns

Video

Mobile Web

PM50DD

950

Target 50% viewability or higher for display campaigns

Display

Desktop

PM50DM

650

Target 50% viewability or higher for display campaigns on mobile web

Display

Mobile Web

PM50V

92650

Target 50% viewability or higher for video campaigns

Video

All

PM50VD

92050

Target 50% viewability or higher for desktop video campaigns

Video

Desktop

PM50VM

92350

Target 50% viewability or higher for mobile web video campaigns

Video

Mobile Web

PM60DD

960

Target 60% viewability or higher for display campaigns

Display

Desktop

PM60DM

660

Target 60% viewability or higher for display campaigns mobile web

Display

Mobile Web

PM60V

92660

Target 60% viewability or higher for video campaigns

Video

All

PM60VD

92060

Target 60% viewability or higher for desktop video campaigns

Video

Desktop

PM60VM

92360

Target 60% viewability or higher for mobile web video campaigns

Video

Mobile Web

PM70DD

970

Target 70% viewability or higher for display campaigns

Display

Desktop

PM70DM

670

Target 70% viewability or higher for display campaigns mobile web

Display

Mobile Web

PM70V

92670

Target 70% viewability or higher for video campaigns

Video

All

PM70VD

92070

Target 70% viewability or higher for desktop video campaigns

Video

Desktop

PM70VM

92370

Target 70% viewability or higher for mobile web video campaigns

Video

Mobile Web

PMLD

9140

Target up to 40% viewability for display campaigns

Display

All

PMLDD

930

Target up to 40% viewability for display campaigns

Display

Desktop

PMLDM

639

Target up to 40% viewability for display campaigns on mobile web

Display

Mobile Web

PMLV

92630

Target up to 40% viewability for video campaigns

Video

All

PMLVD

92030

Target up to 40% viewability for desktop video campaigns

Video

Desktop

PMLVM

92330

Target up to 40% viewability for mobile web video campaigns

Video

Mobile Web

Viewability - MRC Performance Matching by Ad Size

Seg Code

Seg ID

Segment Description

Format

Channel

PM40D_160x600

141

Target 40% viewability or higher for display campaigns for ad size 160x600

Display

All

PM40D_300x250

144

Target 40% viewability or higher for display campaigns for ad size 300x250

Display

All

PM40D_320x50

142

Target 40% viewability or higher for display campaigns for ad size 320x50

Display

All

PM40D_728x90

143

Target 40% viewability or higher for display campaigns for ad size 728x90

Display

All

PM40DD_160x600

941

Target 40% viewability or higher for display campaigns for ad size 160x600

Display

Desktop

PM40DD_300x250

942

Target 40% viewability or higher for display campaigns for ad size 300x250

Display

Desktop

PM40DD_728x90

943

Target 40% viewability or higher for display campaigns for ad size 728x90

Display

Desktop

PM40DM_300x250

641

Target 40% viewability or higher for mobile web display campaigns for ad size 300x250

Display

Mobile Web

PM40DM_320x50

642

Target 40% viewability or higher for mobile web display campaigns for ad size 320x50

Display

Mobile Web

PM40DM_728x90

643

Target 40% viewability or higher for mobile web display campaigns for ad size 728x90

Display

Mobile Web

PM50D_160x600

151

Target 50% viewability or higher for display campaigns for ad size 160x600

Display

All

PM50D_300x250

154

Target 50% viewability or higher for display campaigns for ad size 300x250

Display

All

PM50D_320x50

152

Target 50% viewability or higher for display campaigns for ad size 320x50

Display

All

PM50D_728x90

153

Target 50% viewability or higher for display campaigns for ad size 728x90

Display

All

PM50DD_160x600

951

Target 50% viewability or higher for display campaigns for ad size 160x600

Display

Desktop

PM50DD_300x250

952

Target 50% viewability or higher for display campaigns for ad size 300x250

Display

Desktop

PM50DD_728x90

953

Target 50% viewability or higher for display campaigns for ad size 728x90

Display

Desktop

PM50DM_300x250

651

Target 50% viewability or higher for mobile web display campaigns for ad size 300x250

Display

Mobile Web

PM50DM_320x50

652

Target 50% viewability or higher for mobile web display campaigns for ad size 320x50

Display

Mobile Web

PM50DM_728x90

653

Target 50% viewability or higher for mobile web display campaigns for ad size 728x90

Display

Mobile Web

PM60D_160x600

161

Target 60% viewability or higher for display campaigns for ad size 160x600

Display

All

PM60D_300x250

164

Target 60% viewability or higher for display campaigns for ad size 300x250

Display

All

PM60D_320x50

162

Target 60% viewability or higher for display campaigns for ad size 320x50

Display

All

PM60D_728x90

163

Target 60% viewability or higher for display campaigns for ad size 728x90

Display

All

PM60DD_160x600

961

Target 60% viewability or higher for display campaigns for ad size 160x600

Display

Desktop

PM60DD_300x250

962

Target 60% viewability or higher for display campaigns for ad size 300x250

Display

Desktop

PM60DD_728x90

963

Target 60% viewability or higher for display campaigns for ad size 728x90

Display

Desktop

PM60DM_300x250

661

Target 60% viewability or higher for mobile web display campaigns for ad size 300x250

Display

Mobile Web

PM60DM_320x50

662

Target 60% viewability or higher for mobile web display campaigns for ad size 320x50

Display

Mobile Web

PM60DM_728x90

663

Target 60% viewability or higher for mobile web display campaigns for ad size 728x90

Display

Mobile Web

PM70D_160x600

171

Target 70% viewability or higher for display campaigns for ad size 160x600

Display

All

PM70D_300x250

174

Target 70% viewability or higher for display campaigns for ad size 300x250

Display

All

PM70D_320x50

172

Target 70% viewability or higher for display campaigns for ad size 320x50

Display

All

PM70D_728x90

173

Target 70% viewability or higher for display campaigns for ad size 728x90

Display

All

PM70DD_160x600

971

Target 70% viewability or higher for display campaigns for ad size 160x600

Display

Desktop

PM70DD_300x250

972

Target 70% viewability or higher for display campaigns for ad size 300x250

Display

Desktop

PM70DD_728x90

973

Target 70% viewability or higher for display campaigns for ad size 728x90

Display

Desktop

PM70DM_300x250

671

Target 70% viewability or higher for mobile web display campaigns for ad size 300x250

Display

Mobile Web

PM70DM_320x50

672

Target 70% viewability or higher for mobile web display campaigns for ad size 320x50

Display

Mobile Web

PM70DM_728x90

673

Target 70% viewability or higher for mobile web display campaigns for ad size 728x90

Display

Mobile Web

PMLDD_160x600

931

Target up to 40% viewability for display campaigns for ad size 160x600

Display

Desktop

PMLDD_300x250

932

Target up to 40% viewability for display campaigns for ad size 300x250

Display

Desktop

PMLDD_728x90

933

Target up to 40% viewability for display campaigns for ad size 728x90

Display

Desktop

Viewability - Time In-View

Seg Code

Seg ID

Segment Description

Format

Channel

TIVADD

9000

Target the top 30% of pages with longest time-in-view duration for display on desktop

Display

Desktop

TIVCDD

9002

Target the top 15% of pages with longest time-in-view duration for display on desktop

Display

Desktop

Mobile App Segments

Viewability - MRC Performance Matching

Seg Code

Seg ID

Segment Description

Format

Channel

PM40DA

4040

Target 40% viewability or higher for mobile app display campaigns

Display

Mobile App

PM50DA

4050

Target 50% viewability or higher for mobile app display campaigns

Display

Mobile App

PM60DA

4060

Target 60% viewability or higher for mobile app display campaigns

Display

Mobile App

PM70DA

4070

Target 70% viewability or higher for mobile app display campaigns

Display

Mobile App

PMLDA

4030

Target up to 40% viewability for mobile app display campaigns

Display

Mobile App

Invalid Traffic Prevention

Desktop/Mobile Web Segments

IAS invalid traffic prevention provides comprehensive coverage against both general invalid traffic (GIVT) and sophisticated invalid traffic (SIVT). A combination of predictive and real-time signals identifies and avoid site and bot invalid traffic - IAS technology is inclusive of URL, IP, and User Agent invalid traffic data. The invalid traffic prevention segments exclude/avoid invalid traffic risks. The presence of the segment means it is good to serve the ad. Using proprietary machine learning, algorithmic modeling, and human verification, IAS rates the risk that a website or the advertisements appearing on it are associated with illegal or deceptive activity such as click fraud or invalid traffic.

IAS provides the following invalid traffic segments in the bid requests:

Seg Code

Seg ID

Segment Description

Format

Channel

ESA

401

Avoid HIGH risk invalid traffic pages as rated by IAS

Display

Desktop

ESAHM

402

Avoid HIGH and MODERATE risk invalid traffic pages as rated by IAS

Display

Desktop

ESAHMV

407

Avoid HIGH and MODERATE risk invalid traffic video pages as rated by IAS

Video

Desktop

ESAIPH

411

Avoid IP addresses which IAS has identified as invalid traffic

All

All

ESAUNR

400

Avoid pages which IAS has not rated for invalid traffic

Display

Desktop

ESAUNRV

410

Avoid video pages which IAS has not rated for invalid traffic

Video

Desktop

ESAV

404

Avoid HIGH risk invalid traffic video pages as rated by IAS

Video

Desktop

Mobile App Segments

Seg Code

Seg ID

Segment Description

Format

Channel

ESAA

4016

Avoid HIGH risk invalid traffic content apps as rated by IAS

Display

Mobile App

ESAAV

8016

Avoid HIGH risk invalid traffic content apps for video as rated by IAS

Video

Mobile App

ESAHMA

4017

Avoid HIGH and MODERATE risk invalid traffic content apps as rated by IAS

Display

Mobile App

ESAHMAV

8017

Avoid HIGH and MODERATE risk invalid traffic content apps for video as rated by IAS

Video

Mobile App

ESAUNRA

4015

Avoid apps which IAS has not rated for invalid traffic

Display

Mobile App

ESAUNRAV

8015

Avoid apps for video which IAS has not rated for invalid traffic

Video

Mobile App

Brand Safety Protection

IAS brand safety protection ensures campaigns align with quality content via 8 categories and a custom segments. The brand safety scoring uses a predictive methodology that applies keyword and analysis. IAS dynamically updates the page-level scores. The brand safety prevention segments exclude/avoid brand safety risks. The presence of the segment means it is good to serve the ad. IAS recommends implementing AND logic between multiple brand safety categories.

IAS provides the following brand safety protection segments in the bid requests:

Segment Category

Web

App

Avoid Pages or Apps Rated As

Adult

Yes

Yes

HIGH and MODERATE risk for adult content

Alcohol

Yes

Yes

HIGH and MODERATE risk for alcohol content

Gambling


Yes

HIGH and MODERATE risk for gambling content

Hate Speech

Yes

Yes

HIGH and MODERATE risk for hate speech content

Illegal Downloads

Yes

Yes

HIGH, MODERATE, and LOW risk for illegal download content. Only URLs rated as no risk (rating = 1000) are targeted.

Illegal Drugs

Yes

Yes

HIGH and MODERATE risk for drug content

Offensive Language

Yes

Yes

HIGH and MODERATE risk for offensive language content

Violence

Yes

Yes

HIGH and MODERATE risk for violent content

Unrateable

Yes

Yes

Avoid pages marked unrateable (For example, "blind" URLs, ad server URLs, ad network URLs, doubleclick.net, yieldmanager.com, IP addresses, etc.). For mobile app, this applies to apps not available on iTunes or the Google Play stores.

Using proprietary machine learning, algorithmic modeling, and human verification, IAS rates the risk profile of content in the following risk segments.

Brand Risk

Definition

Low Risk

Generally acceptable content for all ages and audiences; does not typically contain anything offensive in nature or theme

Moderate Risk

Moderate content, typically acceptable for brands. However, caution needs to be given to subjective nature of content (for example, alcohol, tobacco or partial nudity, such as swimsuits).

High Risk

Graphic content, typically moderately offensive but not illegal. High probability that this is offensive for leading brands/advertisers.

Desktop/Mobile Web Segments

Seg Code

Seg ID

Segment Description

Format

Channel

EHAD

501

Avoid HIGH risk adult content pages as rated by IAS

Display

Desktop

EHADV

535

Avoid HIGH risk adult content pages for video as rated by IAS

Video

Desktop

EHAL

503

Avoid HIGH risk alcohol content pages as rated by IAS

Display

Desktop

EHALV

537

Avoid HIGH risk alcohol content pages for video as rated by IAS

Video

Desktop

EHDG

507

Avoid HIGH risk drug content pages as rated by IAS

Display

Desktop

EHDGV

541

Avoid HIGH risk drug content pages for video as rated by IAS

Video

Desktop

EHDL

505

Avoid HIGH risk illegal download content pages as rated by IAS

Display

Desktop

EHDLV

539

Avoid HIGH risk illegal download content pages for video as rated by IAS

Video

Desktop

EHHT

509

Avoid HIGH risk hate speech content pages as rated by IAS

Display

Desktop

EHHTV

543

Avoid HIGH risk hate speech content pages for video as rated by IAS

Video

Desktop

EHMAD

502

Avoid HIGH and MODERATE risk adult content pages as rated by IAS

Display

Desktop

EHMADV

536

Avoid HIGH and MODERATE risk adult content pages for video as rated by IAS

Video

Desktop

EHMAL

504

Avoid HIGH and MODERATE risk alcohol content pages as rated by IAS

Display

Desktop

EHMALV

538

Avoid HIGH and MODERATE risk alcohol content pages for video as rated by IAS

Video

Desktop

EHMDG

508

Avoid HIGH and MODERATE risk drug content pages as rated by IAS

Display

Desktop

EHMDGV

542

Avoid HIGH and MODERATE risk drug content pages for video as rated by IAS

Video

Desktop

EHMDL

506

Avoid HIGH and MODERATE risk illegal download content pages as rated by IAS

Display

Desktop

EHMDLV

540

Avoid HIGH and MODERATE risk illegal download content pages for video as rated by IAS

Video

Desktop

EHMHT

510

Avoid HIGH and MODERATE risk hate speech content pages as rated by IAS

Display

Desktop

EHMHTV

544

Avoid HIGH and MODERATE risk hate speech content pages for video as rated by IAS

Video

Desktop

EHMOF

512

Avoid HIGH and MODERATE risk offensive language content pages as rated by IAS

Display

Desktop

EHMOFV

546

Avoid HIGH and MODERATE risk offensive language content pages for video as rated by IAS

Video

Desktop

EHMVIO

532

Avoid HIGH and MODERATE risk violence pages as rated by IAS

Display

Desktop

EHMVIOV

534

Avoid HIGH and MODERATE risk violence pages for video as rated by IAS

Video

Desktop

EHOF

511

Avoid HIGH risk offensive language content pages as rated by IAS

Display

Desktop

EHOFV

545

Avoid HIGH risk offensive language content pages for video as rated by IAS

Video

Desktop

EHVIO

531

Avoid HIGH risk violence pages as rated by IAS

Display

Desktop

EHVIOV

533

Avoid HIGH risk violence pages for video as rated by IAS

Video

Desktop

EUNR

513

Avoid pages which IAS CANNOT RATE (for example, "blind" URLs, ad server URLS, ad network URLs, doubleclick.net, yieldmanager.com, IP addresses, etc.)

Display

Desktop

EUNRV

551

Avoid pages which IAS CANNOT RATE (for example, "blind" URLs, ad server URLS, ad network URLs, doubleclick.net, yieldmanager.com, IP addresses, etc.) for video

Video

Desktop

Mobile App Segments

IAS supports brand safety protection segments for mobile app display. The following targeting definitions are the standard for mobile app display and video brand safety protection categories and are only applicable to the mobile app inventory supply. IAS rates all apps using these standard segments:

Seg Code

Seg ID

Segment Description

Format

Channel

EHADA

4000

Avoid HIGH risk adult content apps as rated by IAS

Display

Mobile App

EHADAV

8000

Avoid HIGH risk adult content apps for video as rated by IAS

Video

Mobile App

EHALA

4002

Avoid HIGH risk alcohol content as rated by IAS

Display

Mobile App

EHALAV

8002

Avoid HIGH risk alcohol content apps for video as rated by IAS

Video

Mobile App

EHDGA

4006

Avoid HIGH risk drug content apps as rated by IAS

Display

Mobile App

EHDGAV

8006

Avoid HIGH risk drug content apps for video apps as rated by IAS

Video

Mobile App

EHDLA

4004

Avoid HIGH risk illegal download content apps as rated by IAS

Display

Mobile App

EHDLAV

8004

Avoid HIGH risk illegal download content apps for video as rated by IAS

Video

Mobile App

EHGA

4008

Avoid HIGH risk gambling apps as rated by IAS

Display

Mobile App

EHGAV

8008

Avoid HIGH risk gambling apps for video as rated by IAS

Video

Mobile App

EHHTA

4018

Avoid HIGH risk hate speech content apps as rated by IAS

Display

Mobile App

EHHTAV

8018

Avoid HIGH risk hate speech content apps for video as rated by IAS

Video

Mobile App

EHMADA

4001

Avoid HIGH and MODERATE risk adult content apps as rated by IAS

Display

Mobile App

EHMADAV

8001

Avoid HIGH and MODERATE risk adult content apps for video as rated by IAS

Video

Mobile App

EHMALA

4003

Avoid HIGH and MODERATE risk alcohol content apps as rated by IAS

Display

Mobile App

EHMALAV

8003

Avoid HIGH and MODERATE risk alcohol content apps for video as rated by IAS

Video

Mobile App

EHMDGA

4007

Avoid HIGH and MODERATE risk drug content apps as rated by IAS

Display

Mobile App

EHMDGAV

8007

Avoid HIGH and MODERATE risk drug content apps for video as rated by IAS

Video

Mobile App

EHMDLA

4005

Avoid HIGH and MODERATE risk illegal download content apps as rated by IAS

Display

Mobile App

EHMDLAV

8005

Avoid HIGH and MODERATE risk illegal download content apps for video as rated by IAS

Video

Mobile App

EHMGA

4009

Avoid HIGH and MODERATE risk gambling content apps as rated by IAS

Display

Mobile App

EHMGAV

8009

Avoid HIGH and MODERATE risk gambling content apps for video as rated by IAS

Video

Mobile App

EHMHTA

4019

Avoid HIGH and MODERATE hate speech content apps as rated by IAS

Display

Mobile App

EHMHTAV

8019

Avoid HIGH and MODERATE hate speech content apps for video as rated by IAS

Video

Mobile App

EHMOFA

4011

Avoid HIGH and MODERATE risk offensive language content apps as rated by IAS

Display

Mobile App

EHMOFAV

8011

Avoid HIGH and MODERATE risk offensive language content apps for video as rated by IAS

Video

Mobile App

EHMVIOA

4013

Avoid HIGH and MODERATE risk violence content apps as rated by IAS

Display

Mobile App

EHMVIOAV

8013

Avoid HIGH and MODERATE risk violence content apps for video as rated by IAS

Video

Mobile App

EHOFA

4010

Avoid HIGH risk offensive language content apps as rated by IAS

Display

Mobile App

EHOFAV

8010

Avoid HIGH risk offensive language content apps for video as rated by IAS

Video

Mobile App

EHVIOA

4012

Avoid HIGH risk violence content apps as rated by IAS

Display

Mobile App

EHVIOAV

8012

Avoid HIGH risk violence content for video apps as rated by IAS

Video

Mobile App

EUNRA

4014

Avoid valid apps, which IAS has not rated or cannot rate (for example, new apps, private/blind apps, apps without or limited descriptions, etc.)

Display

Mobile App

EUNRAV

8014

Avoid valid apps, which IAS has not rated or cannot rate (for example, new apps, private/blind apps, apps without or limited descriptions, etc.) for video

Video

Mobile App

Custom Segments

Custom segments allow you to meet your clients' requirements while ensuring advertisers meet their campaign goals and minimize their post-bid blocking. IAS supports custom segments on Desktop and Mobile Web channels with:

  • Brand Safety Protection

    • Context Control Avoidance

    • Context Control Targeting

  • Quality Sync Pre-bid Segments

In order to access the new custom segments, IAS activates the custom segment within the Pre-bid API. IAS needs three hours to enable the custom segment. Once enabled, you can query the Pre-bid API for the segments. Then you should refresh your cache so your application can respond accordingly.

Custom segments apply to web and mobile web inventory only (Quality Sync Pre-bid Segments apply to web and mobile app inventory).

Type

Seg Code

Seg ID

Targeting Methodology

Includes Mobile App

Notes

Context Control Avoidance

IAS_<Unique ID>_PG

A number between 1,000,002- 1,999,999

Negative targeting

No

Not eligible for the campaign

Context Control Targeting

IAS_<Unique ID>_PG

A number between 3,000,000- 3,999,999

Positive targeting

No

Eligible for the campaign

Quality Sync Pre-bid Segments

IAS_<Unique ID>_MS

A number between 4,000,000-4,999,999

Positive Targeting

Yes

Eligible for the campaign

In-app Exclusion list

IAS_<Unique ID>_BL

A number between 5,000,000-5,999,999

Negative targeting

Yes

Exclusion lists, not eligible for the campaign

In-app Inclusion list

IAS_<Unique ID>_WL

A number between 6,000,000-6,999,999

Positive targeting

Yes

Inclusion lists, eligible for the campaign

In-app Required list

IAS_<Unique ID>_RL

A number between 7,000,000-7,999,999

Positive targeting

Yes

Required lists, eligible for the campaign

Pricing differs by segment type. You should be able to differentiate your custom segment integration to streamline integrations for current and future IAS segments. Contact your IAS representative for more details.

Brand Safety Protection

These profiles refer to contextual segments that can either target or exclude specific contextual based content depending on the segment type. Brand Safety Protection blocks or optimizes campaigns on web pages by scanning page contents against a set of custom criteria, to accord with a team's Context Control thresholds.

The API returns a custom object in the JSON response when the URL is in a segment in a profile. IAS returns segments in the same API call as requests for standard IAS viewability, brand safety, and invalid traffic.

Note: The presence of the segment ID or code in the response indicates a word in the profile is in the segment.

Context Control Avoidance lets you avoid pages which are not suitable for the brand's custom standards. When avoiding content and IAS isn't able to score the page, you should also avoid pages with the unscored segment which is only relevant for Context Control Avoidance.

Context Control Avoidance uses negative targeting - the presence of the response object identifies when the page is not suitable for the brand's custom standards. Conversely, the absence of any Context Control Avoidance information means the page is brand suitable. When applying multiple avoidance segments, IAS recommends using OR logic between segments. If any of the selected avoidance segments are returned from the IAS API endpoint for a URL/bundle ID, then do not bid.

DSPs activate the unscored page response by default when you use Brand Safety Protection. Therefore you can have the unscored segment active by default if a client uses Context Control Avoidance. Otherwise if the unscored response isn't activated by default, you need to add the unscored score or code as a custom targeting segment in the DSP.

Note: IAS recommends to always apply the unscored segment for Context Control Avoidance.

Endpoint

Naming Convention

Example

segt

Always returns 1,000,001 for an unscored page

1000001

seg

Always returns IAS_UNSCORED_PG for an unscored page

IAS_UNSCORED_PG

segt

A number between 1,000,002-1,999,999

1000075

seg

IAS_<unique ID>_PG

IAS_23_PG

For example, from the segt endpoint:

"segment_ids": [ "1000075" ]

An example from the seg endpoint:

"segment_codes": [ "IAS_23_PG"]

Made for Advertising

Within Context Control Avoidance are two segments to avoid Made for Advertising (MFA) sites.

Seg Code

Seg ID

Description

Format

Channel

IAS_1513948_PG

1513948

MFA sites and sites with ad clutter

Display

Desktop

IAS_1513949_PG

1513949

MFA sites

Display

Desktop

Context Control Targeting uses positive targeting when the presence of the response object identifies when the page is suitable for the brand's custom standards. IAS returns the seg code with the convention IAS_<unique ID>_PG and seg ID 3,000,000-3,999,999 to identify the positive targeting. When applying multiple targeting segments, IAS recommends using OR logic between segments. If any of the selected targeting segments are returned from the IAS API endpoint for a URL/bundle ID, then bid.

Context Control Targeting also supports a single segment containing other segments; these segment of segments are created in IAS Signal.

Endpoint

Naming Convention

Example

segt

A number between 3,00,000 and 3,999,999

3000002

seg

IAS_<Unique ID>_PG

IAS_1299_PG

For example, from the segt endpoint:

"segment_ids": [ "3000002" ]

An example from the seg endpoint:

"segment_codes": [ "IAS_1299_PG"]

Quality Sync Pre-bid Segments reflect the entirety of a user's content avoidance profile, encompassing the Brand Safety, Fraud, Custom List, and Custom blocking setting for their Open Web campaigns. The Quality Sync Pre-bid Segments can be used for Web and App inventory. The Pre-bid API outputs the same segment code from both the mobile and app API endpoints.

When applying multiple Quality Sync segments, IAS recommends using AND logic between segments. It is only safe to bid when all Quality Sync segments are returned from the IAS API endpoint for a URL/bundle ID.

Connected TV

Seg Code

Seg ID

Description

Format

Channel

CTV_FULLY_ONSCREEN

800000

Contains a list of all apps IAS verified for Fully On-Screen Measurement

VIDEO

CTV_APP

Authentication Sample

This Java code gets the token, then uses the token for a Pre-bid API request.

Step 1: Coordinate Client ID and Secret

Consult with your IAS Solution Engineer representative for a client ID and client secret.

Step 2: Get the Token

See a Java example to get the access token.

private static String getAccessToken(String url, String clientId, String clientSecret) throws IOException {
LOG.info("Getting access token");
ClientCredentialsTokenRequest request = new ClientCredentialsTokenRequest(new NetHttpTransport(), new JacksonFactory(), new GenericUrl(url));
TokenResponse response = request.setClientAuthentication(new BasicAuthentication(clientId, clientSecret)).execute();
return response.getAccessToken();
}

Step 3: Use the Token

Insert the token in the header for each report request.

See a Java example on how to make an API request.

private static String makeAPIRequest(String url, String token) throws IOException {
LOG.info("Using access token " + token.substring(token.length() - 15) + " for " + url);
// Pass the access token in the header 'Authorization:bearer'
Credential credential = new Credential(BearerToken.authorizationHeaderAccessMethod()).setAccessToken(token);
HttpRequestFactory requestFactory = new NetHttpTransport().createRequestFactory(credential);
HttpResponse httpResponse = requestFactory.buildGetRequest(new GenericUrl(url)).execute();
return httpResponse.parseAsString();
}

POM Dependencies

This code uses Google API and OAuth clients to make requests and parse the responses, as well as Apache logging.

See the dependencies as shown.

<dependencies>
<dependency>
<groupId>com.google.api-client</groupId>
<artifactId>google-api-client</artifactId>
<version>1.22.0</version>
</dependency>
<dependency>
<groupId>com.google.oauth-client</groupId>
<artifactId>google-oauth-client</artifactId>
<version>1.22.0</version>
</dependency>
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-api</artifactId>
<version>2.9.0</version>
</dependency>
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-core</artifactId>
<version>2.9.0</version>
</dependency>
</dependencies>

Examples

Sample Client

This sample passes in 3 parameters to get a token which it uses to make a request to the Pre-bid API.

Parameter

Variable

Description

args[0]

clientId

The ID your IAS Solution Engineer representative provides

args[1]

clientSecret

The secret for the ID your IAS representative provides

args[2]

url

The URL for making a Pre-bid API request

See the complete Java code example.

import java.io.IOException;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import com.google.api.client.auth.oauth2.BearerToken;
import com.google.api.client.auth.oauth2.ClientCredentialsTokenRequest;
import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.auth.oauth2.TokenResponse;
import com.google.api.client.http.BasicAuthentication;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpResponse;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
/**
* * Demonstrates how to request access tokens and how to use them in api calls.
* Uses Google api client library See <a href
* https://developers.google.com/api-client-library/java/google-oauth-java-
* client/oauth2></a>.
*/
public class SampleClientSimple {
private final static String TOKEN_SERVER_URL = "https://auth.adsafeprotected.com/uaa/oauth/token";
private static final Logger LOG = LogManager.getLogger(SampleClientSimple.class);
public static void main(String[] args) throws IOException {
if (args.length != 3) {
LOG.error("Arguments: <client-id> <client-secret> <url>");
System.exit(1);
}
String clientId = args[0];
String clientSecret = args[1];
String url = args[2];
String token = getAccessToken(TOKEN_SERVER_URL, clientId, clientSecret);
String result = makeAPIRequest(url, token);
LOG.info(result);
}
private static String getAccessToken(String url, String clientId, String clientSecret) throws IOException {
LOG.info("Getting access token");
ClientCredentialsTokenRequest request = new ClientCredentialsTokenRequest(new NetHttpTransport(), new JacksonFactory(), new GenericUrl(url));
TokenResponse response = request.setClientAuthentication(new BasicAuthentication(clientId, clientSecret)).execute();
return response.getAccessToken();
}
private static String makeAPIRequest(String url, String token) throws IOException {
LOG.info("Using access token " + token.substring(token.length() - 15) + " for " + url);
// Pass the access token in the header 'Authorization:bearer'
Credential credential = new Credential(BearerToken.authorizationHeaderAccessMethod()).setAccessToken(token);
HttpRequestFactory requestFactory = new NetHttpTransport().createRequestFactory(credential);
HttpResponse httpResponse = requestFactory.buildGetRequest(new GenericUrl(url)).execute();
return httpResponse.parseAsString();
}
}

Refreshing Token

The following example shows requesting a token every hour and then uses the token to get the segments on various URLs in a multi-threaded environment.

See the complete Java code example.

import static java.util.concurrent.TimeUnit.SECONDS;
import java.io.IOException;
import java.util.Arrays;
import java.util.Date;
import java.util.List;
import java.util.Random;
import java.util.concurrent.Executors;
import java.util.concurrent.ScheduledExecutorService;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import com.google.api.client.auth.oauth2.BearerToken;
import com.google.api.client.auth.oauth2.ClientCredentialsTokenRequest;
import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.auth.oauth2.TokenResponse;
import com.google.api.client.http.BasicAuthentication;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpResponse;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
/**
* Demonstrates how to request access tokens and how to use them in api calls.
* Uses Google api client library See <a href
* https://developers.google.com/api-client-library/java/google-oauth-java-client/oauth2></a>.
*
*/
public class SampleClient {
private final static String CLIENT_ID = "<<CLIENT_ID>>";
private final static String CLIENT_SECRET = "<<CLIENT_SECRET>>";
private final static String TOKEN_SERVER_URL = "https://<<TOKEN_SERVER_ADDRESS>>/uaa/oauth/token";
private final static String BASE_API_URL = "http://<<API_SERVER_ADDRESS>>/db2/client/<<CLIENT_ID>>/seg?adsafe_url=";
private static final long TOKEN_REFRESHER_RUNNER_INTERVAL = 10;
private static final long REQUEST_RUNNER_INTERVAL = 1;
// Refresh access token an hour before it expires
private static final long THRESHOLD = 60 * 60;
private Date nextTokenRefreshTime;
private volatile String accessToken;
private final ScheduledExecutorService actionTokenRefresherScheduler = Executors.newScheduledThreadPool(1);
private final ScheduledExecutorService processRunnerScheduler = Executors.newScheduledThreadPool(10);
// Some random URLs
private final static List<String> URLS = Arrays.asList("www.google.com", "www.cnn.com", "www.adidas.com", "msn.com", "apple.com");
private static final Logger LOG = LogManager.getLogger(SampleClient.class);
public static void main(String[] args) throws IOException {
SampleClient client = new SampleClient();
client.updateAccessToken();
// Simulate api call requests
client.launchRequestRunners();
client.launchAccessTokenRefresherRunner();
}
private void updateAccessToken() {
LOG.info("updating access token");
try {
// Use Basic Authentication against token server
final TokenResponse tokenResponse = new ClientCredentialsTokenRequest(new NetHttpTransport(), new JacksonFactory(), new GenericUrl(TOKEN_SERVER_URL)).setClientAuthentication(new BasicAuthentication(CLIENT_ID, CLIENT_SECRET)).execute();
LOG.info("Obtained " + tokenResponse.toPrettyString());
nextTokenRefreshTime = calculateNextTokenRefreshTime(tokenResponse);
accessToken = tokenResponse.getAccessToken();
} catch (IOException e) {
LOG.error(e);
}
}
private void callAPIService(final String url) {
LOG.info("Using access token " + accessToken.substring(accessToken.length() - 15) + " calling for " + url);
final String uRLToFire = BASE_API_URL + url;
// Pass the access token in the header 'Authorization:bearer'
final Credential credential = new Credential(BearerToken.authorizationHeaderAccessMethod()).setAccessToken(accessToken);
final HttpRequestFactory requestFactory
= new NetHttpTransport().createRequestFactory(credential);
try {
final HttpResponse httpResponse = requestFactory.buildGetRequest(new GenericUrl(uRLToFire)).execute();
LOG.info(httpResponse.parseAsString());
} catch (IOException e) {
LOG.error(e);
// Handle Error Scenario
}
}
private Date calculateNextTokenRefreshTime(final TokenResponse tokenResponse) {
return new Date(System.currentTimeMillis() + (tokenResponse.getExpiresInSeconds() * 1000) - THRESHOLD * 1000);
}
private void launchRequestRunners() {
processRunnerScheduler.scheduleAtFixedRate(new RequestRunner(), 5, REQUEST_RUNNER_INTERVAL, SECONDS);
}
private String getARandomURL() {
return URLS.get(new Random().nextInt(URLS.size()));
}
private void launchAccessTokenRefresherRunner() {
actionTokenRefresherScheduler.scheduleAtFixedRate(new TokenRefresherRunner(), 10, TOKEN_REFRESHER_RUNNER_INTERVAL, SECONDS);
}
private class TokenRefresherRunner implements Runnable {
public void run() {
handleAccessTokenRefresh();
}
private void handleAccessTokenRefresh() {
if (needTokenRefresh()) {
LOG.info("Access token refreshing threshold has reached.");
updateAccessToken();
} else {
LOG.info("Access token refreshing threshold has not reached yet. Doing nothing.");
}
}
private boolean needTokenRefresh() {
return new Date().after(nextTokenRefreshTime);
}
}
private class RequestRunner implements Runnable {
public void run() {
callAPIService(getARandomURL());
}
}
}

Response Outputs

Here are example response outputs with explanations for the responses for various environments.

Web Environment

Invalid Traffic

Response

Notable Missing Segments

Interpretation

Risk Level

{"segment_ids":["ESA","ESAHM","ESAV","ESAHMV","ESAUNR","ESAUNRV"]}

None

IAS rated this domain as a low risk for IVT for both web display and video

Low

{"segment_ids":["ESA","ESAV","ESAUNR","ESAUNRV"]}

ESAHM, ESAHMV

IAS rated this domain as a moderate risk for IVT for both web display and video

Moderate

{"segment_ids":["ESAUNR","ESAUNRV"]}

ESA, ESAV

IAS rated this domain as a high risk for IVT for both web display and video

High

{"segment_codes":[]}

ESAUNR, ESAUNRV

IAS did not rate this domain for IVT

Unrated

Brand Safety Violence

Response

Notable Missing Segments

Interpretation

Risk Level

{"segment_codes":["EHVIO","EHVIOV","EHMVIO","EHMVIOV","EUNR","EUNRV"]}

None

IAS rated this domain as a low risk for violence for web display and video

Low

{"segment_codes":["EHVIO","EHVIOV","EUNR","EUNRV"]}

EHMVIO, EHMVIOV

IAS rated this domain as a moderate risk for violence for web display and video

Moderate

{"segment_codes":["EUNR","EUNRV"]}

EHVIO, EHVIOV

IAS rated this domain as a high risk for violence for web display and video

High

{"segment_codes":[]}

EUNR, EUNRV

IAS can't rate this domain for brand safety for web display nor video

Unrated

Mobile App Environment

Invalid Traffic

Response

Notable Missing Segments

Interpretation

Risk Level

{"segment_ids":["ESAA","ESAAV","ESAHMA","ESAHMAV","ESAUNRA","ESAUNRAV"]}

None

IAS rated this app as a low risk for IVT for both mobile app display and video

Low

{"segment_ids":["ESAA","ESAAV","ESAUNRA","ESAUNRAV"]}

ESAHMA, ESAHMAV

IAS rated this app as a moderate risk for IVT for both mobile app display and video

Moderate

{"segment_ids":["ESAUNRA","ESAUNRAV"]}

ESAA, ESAAV

IAS rated this app as a high risk for IVT for both mobile app display and video

High

{"segment_codes":[]}

ESAUNRA, ESAUNRAV

IAS did not rate this app for IVT

Unrated

Brand Safety Violence

Response

Notable Missing Segments

Interpretation

Risk Level

{"segment_codes":["EHVIOA","EHVIOAV","EHMVIOA","EHMVIOAV","EUNRA","EUNRAV"]}

None

IAS rated this app as a low risk for violence for mobile app display and video

Low

{"segment_codes":["EHVIOA","EHVIOAV","EUNRA","EUNRAV"]}

EHMVIOA, EHMVIOAV

IAS rated this app as a moderate risk for violence for mobile app display and video

Moderate

{"segment_codes":["EUNRA","EUNRAV"]}

EHVIOA, EHVIOAV

IAS rated this app as a high risk for violence for mobile app display and video

High

{"segment_codes":[]}

EUNRA, EUNRAV

IAS can't rate this app for brand safety for desktop display nor video

Unrated

Context Control

Context Control Avoidance

Response

Notable Missing Segments

Interpretation

Risk Level

{"segment_codes":["IAS_UNSCORED_PG"]}

Not applicable

IAS has not or cannot score the page for Context Control

Avoid

{"segment_codes":["IAS_1500692_PG"]}

IAS_UNSCORED_PG

IAS has scored the page and it should be avoided for Sensitive Social Issues

Avoid

{"segment_codes":[]}

IAS_UNSCORED_PG

IAS has scored the page and it does not meet criteria for Sensitive Social Issues

Suitable

Context Control Targeting

Response

Notable Missing Segments

Interpretation

Suggestion

{"segment_codes":["IAS_UNSCORED_PG"]}

Not applicable

IAS has not or cannot score the page for Context Control

Not contextually relevant

{"segment_codes":["IAS_3008527_PG"]}

IAS_UNSCORED_PG

IAS has scored the page and it should be targeted for Automotive

Target

{"segment_codes":[]}

IAS_UNSCORED_PG

IAS has scored the page and it does not meet criteria for Automotive

Not contextually relevant


Was this article helpful?

Need further help?

Create an IAS case with details of your inquiry to receive help from our internal support team.