Skip to end of metadata
Go to start of metadata

DefineTag

defineTag({params})

Defines parameters for an ad placement. Note that no more than 12 placements should be specified per page. Returns a Tag object that can be used later after defining. 

Parameters

ParameterTypeDescription
membernumberThe member ID for the placement (overrides global setting from setPageOpts())

invCode

string

The placement code for this placement.

tagIdnumberThe placement ID for the placement

sizes

array of numbers

One or more placement sizes in the format [300,250] ({{height, width}}) for a single size and [[300,250],[728,90]] for multiple sizes.

If more than one size is specified, the first is the placement size and the rest are promo sizes.

Only 1 of sizes or sizeMapping is allowed per ad slot.

sizeMapping array of objects

Specifies a set of sizes based on a minimum viewport size. This allows a seller to set which sizes should be used based on the size of the viewport. If the viewport size is smaller than the smallest minWidth provided, no ad will be requested for the ad slot. Sizes are passed in the format [300,250] for a single size and [[300,250],[728,90]] for multiple sizes.

Each object in the array contains two parameters :

  • minWidth: Specifies the minimum width of the viewport. Example: minWidth: 1024
  • sizes: Specifies the size(s) of the ad. Example: sizes: [[300,250],[300,600]]

Only 1 of sizes or sizeMapping is allowed per ad slot.

targetId

string

The unique identifier of a specific ad slot, created by the publisher/seller. Corresponds to a div tag in the body of the page where the ad should appear. The div tag's id should be set to the same value as the targetId.

forceCreativeIdnumber

Specifies the ID of a creative that should be forced to appear in this placement. Forcing a creative allows you to preview an ad on a site, perform testing or certification, and create tear sheets.

