Skip to end of metadata
Go to start of metadata

 

Introduction

We support three kinds of integration:

  • We offer an SDK for integration into your mobile apps
  • We offer server-side integration via an API
  • We offer javascript ad tags for integrating into mobile sites and apps

SDK Integration

For more information on the Verve Ad SDK, contact your publisher services representative.

Server-Side Integration

Our AdCel API provides a server-side method of integrating with publishers.

Talk to your publisher services representative for provisioning of your production service on our API.

Javascript Integration

The javascript Integration is the simplest form of integration that Verve supports.

The Verve ad tag is a simple call to a hosted javascript file.  Please see below for an example.

<script>
vrv = document.vrv || {};
vrv.b = 'sampletag';
vrv.p = 'iphn';
vrv.c = '999';
vrv.lat = '<INSERT_LATITUDE_HERE>';
vrv.long = '<INSERT_LONGITUDE_HERE>';
vrv.ui = '<INSERT_ADVERTISER_IDENTIFIER>';
vrv.uis = '<INSERT_ADVERTISER_IDENTIFIER_SOURCE>';
vrv.appid = '<INSERT_APP_BUNDLE_ID>';
</script>
<script src="https://c.vrvm.com/pass/vrv/adtag/vervetag.js"></script>

In the example above, the placeholders (text between the angle brackets, and the brackets themselves) should be replaced with actual values. If the tag includes these placeholders, the request may pass inaccurate/insufficient data

For normal client-side integration, simply insert your Verve ad tag where you want your ad to appear.

Required parameters

These are the required parameters to be included in the Verve ad tag request.

Parameter

Name

Description

p

Portal keyword

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

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

uiUser IdentifierUnique identifier for a user or advertiser ID, includes IDFA or Google 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 IDs must be passed as uppercase and Android IDs in lower case. Refer to this section to understand the uis mapping: User Identifier Guidance.
appidApp Bundle Id

Unique 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


In addition to the above, latitude and longitude location parameters are also required.  They can be passed in the ''ll" parameter or "lat" and "long" parameters.  

Parameter

Name

Description

llLat/LongLatitude 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.

Optional Parameters

For a list of additional available parameters, read more here: AdCel API.

Testing and Certification

Testing and certification involves a combination of validating on mobile web and app as well as various flavors of interstitials and video formats.

MMA

To create a tag that returns a banner every time, the following values should be used:

  • b=sampletag
  • p=iphn
  • c=999

By changing the category ("c") to "888", you will get a Celtra rich media banner rather than a static image. Using this, you can test a wide range of possible Verve responses.

Expandable

Please validate that your supports our expandable format for both mobile web and app below:

Mobile Web

<script>
vrv = document.vrv || {};
vrv.b = 'sampletag';
vrv.p = 'ptnr';
vrv.c = '97';
</script> 
<script src="https://c.vrvm.com/pass/vrv/adtag/vervetag.js"></script>

APP-for both iPhone and Android apps

<script>
vrv = document.vrv || {};
vrv.b = 'sampletag';
vrv.p = 'iphn';
vrv.c = '97';
</script>
<script src="https://c.vrvm.com/pass/vrv/adtag/vervetag.js"></script>


In banner/line video for iOS apps

iOS supports playing inline video via the "allowsInlineMediaPlayback" to be set in app. Please certify if your iOS (iPhone and iPad) apps can run this creative type.

  1. Requires allowsInlineMediaPlayback to be set in app
  2. Use this test tag to be loaded in app:

<script>
vrv = document.vrv || {};
vrv.b = 'sampletag';
vrv.p = 'iphn';
vrv.c = '22';
</script>
<script src="https://c.vrvm.com/pass/vrv/adtag/vervetag.js"></script> 


Specifications:

  1. In line banner/interstitial
    1. Auto play: Yes
    2. Duration: 5-10 seconds
    3. Audio: No
  2. Expanded panel (requires user to tap on initial banner to open)
    1. Auto play: Yes
    2. Duration: 15 to 30 recommended. 
    3. Audio: Yes
  3. Example preview without using an app: http://www.vervemobile.com/test/inbannervideo/
    1. If your browser doesn't support the mime type try another browser or install the appropriate plugin for your browser.
    2. If viewing on a mobile device, this will not auto play.

Interstitial

Full Screen Interstitial

This is a test full screen static interstitial tag for mobile web. The black border will soak up all remaining space on the page. If you don't want a full screen interstitial, please take a look at the dedicated 300x250 interstitial. As a publisher, you will need to control how many interstitials you will request.

