Unified Ad Server (UAS) Ad Tag User Guide

Document created by catherine.racette on Apr 28, 2017Last modified by catherine.racette on Sep 13, 2018
Version 17Show Document
  • View in full screen mode

Introduction

The Ad Unit script/Ad Tag is code that should be inserted in your web page source code. It represents the slot where an ad will be rendered.

Generate an Ad Tag

To generate an ad tag, follow the instructions in Generating Ad Tags in UAS.

Supported Tag Types

UAS supports three ad formats:

The ad tag/ad request can be generated for each using the guidelines below.

 

 

Banner/Rich Media Ad Tag

The Banner/Rich Media tag contains a header and a body section, both of which contain three different parts, explained below. The Banner/Rich Media tag can be used for Image, Text, Rich Media and HTML5 ad formats. 

Part One: Ad Unit One-Time Configuration

Irrespective of how many Ad Units and Ad Slots are configured in the source of the page, this code only needs to be included once in the header of the page.

 

Part One - Ad Unit One-Time Configuration:

<html>
<head>

<!-- Part 1 -->
<!-- Head section, should be included only once on a page -->
<script type='text/javascript'>
    var Phoenix = window.Phoenix || {};
    Phoenix.EQ = window.Phoenix.EQ || [];
    (function(){
        var scriptElement = document.createElement('script');
        scriptElement.async = true;
        scriptElement.type = 'text/javascript';   
        scriptElement.src = ('https:' == document.location.protocol ? 'https:' : 'http:') + '//ads.pubmatic.com/AdServer/js/phoenix.js';
        var node = document.getElementsByTagName('script')[0];
        node.parentNode.insertBefore(scriptElement, node);            
    })();
</script>
</head>

<body>
</body>
</html>

 

Part Two: Ad Slot Definition

This is the Ad Slot declaration section. After completing part one, include this section in the header of the page. In this section, define global, slot-specific targeting and extra parameters supported by UAS, which will pass to the UAS Ad Engine while making an ad request.

defineAdSlot

This method helps to define the Ad Slots on the page. The following are the parameters used to the define the Ad Slot.

  • Ad Unit ID: Ad Unit is a basic inventory entity that generates the Ad Tag.
  • Supported Ad Sizes: Contains the list of Ad Sizes configured at Ad Unit Level for Banner / Rich Media Ad format. If you are passing other ad sizes in the list not configured at Ad Unit, then UAS returns an error.
  • Div_ID_To_Render_This_Slot: DIV Identifier by which Ad Tag determines in which DIV creative/ad should get render on the page.

Important note for Div_ID_To_Render_This_Slot:

The string 'Div_ID_To_Render_This_Slot' must be replaced in JS tags using the following guidelines.

  • ID token must begin with a letter ([A-Z,a-z]) and may be followed by any number of letters, digits ([0-9]), hyphens ("-") and underscores ("_").
  • It is a case-sensitive string
  • ID must be unique on the page
  • Div_ID should match exactly with the DIV_ID of the render section of the Tag.
  •                          
                         

 

Part Two - Ad Slot Definition:

<html>
<head>
<!-- Part 1 should be place here as shown above  -->

 
<!-- Part 2 -->
<!-- AdSlot declaration section, will repeat for number of slots -->
<script type='text/javascript'>
    Phoenix.EQ.push(
        function(){
            <!-- enableSingleRequestCallMode enables to make single request -->
            Phoenix.enableSingleRequestCallMode();
            Phoenix.setInfo('ACCID', <Your Account ID>);
            var adSlot_1 = Phoenix.defineAdSlot('adUnit1',[[300, 250], [250, 250], [300, 300]],'DIV_01'); 
            var adSlot_2 = Phoenix.defineAdSlot('adUnit2',[[768, 90]],'DIV_02');  
        }
    );
</script>
</head>

<body>
</body>
</html>

 

Part Three: Ad Unit Creative Rendering

In this part, the ad unit gets rendered in the call to the display function.

 

display

The display method can be called to the setup area on the page where you expect to show an ad. The “DIV_ID” parameter to the display method defined at the slot level in Part Two of the tag should match with Part Three of the tag.

 

