Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Parameter

Name

Description

p

Portal keywordKeyword

This is a Verve-assigned value identifying the distribution portal on which the advertisement is being displayed. In most cases, a mobile website accessed directly using the publisher's hostname is on the default portal (keyword: "def"). The portal will change if the site is accessed through a mobile carrier's "deck". Mobile client applications are typically segregated by platform (e.g., iPhone, BlackBerry, Windows Mobile, etc.) using portals.

b

Partner keywordKeyword

This is a Verve-assigned value identifying the publisher of the mobile content. Note that there's a one-to-one relationship between a mobile site and a publisher. For example, for the Daily Planet's mobile site, the partner keyword might be "dailyplanet".

c

Content Category

Content category ID. This is an integer which identifies the type of content available on the page for which an ad is requested. For example, a page of sports news will have one category ID, while a page of movie reviews will have another. See  Appendix A  for a complete list of categories and codes.

Multiple c values can be passed on the querystring as c=value1&c=value2&c=value3

ui

User identifierIdentifier

Unique identifier for a user, commonly from an HTTP cookie (mobile web) or some sort of device ID (apps). If a ui value is passed, the uis parameter should also be set. ui value is case sensitive. Unhashed IDFA (Apple ID) should be upper case. All other ui values, included hashed IDFA's, should be lower case.

uisUser identifier sourceIdentifier Source/typeType

Code indicating the source or type of ID passed in the "ui" parameter. (Ignored when the "ui" parameter is not present.) By default and in the absence of this parameter, the user identifier is assumed to be a randomly-generated ID. iOS id's must be passed as uppercase and Android id's in lower case.

See User Identifier Guidance for the values to code various identifiers.

appidApp Bundle IdIDUnique key that identifies the app (e.g. iOS Bundle ID or Android App ID or Package name). This is usually in the following format: com.example.myapp  

Optional parameters

Parameter

Name

Description

adunit

Ad Unit

Used to retrieve an ad specifically crafted for the target medium. Required for non-MMA banners. (see below). List of acceptable adunits ad units are mma (default), banner, inter, tinter, splash (sdk only), vastlinear (only supported on the /vast endpoint), vastnonlinear (only supported on the /vast endpoint).

sizeAd SizeSpecifies the size of the ad you want returned. Required for non-MMA banners or where an explicit mma size is required. See below for list of acceptable sizes and the adunitsad units.

lat

Latitude

Latitude location of the user making the ad request. Note the "ll" parameter is the preferred method in which to supply geolocation information. Please pass the most accurate location known, which is generally GPS data pulled from the device.

long

Longitude

Longitude location of the user making the ad request. Please pass the most accurate location known, which is generally GPS data pulled from the device.

ll

Lat/Long (Encoded)

Latitude and longitude of the user, encoded. The location of the user at the time of the advertising request. Availability of this parameter is, of course, platform- dependent and optional. It must be excluded if the user does not consent to provide location information in some manner. However, if location is available, it should be included. The parameter name is two lower-case Ls, and is encoded in a special format (described later in this document). The location's resolution does not have to be particularly precise, however a minimum target of 3km is recommended. Also, for a particular user session, it's sufficient to obtain the location only once. I.e., location does not need to be looked-up for every ad request during a session. Please pass the most accurate location known, which is generally GPS data pulled from the device.

latlongLat/Long (Plain-text)Latitude and longitude of the user, plain text. The value of this parameter should adhere to the format <latitude>,<longitude>. The data supplied here should adhere to the same rules as the above lat/long parameters, this is simply a convient method of providing location for those integrations where it is not possible to split the lat/long into separate parameters.
laLocation AgeAge of the supplied location (either lat/long or ll), in minutes. Please omit if the age is unknown.
laccLocation AccuracyAccuracy of the supplied location (either lat/long or ll), in meters. Please omit if the accuracy is unknown.

z

Postal Code

