Versions Compared

Key

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

...

  1. banner - an API call that returns adcel proprietary XML, which provides information about an ad, including the banner image URL, image alt text, the click through URL, and possibly ad text. Also can return "raw response" from an ad network instead. Eg.

    Code Block
    languagehtml/xml
    http://adcel.vrvm.com/banner?p=ptnr&b=sampletag&c=999&ip=132.42.45.2&lat=40.753800&long=-73.983354
  2. adtag.js - returns javascript which is will be embedded into a page where the adTag was placed. It uses "document.write" to place the information into the HTML page. This is not meant to be called by a client directly, but rather by our own generated adTag code that the client has embedded into their page. The adTag code to be embedded by the client is generated in the dashboard. Eg.

    Code Block
    languagehtml/xml
    http://adcel.vrvm.com/adtag.js?p=ptnr&b=sampletag&c=999&lat=40.753800&long=-73.983354
  3. htmlad - an API call that is nearly identical to "banner". The difference being that instead of returning AdCel proprietary XML, the actual HTML that will display the ad is returned. This means that the client calling to the API can simply copy the results into their ad space as is, rather than having to parse our response, and build the ad themselves. Eg.

    Code Block
    languagehtml/xml
    http://adcel.vrvm.com/htmlad?p=ptnr&b=sampletag&c=999&lat=40.753800&long=-73.983354
  4. vast - an API call that returns a VAST xml document.  Unlike the other endpoints, this format is only intended to be used in VAST compliant video viewers.  AdCel places event tracking calls in the various video viewing lifecycle (see Appendix B)

    Code Block
    languagehtml/xml
    https://adcel.vrvm.com/vast?p=ptnr&b=vastvrvtest&c=999&adunit=vastlinear&lat=40.753800&long=-73.983354



...

Parameter

Name

Description

p

Portal keyword

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 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

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 identifier

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 source/type

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 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


  

...

Parameter

Name

Description

p

Portal keyword

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.

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.

 

Optional Parameters

If your application/platform captures accurate location or advertiser ids, passing this data on the request can greatly increase the monetization of your inventory. Simply insert the parameters you wish to pass in the request in your ad tag as show below. Your account manager will create a custom tag for your specific integration.

ParameterNameDescription
llLat/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.
latLatitudeLatitude 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.
longLongitude

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.

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.
hwmdlHardware Model Manufacturer'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.
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)
durationDurationSpecifies the duration in seconds of the ad you want returned. Valid values: 15 Second Video: "15” or  30 Second Video: “30”, etc.
appverApp VersionThis is the current version number of your app

...

ParameterNameTypeExamplesRequired?Default ValueDescription
minDurationMinimum Durationinteger (seconds)15noanyThe minimum length (in seconds) of the advertisement requested.
maxDurationMaximum Durationinteger (seconds)60noanyThe maximum length (in seconds) of the advertisement requested.
videoMimeVideo Mime Typestringvideo/mp4novideo/mp4The mime type allowed for video delivery (e.g.: video/mp4, video/x-flv)
deliveryTypeDelivery TypeStringprogressivenoprogressive

Supported delivery methods.

Allowed values: progressive, streaming, download

skipAllow Skipboolean (true|false)truenofalseIndicates if the player will allow the video to be skipped.
skipMinSkip Minimum Secondsinteger (seconds)10no0Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable
skipAfterSkip After Secondsinteger (seconds)10no0

Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable.

startDelayStart Delay Secondsinteger (seconds)10no0

Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements.

0 is pre-roll

>0 is Mid-Roll (value indicates start delay in second)

boxingAllowedLetterboxing Allowedboolean (true|false)falsenotrueIndicates if letter-boxing of 4:3 content into a 16:9 window is allowed
autoPlayAuto Playboolean (true|false)truenoanyIndicates if the video is allowed to auto play
audioOnStartAudio On Startboolean (true|false)truenoanyIndicates if the video's audio is allowed to be on when starting
vphVideo Player Heightinteger200nononeThe video player height
vpwVideo Player Widthinteger300nononeThe video player width

Creative Capability

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 paramter.  Multiple creative capability query parameters may be passed.

...