Part 3 - Creative Rendering:

<body>
<h1>position 1</h1>
<!-- Part 3 -->
<!-- Rendering AdUnit adUnit1 -->
<div id='DIV_01'>
    <script type='text/javascript'>
        Phoenix.EQ.push(
            function(){
                Phoenix.display('DIV_01');
            }
        );
    </script>
</div>


<!-- Part 3 -->
<!-- Rendering AdUnit adUnit2 -->
<div id='DIV_02'>
    <script type='text/javascript'>
        Phoenix.EQ.push(
            function(){
                Phoenix.display('DIV_02');
            }
        );
    </script>
</div>
</body>

Setting Global Parameters & Key-Value Pair Targeting in Banner/Rich Media Tag

The following methods can be used if you have configured multiple ad slots on the page and expect to have set common parameters and key-value pairs across all the ad slots on the page in single Ad Request mode.

 

In the Part Two section (above), use the following methods to set the global parameters and the key-value pairs.

 

setInfo

Using this method, you can pass the following information, globally applicable to all slots on the page. (Does not support slot-specific application.)

Sr. No.Parameter KeyDescription
1ACCID

Your account/publisher identifier. This is used for user sync up for your account

e.g. Phoenix.setInfo('ACCID', <YOUR_ACCOUNT_ID_AS_INTEGER>);

2GDPR

Use GDPR parameter to signal if the request coming from a user is subject to GDPR compliance or not.  If you have not integrated with any IAB compliant CMP vendor and not passed GDPR information, UAS considers default as 1. 

Possible values are:

ValueDescription
0

The ad request is not subject to GDPR compliance

1

The ad request is subject to GDPR compliance 

If your web property already integrated with IAB compliant CMP vendor, UAS Ad Client Script automatically reads the information for given domain and send it. It has higher preference if you also set it explicitly. e. g. Phoenix.setInfo('GDPR', 0 / 1)

               
3GDPR_CONSENT

Use GDPR_CONSENT key to pass the user-provided consent string on your domain / subdomain. The value should be URL-safe base64-encoded GDPR consent string. Please refer document for consent string, obtained from the CMP vendor. 

If your web property is already integrated with an IAB-compliant CMP vendor, the UAS Ad Client Script automatically reads the consent string for the domain and sends it. It has a higher preference if you also set it explicitly.

e. g. Phoenix.setInfo('GDPR_CONSENT', 'URL-safe base64-encoded GDPR consent string' )

               
4SEC

Use to inform UAS if SSL complaint creatives are expected or not.

e.g. Phoenix.setInfo('SEC', '1');

Value

NameDescription
1Non-securedIf you expect non-secured creatives on the page, this does not have to be set. When "1" is not passed, it considers that secured/non-secured creatives are OK on the page. 
2SecuredIf you have generated a secured version of an ad tag, the ad tag automatically sets this property. This signifies to UAS that it must deliver only secured creative.

 

Note: The UAS Ad Client does an auto-detection of the protocol and sets SEC=1 if the publisher page is running on HTTPS. No need to explicitly call this function.             

                         
5PAGEURL

UAS Ad Tag automatically retrieves the Page URL and passes the same information in the ad request. You can override the auto-retrieved URL by explicitly calling this function/method. 

 

This is applicable for inventory coming from Web / Mobile Web ( Browsers ). We expect application specific parameter if the inventory is coming from Mobile applications. Please refer following parameters for more details. 

If your account has been configured as a channel partner and you've enabled "WhiteList Domain" at a site level, make sure the domain is registered against the site correctly and passing the same while making the ad request. 

 

A request coming through the wrong domain if passed explicitly using this or if a domain is not registered, then UAS will not monetize the ad request. 

                     

e.g. Phoenix.setInfo('PAGEURL', 'http://publisher-site.com');

6LAT

Location Information: Latitude of the user/device. The valid range is from -90.000000 to 90.000000
e.g. Phoenix.setInfo('LAT', '40.785091');

7LON

Information: Longitude of the user/ device. Valid range of longitude is -180.000000 to 180.000000
e.g. Phoenix.setInfo('LON', '-73.968285');