Zip or Zip+4 postal code describing the location of the content being viewed (not necessarily the postal code of the user's location). The value should be a zero leading 5 digit postal code. Examples: 07048, 21228, 90210-1234,

ipDevice's IP AddressIP address of the client/device on which the requested ad will be displayed. Mandatory for server-side requests; optional when requests come directly from a user's device.
ageAgeThe user's age used for demographic targeting.
zipZipThe user's zip code.
genderGenderThe user's gender used for demographic targeting. Acceptable values: "male", "female", "m", "f". If unknown, do not pass the key/value.
site 

Site/App Name

The site on which the ad is presented. On mobile web, this would be the hostname of the mobile site; in the app world, it's a unique key that identifies the app (e.g., the iOS bundle ID).

pos

position

position in which ad is to appear on page. Acceptable values are "top","inline", and "bottom"

ei

extra info

semi-colon separated list of arbitrary key-value pairs. Example: color=blue;shape=square; (note, the value should be url encoded, as it is a query parameter value)

ua

User Agent

User Agent should be passed in the header. If that is not possible, pass an encoded user agent string here.

modelDevice ModelModel information for the requesting device when otherwise unavailable from the user agent (i.e., iOS, primarily). An iPhone 6 is referenced as "iPhone7,2" and an iPhone 6 Plus is"iPhone7,1". Use the identifier as prescribed in the following list: https://theiphonewiki.com/wiki/Models
hwmdlHardware ModelManufacturer's designation for the device hardware model. At present, this should only be populated for iOS using the "hw.model" sysctl. For example, the GSM iPhone 4 would use the value "N90AP". Refer to the internal name designed in this list: https://theiphonewiki.com/wiki/Models On iOS, this parameter is preferred to the "model" parameter, but should be omitted if the information is unavailable.

dguid

device guid

A Verve-assigned identifier assigned to the device type making the request. It is used to override the "User-Agent" HTTP request header. Note that this parameter is typically only used in conjunction with the Verve Registration API for mobile client applications. If blank, omitted, or an unknown value, the "User-Agent" HTTP request header is used to identify the device type. Ignore unless directed otherwise.

db

display block id

Ignore unless directed otherwise.

pm

partner module id

Ignore unless directed otherwise.

iframe

disable iframe wrapping

If this parameter is set to false, responses from certain ad networks will not be wrapped within an iframe. This parameter should not be relied on to ensure that there is never or is always an iframe response. This is generally an internal Verve parameter for testing. Ignore unless directed otherwise.

cc

creative capability

Define the creative capability of your request.

"cc=1": for MRAID1 support

"cc=2": for MRAID2 support  (From the client Apps this value will be just integer 2)

nwkAd Networkchar[]: The production ID of the ad network (ex: dfp even in staging would be '41'). Skips the chain resolution and directly calls the network.
fltFlightchar[]: Unique flight identifier of some sort (passed through to ad network DSL) Requires nwk parameter is present. Identifies the flight id this call will use for creative tag retrieval.
ctgCreative Tagchar[]: Unique creative identifier of some sort (passed through to ad network DSL) Requires nwk and flt parameters. Identifies the creative id this call will use for creative tag retrieval.
scSecure Creative

s : requires secure creative

ns : requires insecure creative

x or n : secure creative agnostic (can handle both secure or unsecure)

 

ouReferer OverrideThe ou parameter should be used for mobile web requests, specifying the page url that the ad was requested on. Note: AdCel will use the referer header value for this, if this override is not specified.
appverApp VersionThis is the current version number of your app
usprivacyUS Privacy Regulatory Context(Used for CCPA) Regulatory context governing personal data contained within the bid request and any subsequent related transactions. Format defined by: https://iabtechlab.com/wp-content/uploads/2019/11/U.S.-Privacy-String-v1.0-IAB-Tech-Lab.pdf

...

Adunit ValueSize ValuesDescriptionExample
mma

Size optional. Largest size served based on device capability.

320x50, 300x50

Auto-sized MMA banner. Only set mma and the size if a specific mma size is required.
Auto sized mma banner. MMA adunit and size not required.

 

<script>


vrv

=

document.vrv

||

{};


vrv.b

=

'sampletag';


vrv.p

=

'ptnr';


vrv.c

=

'999';


</script>


<script

src="

http

https://

c

ad.vrvm.com/

pass

custom/

vrv

verve/

adtag

pixels/vervetag/vervetag.js"

></script>

>

 

For a specific mma size:

 

<script>
vrv

=

document.vrv

||

{};
vrv.b

=

'sampletag';
vrv.p

=

'ptnr';
vrv.c

=

'999';
vrv.adunit

=

'mma';
vrv.size

=

'300x50';
</script>
<script

src="

http

https://

c

ad.vrvm.com/

pass

custom/

vrv

verve/

adtag

pixels/vervetag/vervetag.js"

></script>

>

 

banner728x90, 300x250

Tablet ad. Requires

iPad l (p=ipad) or Android Tablet (p=apad) portals

tablet portal ('p') values:

  • iPad: 'ipad' (vrv.p = 'ipad')
  • Android Tablet: 'apad' (vrv.p = 'apad')

<script>
vrv

=

document.vrv

||

{};
vrv.b

=

'sampletag';
vrv.p

=

'ipad';
vrv.c

=

'999';
vrv.adunit

=

'banner';
vrv.size

=

'728x90';
</script>
<script

src="

http

https://

c

ad.vrvm.com/

pass

custom/

vrv

verve/

adtag

pixels/vervetag/vervetag.js"

></script>

>

banner300x250

Mobile phone banner. Requires mobile device portal ('p') values:

  • iPhone: 'iphn' (vrv.p = 'iphn')
or
  • Android: 'anap' (vrv.p = 'anap')
portals

<script>
vrv

=

document.vrv

||

{};
vrv.b

=

'sampletag';
vrv.p

=

'iphn';
vrv.c

=

'999';
vrv.adunit

=

'banner';
vrv.size

=

'300x250';
</script>
<script

src="

http

https://

c

ad.vrvm.com/

pass

custom/

vrv

verve/

adtag

pixels/vervetag/vervetag.js"

></script>

>

inter320x416, 300x250, 320x480Mobile interstitial. Full size (320x416) or small size (300x250)

<script>
vrv

=

document.vrv

||

{};
vrv.b

=

'sampletag';
vrv.p

=

'iphn';
vrv.c

=

'999';
vrv.adunit

=

'inter';
vrv.size

=

'320x416';
</script>
<script

src="

http

https://

c

ad.vrvm.com/

pass

custom/

vrv

verve/

adtag

pixels/vervetag/vervetag.js"></

script>

script>

Interstitials

To request an interstitial ad, the adunit needs be set to 'inter' for mobile phones or 'tinter' for tablets. Refer to the associated sizes in the adunit section above.

...

Parameter

Name

Description

p

Portal keywordKeyword

This is a Verve-assigned value identifying the distribution portal on which the advertisement is being displayed. In most cases, a mobile website accessed directly using the publisher's hostname is on the default portal (keyword: "def"). The portal will change if the site is accessed through a mobile carrier's "deck". Mobile client applications are typically segregated by platform (e.g., iPhone, BlackBerry, Windows Mobile, etc.) using portals.

b

Partner (publisher) keyword.Keyword

This is a Verve-assigned value identifying the publisher of the mobile content. Note that there's a one-to-one relationship between a mobile site and a publisher. For example, for the Daily Planet's mobile site, the partner keyword might be "dailyplanet".

c

Content Category

This is an integer which identifies the type of content available on the page for which an ad is requested. For example, a page of sports news will have one category ID, while a page of movie reviews will have another. See  Appendix A  for a complete list of categories and codes. 

Multiple c values can be passed on the querystring as c=value1&c=value2&c=value3

uiUser IdentifierDevice ID. If a ui value is passed, the uis parameter should also be set. ui value is case sensitive. Unhashed IDFA (Apple ID) should be upper case. All other ui values, including hashed IDFA's, should be lower case.
uisUser Identifier SourceCode indicating the source or type of ID passed in the "ui" parameter. (Ignored when the "ui" parameter is not present.) By default, and in the absence of this parameter, the user identifier is assumed to be a randomly-generated ID. iOS id's must be passed as uppercase and Android id's in lower case. Refer to this section to understand the uis mapping: User Identifier Guidance. If you cannot properly set a uis value, please talk with your account manager for alternate ways to pass this data.
appidApp Bundle IdUnique key that identifies the app (e.g. iOS Bundle ID or Android App ID or Package name). This is usually in the following format: com.example.myapp
adunitAd UnitValid values; vastlinear (only supported on the /vast endpoint), vastnonlinear (only supported on the /vast endpoint).
ccContainer Capability

Indicates the container capabilities for the vidoe ad request. VAST and/or VPAID support, including supported version, should be communicated: e.g. cc=vast2.0&cc=vpaid1.0

videoPlacementVideo Placement

Allowed values: stream, banner, article, feed, floating

  • stream: Played before, during or after the streaming video content that the consumer has requested (e.g., Pre-roll, Mid-roll, Post-roll)
  • banner: Exists within a web banner that leverages the banner space to deliver a video experience as opposed to another static or rich media format. The format relies on the existence of display ad inventory on the page for its delivery.
  • article: Loads and plays dynamically between paragraphs of editorial content; existing as a standalone branded message
  • feed: Found in content, social, or product feeds
  • floating: Covers the entire or a portion of screen area, but is always on screen while displayed (i.e. cannot be scrolled out of view)
vphVideo Player HeightThe video player height. Example value: 200.
vpwVideo Player WidthThe video player width. Example value: 300.

...

Additional Video Parameters

In addition to the relavant relevant parameters above (location/device/supply/etc), the following parameters may be used to further filter the potential demand to be requested.

Note:   previouslypreviously, the size parameter was used to define the duration.  It has now been separated into a new field, 'duration'.  Duration passed in the size parameter will still be honored, but this is less favorable than using the duration parameter.

...

Creative capability may now be used to define the version of vast/vpaid that the requester may need, and this can be passed via the creative capablity paramterparameter.  Multiple creative capability query parameters may be passed.

...