Creatives can also be forced in the query string of the website URL in the format ast_override_[parameter]=[value]:[creative_id] , where you will replace parameter, value, and creative_id as needed. You may pass in multiple [value]:[creative_id] combinations separated by a comma (e.g. http://test.example.com/demo.html?ast_override_ index = 2 : 40611315 , 3 : 40611316 )

You may choose one of the following options for the parameter.

ParameterDescriptionExample
divSpecifies a target div ID of the ad slot to override. In value, enter the div ID you would like to force creative_id into

To override the div with ID "apn_ad_slot_1" with creative 40611315:

http://test.example.com/demo.html?ast_override_div=apn_ad_slot_1:40611315

indexSpecifies the index number of the ad slot to override, starting from 0. In value enter the index number you would like to force creative_id into

To override the 3rd defined placement with creative 40611315:

http://test.example.com/demo.html?ast_override_index=2:40611315

tag_idSpecifies the tag ID that of the ad slot to override. In value enter the tag_id you would like to force creative_id into. If the size of the ad slot and creative do not match, the creative will still be rendered but a warning message will be displayed. The creative would not serve in this ad slot in a live auction.

To override tag_id 8011968 with creative 40611315:

http://test.example.com/demo.html?ast_override_tag_id=8011968:40611315

inv_codeSpecifies the inventory code that of the ad slot to override. In value enter the inventory code you would like to force creative_id into. If the size of the ad slot and creative do not match, the creative will still be rendered but a warning message will be displayed. The creative would not serve in this ad slot in a live auction.

To override inv_code 9123450 with creative 40611315:

http://test.example.com/demo.html?ast_override_inv_code=9123450:40611315

The querystring parameters listed above will override any value specified in the forceCreativeId parameter of the ad tag.

allowSmallerSizes

Boolean

Indicates whether smaller ad sizes than defined on sizes are allowed.

allowedFormatsarray of stringsIndicates the desired formats. Options include [ 'video' 'banner' 'native, ' audio'].
rendererOptions objectSpecifies one or more options that can be passed into the renderer for custom rendering.
position
stringIdentify the placement as above or below the fold. Possible values: above or below.
disablePsa BooleanIndicates whether this placement should disable PSAs from being shown.
nobidIfUnsoldBoolean

Indicates that a blank ad should be returned if the placement is not sold rather than a default ad or PSA.

keywords

object

A set of key/value pairs applicable to this placement. Querystring segments are defined by key/value pairs in this object. Keywords that contain hyphens must be surrounded by single quote marks. Best practice is to always enclose keywords in single quotes. A maximum of 100 key/value pairs can be defined per tag.

trafficSourceCodestringSpecifies the third-party source of this impression.

alwaysUseXDomainIframe

This is deprecated in favor of enableSafeFrame
Boolean

Indicates whether the ad creative should be loaded into a cross-domain iframe. This will prevent data leakage and does not allow the creative to access the parent page directly.

privateSizes
array of numbers

COMING SOON! The additional sizes that allowed to serve only for custom deals or packages (when private sizes are allowed by the deal or package). In the format [300,250] for a single size and [[300,250],[728,90]] for multiple sizes

supplyType
stringIndicate the type of supply for this placement. Possible values are mobile_webmobile_app , or  web.
pubClick
string

Specifies a publisher-supplied URL for third-party click tracking. This is just a placeholder into which the publisher can insert their own click tracker. This parameter should be used for an unencoded tracker. This parameter is expected to be the last parameter in the URL. Please note that the click tracker placed in this parameter will only fire if the creative winning the auction is using AppNexus click tracking properly.

Example: pubClick=http://click.adserver.com/

reserve
number

Specifies the reserve price for this inventory. This parameter will override a preset price and will set both the hard floor AND soft floor if Yield Management is not being used. Note: This option is not available from the UI and must be appended to the placement tag manually.

Example: reserve=5.00

extInvCode
 string

Specifies predefined value passed on the query string that can be used in reporting. The value must be entered into the system before it is logged. For more information, see External Inventory Code Service.

Example: extInvCode='10039'

native
object

This is optional. You do not need to specify this in defineTag.

A native ad is a collection of individual assets. These could be a title, a description, or an image, for example.

Any field in the native object configured as {required: true} will be required on the bid response object. If not present, the bid is not added to the auction.

Possible Native Assets:
NamePossible Optional ValuesNotes/Description
title

required: <true | false>

max_length: <number>

Where field marked required: true will be required on the bid response object.

If max_length is specified, responses for this fields must not exceed the max_length number.

body

required: <true | false>

max_length: <number>

Where field marked required: true will be required on the bid response object.

If max_length is specified, responses for this field must not exceed the max_length number.

image

required: <true | false>

sizes: [{ width: <number>, height: <number> }]

Where field marked required: true will be required on the bid response object.

If sizes is specified, the image response must exactly match the given width and height dimensions.

icon

required: <true | false>

sizes: [{ width: <number>, height: <number> }]

Where field marked required: true will be required on the bid response object.

If sizes is specified, the image response must exactly match the given width and height dimensions.

sponsoredBy

required: <true | false>

max_length: <number>

Where field marked required: true will be required on the bid response object.

If max_length is specified, responses for this fields must not exceed the max_length number.

cta

required: <true | false>

Where field marked required: true will be required on the bid response object.

clickUrl

required: <true | false>

Where field marked required: true will be required on the bid response object.
privacySupported
<true | false>
If true, the publisher supports a privacy link. The privacy link will be sent to the publisher in the bid response.
video
required: <true | false>
min_duration: <number>
max_duration: <number>

Where field marked required: true will be required on the bid response object.

min_duration and max_duration values are specified in milliseconds.

min_duration default = 0

desc2
required: <true | false>
 
rating
required: <true | false>
 
displayUrl
required: <true | false>
 
likes
required: <true | false>
 
downloads
required: <true | false>
 
price
required: <true | false>
 
salePrice
required: <true | false>
 
rating
required: <true | false>
 
phone
required: <true | false>
 
address
required: <true | false>
 

The format for this is:

externalImpIdstring

Specifies the unique identifier of an externally generated auction.

Example: externalImpId: 'bacbab02626452b097f6030b3c89ac05'

enableSafeFrameBoolean

Specifies whether this placement will be served in a SafeFrame container. Here is more information on the SafeFrame API Reference .

setSafeFrameConfig
        
Boolean

Allows configuration of SafeFrame, a managed iframe that provides additional consumer protection and publisher control beyond that provided by a standard iframe. Here is more information on the SafeFrame API Reference .

initCollapsed
object

This initializes the ad iframe at zero size. The only option for the expandBy field is creative, this gives the creative the responsibility of expanding the ad slot by calling resizeAd function.

prebid
BooleanFlag that indicates the tag being requested is for a headerbidding or prebid auction. This will return the cpm on the adObj `adObj.cpm`, however, the ad will not be renderered. It is assumed that another ad server will render the ad if this bid wins.
usePmtRule
Boolean

Flag that indicates whether payment rules should be applied to a bid before sending the bid to the ad server.

Default is false.

Example