8LOC_SRC

Location Source - Value to inform what is the source of determining Geo Location ( Latitude / Longitude ). It could be

Phoenix.setInfo('LOC_SRC', '1');

ValueNameDescription
1GPSIf determined, the location information from using actual GPS device.
2IP DerivedIf the location information is inferred using user IP address either by a third-party applicatino like Digital Element, MAxMind or your own proprietary solution.
3User Registration DataLocation information using user registration data.
9UDID

Unique Device Identifier retrieved from the device. We highly recommend passing the following identifiers with respect to the operating system.

This parameter can only be passed from the application.

Mobile Operating SystemUDID Description
Android

Android Advertising Identifier 

Android Advertising identifier is the resettable unique user identifier. This ID is a (32-character) string format. Example ID:  “38400000-8df0-11bd-b11c-10b96e40000d”.

 

We highly recommend passing Android Advertising ID in raw format along with other parameters as mentioned below.  

 

e.g.

Phoenix.setInfo('UDID', '38400000-8df0-11bd-b11c-10b96e40000d');

Phoenix.setInfo('UDID_TYPE', '9'); 

Phoenix.setInfo('UDID_HASH', '1' );

iOSIDFA or IDFV 

Identifier for advertisers ( IDFA ), Identifiers for Vendor ( IDFV ). This ID is a (32-character) string format. An example ID is 6a92078b-8246-4ab4-Ae5c-76104861e7fd.

 

We highly recommend passing IDFA in raw format along with other parameters as mentioned below.  

e.g.

Phoenix.setInfo('UDID', '6a92078b-8246-4ab4-Ae5c-76104861e7fd');

Phoenix.setInfo('UDID_TYPE', '1'); 

Phoenix.setInfo('UDID_HASH', '1' );

 

Note: Please refer following UDID_TYPE and UDID_HASH possible value if you would like to pass IDFV or Android ID.   

10UDID_TYPE

Type of value provided in the UDID parameter mentioned above.

Phoenix.setInfo('UDID_TYPE', '1'); // Expect For iOS Application.

Phoenix.setInfo('UDID_TYPE', '9'); // Expect For Android Application. 

This parameter can only be passed from the application.

Possible values are:

ValueMobile Application PlatformDescription
0iOS/AndroidOther/Unknown
1iOS

IDFA (Identifier for Advertiser) - Highly Recommended

2iOS

IDFV (Identifier for Vendor)

3Android

Android identifier

9Android

Android Advertising Identifier - Highly Recommended

11UDID_HASH

We highly recommend to pass the Raw unhashed device identifier. However if you are hashing device identifier before passing, we expect to pass us type of Hashing. 

This parameter can only be passed from the application.

Phoenix.setInfo('UDID_HASH', '1'); // If no hashing techniques applied on UDID while passing.


ValueDescription
0Unknown - not aware if performed any hashing on UDID
1Raw - Highly Recommended
2SHA1
3MD5

Possible values are:

Note: You must have to pass if you are passing UDID and UDID_TYPE as per recommendation. 

12APP_NAME

Name of the mobile application. This value should be the same as that mentioned on the application (app) store.

Phoenix.setInfo('APP_NAME', 'Your application name');

This parameter can only be passed from the application.

13APP_STORE_URL

URL of the app store from where a user can download this application.

Phoenix.setInfo('APP_STORE_URL', 'Application Store URL');

This parameter can only be passed from the application.

14APP_BUNDLE_ID

Application bundle or package name

Phoenix.setInfo('APP_BUNDLE_ID', 'your application bundle identifier');

This parameter can only be passed from the application.

15APP_ID

Application Identifier
Mobile application's ID on the exchange. In case of iOS App, this is recommended to be correctly passed by the caller. This is not expected to pass for Android application. 

Phoenix.setInfo('APP_ID', 'your application identifier');

This parameter can only be passed from the application.

 

setCommonTargeting

Common key-value pairs can be set across all ad slots for the same or different ad unit. Ensure you are using Phoenix.setCommonTargeting to set it common. The first parameter is the Key Name and the second parameter is the list of expected values on which you have targeted the Line Item.