<script>
vrv = document.vrv || {};
vrv.b = 'sampletag';
vrv.p = 'ptnr';
vrv.c = '999';
vrv.adunit = 'inter';
vrv.size = '320x416';
</script>
<script src="https://c.vrvm.com/pass/vrv/adtag/vervetag.js"></script>

 

The interstitial will look like this:The tag returns a javascript response similar to this: JS_Response.txt

 

300x250 Interstitial

Use this test tag when your inventory is running a specific 300x250 ad size.

<script>
vrv = document.vrv || {};
vrv.b = 'sampletag';
vrv.p = 'iphn';
vrv.c = '999';
vrv.adunit = 'inter';
vrv.size = '300x250';
</script>
<script src="https://c.vrvm.com/pass/vrv/adtag/vervetag.js"></script>

 

This will request will return a js response as well: JS_Response_300x250.txt

 

Tablet banners require an adunit of banner and a size of either 728x90 or 300x250.

<script>
vrv = document.vrv || {};
vrv.b = 'sampletag';
vrv.p = 'ipad';
vrv.c = '999';
vrv.adunit = 'banner';
vrv.size = '728x90';
</script>
<script src="https://c.vrvm.com/pass/vrv/adtag/vervetag.js"></script>

 

Ad Formats and Size

MMA

The Verve Ad Tag will automatically sense the device requesting a page and serve an appropriately sized advertisement. Generally, Verve Ad Tags comply closely with MMA specifications and come in the following sizes:

  • 320x50
  • 300x50
  • 216x36

The supported formats are .jpg, .gif, and .png.

Caching

No caching of ads is allowed under any circumstances.

Interstitial Inventory

If you wish to display interstitial ads or have interstitial units today and would like Verve to show interstitial ads into it, please speak with your publisher services representative.

Video Tag Integration

The video tag Integration is the simplest form of integration that Verve supports for video. The Verve video tag is a simple call to a Verve VAST endpoint, which will return a VAST-compliant video ad response.  Please see below for an example.

 

https://adcel.vrvm.com/vast?p=[INSERT “anap” OR “iphn”]&b=vastvrvtest&adunit=vastlinear&skip=["true" or "false"]&videoPlacement=["stream" "banner" "article" "feed" "floating"]&c=999&lat=[INSERT LATITUDE]&long=[INSERT LONGITUDE]&ui=[INSERT USER IDENTIFIER]&uis=[INSERT USER IDENTIFIER SOURCE/TYPE]&appid=[INSERT BUNDLE ID OR PACKAGE NAME]&sc=x

 

Required Video Parameters

These are the required parameters to be included in the ad tag request.

Parameter

Name

Description

b

Partner Keyword

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

 p

Portal Keyword

Verve-assigned value identifying the distribution portal on which the advertisement is being displayed.

Allowed values: "iphn" for iOS Devices; "anap" for Android Devices

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 query string 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 Unit

Allowed values: "vastlinear" (only supported on the /vast endpoint), "vastnonlinear" (only supported on the /vast endpoint).

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.

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)
skipAllow SkipIndicates if the player will allow the video to be skipped. Boolean (true|false)
ccContainer Capability

Indicates the container capabilities for the video ad request - VAST and/or VPAID support, including supported version should be communicated.

Example values: "cc=vast2.0&cc=vpaid1.0"

 

Optional Video 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 can assist with creating a custom tag for your specific integration.

Parameter
Name
Description
llLat/LongLatitude 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.
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.
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

Additional Video Parameters

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

Note: Previously, 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.

Many of the parameters defined here have been derived from the OpenRTB specification.

Parameter
Name
Type
Examples
Required?
Default Value
Description
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/mp4noanyThe mime type allowed for video delivery (e.g.: video/mp4, video/x-flv)
deliveryTypeDelivery TypeStringprogressivenoprogressive

Supported delivery methods.

Allowed values: progressive, streaming, download

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

Passbacks

By default, if there was no ad available for the request, a zero-byte HTTP 200 response will be returned. Here is a sample of the headers:

If you have a roll-over tag that you would prefer us to use, give that tag to your Verve publisher services representative and Verve will integrate that on your behalf. Verve works with many third party advertising networks.  Please make sure you let your Verve publisher services representative know whether you would like the benefit of these advertising partners looking at inventory before we pass the ad back to you. Adding Verve ad tags to your mobile application is quick and easy.

  • No labels