GDPR: The custom key and its values must not be used to pass data that PubMatic or others could use or recognise as personally-identifiable information or personal data.

               

In the following example, all the targeting and other information explicitly set is applicable to adSlot_1 and adSlot_2 available on the page.

 

Example: Set Global Parameters and Key-Value Pair Targeting

<html>
<head>
 
<!-- Part 2 -->
<!-- AdSlot declaration section, will repeat for number of slots -->
<script type='text/javascript'>
    Phoenix.EQ.push(
        function(){
            <!-- enableSingleRequestCallMode enables to make single request -->
            Phoenix.enableSingleRequestCallMode();
            Phoenix.setInfo('ACCID', <Your Account ID>);
            // Must if you are channel partner and white list enabled at Site Level.
            Phoenix.setInfo('PAGEURL', 'http://publisher-site.com');              

            // Passing User Location Information
            Phoenix.setInfo('LAT', '40.785091');
            Phoenix.setInfo('LON', '-73.968285');
            Phoenix.setInfo('LOC_SRC', '1');
            // expect only SSL Compliant (Secured) Creatives
            Phoenix.setInfo('SEC', '1');

            // Set the Key and Value across all follwoing slots
            Phoenix.setCommonTargeting('PageContext', ['Sports','Politics']);
            Phoenix.setCommonTargeting('pageSubject', ['Football']);

            var adSlot_1 = Phoenix.defineAdSlot('adUnit1',[[300, 250], [250, 250], [300, 300]],'DIV_01'); 
            var adSlot_2 = Phoenix.defineAdSlot('adUnit2',[[768, 90]],'DIV_02');  
        }
    );
</script>
</head>
</html>

 

Setting Ad-Slot-Specific Parameters and Key-Value Pairs Targeting in the Banner/Rich Media Tag

In Part Two of the tag, various methods can be used to set the ad-slot-specific parameters and key-value pair targeting. You can set slot-specific attributes that will send to UAS ad request per slot in Single Ad Request mode.

 

The defineAdSlot method returns the slot object on which the following methods can be called to set the slot-specific information mentioned below.

setExtraParameters
This method sets the extra parameters such as pmZoneId. You can send any parameter for any standard method that is not available such as setVisibility.

 

setTargeting
This method sets the key-value-specific targeting at the slot level where you expect to deliver a specific line item based on key-value targeting.

GDPR: The custom key and its values must not be used to pass data that PubMatic or others could use or recognise as personally-identifiable information or personal data.

               

   

setVisibility
This method conveys where your ad slot is located on the page. Possible values for set visibility are:

 

ValueDescriptionComments
0UnknownIf no value is provided, this will be considered the default.
1Above the Fold
2Below the Fold
3Partially Above the Fold

 

Example: Set Ad-Slot-Level Parameters

<html>
<head>
 
<!-- Part 2 -->
<!-- AdSlot declaration section, will repeat for number of slots -->
<script type='text/javascript'>
    Phoenix.EQ.push(
        function(){
            <!-- enableSingleRequestCallMode enables to make single request -->
            Phoenix.enableSingleRequestCallMode();
            var adSlot_1 = Phoenix.defineAdSlot('adUnit1',[[300, 250], [250, 250], [300, 300]],'DIV_01'); 
            // adSlot_1 specific targeting and extra parameters
            adSlot_1.setTargeting('pageSlot', ['Baseball']);
            adSlot_1.setExtraParameters('pmZoneId', ['123']);
            adSlot_1.setVisibility('1');

            // adSlot_2 specific targeting and extra parameters
            var adSlot_2 = Phoenix.defineAdSlot('adUnit2',[[768, 90]],'DIV_02');
            adSlot_2.setTargeting('pageSlot', ['Cricket']);
            adSlot_1.setExtraParameters('pmZoneId', ['456']);
            adSlot_2.setVisibility('2');
        }
    );
</script>
</head>
</html>

 

Native Ad Tag/Request

Currently, UAS does not provide an auto-render solution for Native Ad format. However, you can generate a Native Ad Request for the selected Ad Unit. For secured creative, it appends sec=1 parameter informing UAS to deliver only secured-compliant creatives.

 

UAS provides different options to request the Native Creative Assets based on the Native Template identifier in the request or based on Native JSON.

 

If your Native Ad Slot is fixed and not expected to change the template very frequently, send ntid=<NATIVE_TEMPLATE_ID> associated with Ad Unit while requesting. This removes all the Native JSON complexity for you.

 

If the Ad Unit is getting used across various screen sizes and different platforms such as Web, Mobile Web or Mobile App, you can directly send Native JSON in ntl. Refer to UAS Ad Request API User Guide for more details about Native Template ID (ntid) or Native JSON (ntl ) on Unified Ad Server API.

 

Example: Native Ad Tag

Sample Native Request
----------------------
https://ae.pubmatic.com/ad?&req_type=4&res_format=2&au=adUnit1&sec=1&ntid=<NATIVE_TEMPLATE_ID>&iid=<IMPRESSION_ID>&rndn=<RANDOM_NUMBER_CACHE_BURSTING>


Template ID: 204, Template Name: Mobil News Feed
------------------------------------------------
Template RTB JSON:
{"layout":3,"assets":[{"id":1,"required":1,"title":{"len":80}},{"id":2,"required":1,"img":{"type":1,"w":150,"h":150}},{"id":7,"required":1,"data":{"type":3,"len":3}},{"id":16,"required":1,"data":{"type":12,"len":50}}]}

 

Video Ad Request

The Generate Ad Tag option can be used to generate the video ad request and configure the same in the video player.

 

UAS consumes all other video parameters configured at the Ad Unit Level and uses the same for the creative selection whenever a request comes to UAS.

 

If your player dynamics change based on the source of inventory (e.g., Web, Mobile Web etc ) or screen size, all these parameters can be passed in the ad request dynamically and UAS will give a higher preference to the provided parameter if it's available as configured at the Ad Unit Level. Refer to UAS Ad Request API User Guide  for more details about Video Parameters.

 

Enabled Single Request Mode for Banner/Rich Media Tag

  • If you have a web page configured with multiple ad slots associated with the same page, the ad tag makes a separate ad request calls for each ad slot to show the ad provided that Part One, Part Two and Part Three are mentioned separately for each ad slot.
  • If the possibility of too many calls initiated from the web page is a concern, you can optimize the number of requests called by enabling single request mode for all slots configured on the same web page. This will result in making single ad requests for all ad slots.
  • By default, UAS ad tag is enabled for Single Request Mode when you will generate an Ad Tag, irrespective of how many slots are defined. You can check in Part Two of the header section in the ad tag.
  • Single Ad Request Mode can be disabled by removing a call to Phoenix.enableSingleRequestCallMode(); method from Part Two of the Ad Tag.
  • You need to invoke display() method separately for each ad slot where you want it to get rendered as mentioned on Part Three. Ad Client will only make single call to the UAS Ad Engine combining all the ad slots for first display() call only.

Example: Single Ad Request Mode for Multiple Ad Slots on the same page

<html>
<head>
 
<!-- Part 2 -->
<!-- AdSlot declaration section, will repeat for number of slots -->
<script type='text/javascript'>
    Phoenix.EQ.push(
        function(){
            <!-- enableSingleRequestCallMode enables to make single request -->
            Phoenix.enableSingleRequestCallMode();
            // Slot Declarations
            var adSlot_1 = Phoenix.defineAdSlot('adUnit1',[[300, 250], [250, 250], [300, 300]],'DIV_01'); 
            var adSlot_2 = Phoenix.defineAdSlot('adUnit2',[[768, 90]],'DIV_02');  
        }
    );
</script>
</head>

<body>
</body>
</html>

 

Advantages of Single Ad Request Mode

 

A single request for all ad slots on the same page saves the network latency on individual calls.

 

Competitive Exclusion can be supported if you would expect not to deliver a competitor ad on the same page at the same time in different slots.

                                   

Limitations

1. UAS Ad Unit script does not have support for Safe-Frame. 

Attachments

    Outcomes