VAST Supply endpoints

Overview

For SSPs and DSPs that work with VAST traffic and doesn't support OpenRTB, SmartHub offers VAST endpoints functionality as an alternative to OpenRTB.

Smarthub can transform requests and responses from OpenRTB to VAST or backwards, providing the ability to connect supply and demand partners whether each of them working with RTB or VAST traffic.

Important: All SSP endpoints can trade with all DSP endpoints regardless of their type.

 

How it works

  1. Within the VAST endpoint, Smarthub provides the supplier (SSP or publisher) with a link for a GET request.

    Smarthub can provide a connection with supply endpoints using the automatically generated links for receiving the requests.
    A possible problem is that the different platforms may use the different macros for the same type of data, which may lead to their incompatibility: for example, some SSP platform uses the [pageUrl] macro to provide the page URL, while some DSP platforms require the {content_page_url} macro for this information.
    Keeping that in mind, we collect possible variants of macros to do the macros matching to ensure the correct delivery of the details of the requests between different platforms.
    On our part, we create a link, and suggest macros for that partner and selected Ad Type.
  2. The SSP replaces (substitutes) macros with values and sends it to SmartHub. SmartHub sends it to DSPs: repacked into OpenRTB-specified format for RTB-demand or in XML for VAST-demand partners.
  3. After receiving a response, SmartHub repacks (transforms) it back to XML VAST and sends it to SSP.

 

Note: We also support VPAID functionality. See more in a separate article.

 

How to set up Supply Side VAST endpoint

Click 'New endpoint' at the Supply Side.

Set the Name and select the 'VAST' Connection Type:

 

  • Select Ad Types.
  • If you select the partner from the 'Ad Server' field, we will suggest macros specifically for the selected partner.
    The endpoint link will be created automatically.
  • Set Bidfloor so that requests without a bidfloor macro value have this bidfloor.
  • Select Sizes: ‘All Sizes’ in case the SSP serves different sizes. Or, select ‘Custom Sizes’ and set Width and Height – in this case, SmartHub will set that size for all requests.
  • Select a company from the list, or select ‘+ Create New Company’ to create a new one.
  • Select the region of the data center.

Note: you cannot change the region later.

  • Margin - a percent you will charge from the endpoint revenue.
  • Spend Limit
  • Set whether to use Protected Media scanner to scan the traffic from this endpoint.
  • Paste Platform Statistics API link to obtain statistics from supply partner.
  • SSP’s Statistics API link will contain an automatically generated link when the endpoint saved. Provide the partner with this link. For example:

     


 

Click ‘Generate Endpoint’.

 

Later, after saving the endpoint, you will see additional settings on the endpoint page:

  • DSPs allows to set whitelist or blocklist of DSPs allowed/blocked for this endpoint.
  • To set the list of blocked creative IDs, click ‘Blocked crids’ on the edit page of an existing endpoint, then add the list manually (put each ID in a new line) or upload a TXT file with the list of crids:

    You can also download the list to your device.
  • Set ads.txt – here you can specify sellers that are authorized to work with this SSP. To do so, click ‘ads’txt’ link and add records to the list. Then click ‘Add seller’, set the domain, pub id (if needed) and click ‘Add’:

    Then click ‘Save’.
  • .Set the contact email and comment (it may describe features and useful information regarding this endpoint).

 

Also, immediately after the endpoint is saved, you will see such notification with a link. Provide the supply partner with this link to establish a connection to the endpoint.

You can add several macros to the link in order to provide additional information with a request.

Use the drop-down to add macros to the link.

Click ‘Macros’ to show or hide the list of available macros.

If you have selected Ad Server, then the list will contain macros suitable for that partner and ad type. For example, you have selected InApp ad type. In this case, we will add APP_BUNDLE, IDFA, and other macros useful for InApp traffic, and suggested macros will be enclosed in curly brackets as the selected partner requires.

If Ad Server is not selected, we will offer our own list of macros.

Note: CB (cash buster), UA (user agent), IFA (device identifier for the advertiser) and IP macros are already included in the link.

You have to add at least one of the following macros: PAGE_URL (for mobile web traffic), DOMAIN (for desktop web traffic), or APP_BUNDLE (for application traffic).

 

After adding the macros, click ‘Save’.

 

You can change the macros later on the endpoint editing page.

 

After some time of the endpoint working, you will be able to see examples of responses.

Note: there are only responses repacked into OpenRTB format.

To do this, go to the endpoint page, scroll down and click the "Valid Response Sample" or "Valid VAST Tag Sample" button:

You will see the code of the response sample and the exact date and time it was sent:

 

 

You can get another example by clicking ‘Next’ or ‘Prev’.


 

Original request example

The original request that the SSP sends to SmartHub must contain macros, substituted by real parameters:

http://domain123.com/?seat=3V3Bhi4uN1AEJHmYQFOM&token=j3MawqGdDJviP3NEMofyWg4Hmfd1meed&cb=1258812401ab14d&ua=Mozilla%2F5.0%20(Windows%20NT%2010.0;%20Win64;%20x64)%20AppleWebKit%2F537.36%20(KHTML,%20like%20Gecko)%20Chrome%2F80.0.3987.106%20Safari%2F537.36&ip=123.123.45.67&w=480&h=320&ifa=AB1234CD%2DA567%2DB89C%2DD09E%2D42CBA1B23456&domain=publisherdomain.com&make=Apple

 

Note: each macro specified in the link must be replaced with the real value depending on the user or other data.
For example, ip=[IP] would be wrong and would lead to classification of the request as invalid.
In this case, ...&ip=123.234.45.56&... would be the correct format.

 

Below is the list of macros available:

 

Macro

Description

Example

CB

Cash buster: a hash (character sequence), uniquely generated for each link in order to prevent page caching.

Required macro.

1258812401ab14d

UA

User agent

Required macro.

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.106 Safari/537.36

IP

User’s IP address.

Required macro.

123.123.45.67

WIDTH

Placement width.

Required macro.

480

HEIGHT

Placement height.

Required macro.

320

IFA

Identifier for advertiser (different for each device)

Required macro.

AB1234CD-A567-B89C-D09E-42CBA1B23456

BIDFLOOR

SSP should substitute this macro with the minimal bidfloor for the request, otherwise, Smarthub will substitute it with the bidfloor value from the corresponding setting of the endpoint.

2.5

PAGE_URL

URL of the page where the impression happens.

Note: At least one of these macros:
[APP_BUNDLE], [PAGE_URL], [DOMAIN]

is required.

publisherdomain.com/fun/article2981

DOMAIN

The domain where the impression happens.

Note: At least one of these macros:
[APP_BUNDLE], [PAGE_URL], [DOMAIN]

is required.

publisherdomain.com/

DNT

Do-not-track flag.

0 (tracking is allowed)

or 

1 (do not track)

LOCATION_LON

Longitude from -180.0  to +180.0, where negative is West.

2.35121

LOCATION_LAT

Latitude from -90.0 to  +90.0, where negative is South.

48.85661

CATEGORY

Advertising category according to IAB classification.

IAB2.1

REF_URL

URL from which the user went to the page of the event (for web).

OR

Publisher's referrer URL to determine the source of the click..

publisherdomain.com/fun/article1435

APP_BUNDLE

Application bundle identifier (only for apps).

Note: At least one of these macros:
[APP_BUNDLE], [PAGE_URL], [DOMAIN]

is required.

funnyapp.bundle.name

STORE_URL

The app store URL for this app.

 

DEVICE_MAKE

The name of the device manufacturer.

Samsung

DEVICE_MODEL

The name of the device model.

SM-N910G

OSV

The user’s operating system version number.

6.1

DEVICE_TYPE

The type of device according to IAB Specification:

1 Mobile/Tablet

2 Personal Computer

3 Connected TV

4 Phone

5 Tablet

6 Connected Device

7 Set Top Box

5

APP_NAME

The name of the application.

funnyapp

GDPR

General Data Protection Regulation consent. Required for requests from Europe

0 or 1

CONSENT

CCPA consent. Required for requests from California, USA.

0 or 1

API

Framework API versions

2

CARRIER

Cellular carrier name

 

MAX_DURATION

Maximal video ad duration in seconds

30

MIN_DURATION

Minimal video ad duration in seconds

5

 

 

Repacked request example

Based on the VAST request above, SmartHub parses parameters sent via macros and transforms into OpenRTB-format request:

{
	"site": {
		"id": "eb1a64f02f35067c73385f28fd7b5334", "ref": "http://www.publisherdomain.com/ad01", "cat": [
		"IAB1"
		],
		"page": "http://www.publisherdomain.com/ad123", "name": " SitePageName ", "domain": "publisherdomain.com",
		"content": {
			"id": "eb1a64f02sd32sadf",
			"title": "Page Title",
			"cat": [ "IAB2-2" ]
		},
		"publisher": { "id": "12345",
			"domain": "publisherdomain.com"
		}
	},
	"id": "86545bd4-3218-4ddd-bf89-0e82657b6c04",
	"tmax": 300,
	"imp": [
	{
		"secure": 0,
		"id": "1",
		"bidfloor": 4,
		"video": {
			"w": 480,
			"protocols": [2, 5],
			"api": [1, 2]
			"minduration": 15, "mimes": [
			"video/mp4"
			],
			"linearity": 1,
			"maxduration": 30,
			"h": 320
		}
	}
	],
	"at": 2,
	"device": {
		"ifa": "86545bd4bf890e82657b6c04", "os": "iOS",
		"model": "iPad",
		"ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.106 Safari/537.36",
		"devicetype": 1, "make": "Apple",
		"ip": "123.123.45.67"
	},
	"cur": [ "USD"
	],
	"user": {
		"id": "0"
	}
}

 

Macros matching

 

Currently, SmartHub is able to process macros of different types from many platforms.

Therefore, we support all the macros of our partners, automatically transforming the macro into a format acceptable for each partner.

 

The following is a list of macros used by our main partners for Desktop + MobWeb traffic, and we expect the macros to have the names or values as ​​listed.

 

Description

Allowed macro names

Allowed values

Cache buster (Cache breaker), a macro that helps avoid caching

cb

cb

rnd

cb

cb

cb

[CB]

[CACHE_BREAKER]

[CACHEBUSTER]

[CACHE_BUSTER]

[cache_breaker]

{cb}

Page URL

page_url

pageUrl

pageurl

d

pageURL

page_url

content_page_url

[PAGE_URL]

EMBEDDING_PAGE_URL

[PAGEURL] loc YOUR_MACRO(page url)

[URL]

[INSERT_PAGE_URL]

[page_URL]

{content_page}

Height

height

pi.height

height

playerSize

height

height

player_height

[HEIGHT]

HEIGHT

[HEIGHT]

YOUR_WIDTH_MACROxYOUR_HEIGHT_MACRO

[player_height]

{height}

{player_height}

Width

width

pi.width

width

playerSize

width

width

player_width

[WIDTH]

WIDTH

[WIDTH]

YOUR_WIDTH_MACROxYOUR_HEIGHT_MACRO

[player_width]

{width}

{player_width}

Sub ID

sub_id

id

videocontentid

[SUB_ID]

VIDEO_ID

[VIDEO_ID]

IP

ip

a.ip

ip

ip

ip

ip

uip

[IP]

IPADDRESS

[IP_ADDRESS]

YOUR_MACRO

[IP]

[ip_address]

{uip}

User agent

ua

a.ua

ua

ua

ua

[UA]

USER_AGENT

[USER_AGENT]

[user-agent]

{ua}

Do not track

dnt

[DO_NOT_TRACK]

Description

description

videocontentdescription

VIDEO_DESCRIPTION

[VIDEO_DESCRIPTION]

Duration

duration

videocontentduration

video_duration

VIDEO_DURATION

[VIDEO_DURATION]

[replace_me]

Title

title

videocontenttitle

pageTitle

VIDEO_TITLE

[VIDEO_TITLE]

[PAGE_TITLE]

URL

url

videocontenturl

site_url

VIDEO_URL

[VIDEO_FILE_URL]

{site_url}

Content id

contentid

[CONTENT_ID]

Content title

contenttitle

[CONTENT_TITLE]

Content length

contentlength

[CONTENT_LENGTH]

Content URL

contenturl

[CONTENT_URL]

Inventory type

i_type

[inventory_type]

Location Lat

loclat

geo_lat

[LOCATION_LAT]

{geo_lat}

Location Lon

loclong

geo_lon

[LOCATION_LONG]

{geo_lon}

Viewable

pi.viewable

VIEWABILITY

 



 

The following is a list of macros used by our main partners for InApp traffic, and we expect the macros to have the names or values ​​listed.


 

Description

Allowed macro names

Allowed values

Cache buster

cb

cb

rnd

cb

cb

[CB]

[CACHE_BREAKER]

[CACHEBUSTER]

[CB]

[replace_me]

Page URL

page_url

pageUrl

d

[PAGE_URL]

EMBEDDING_PAGE_URL

[APP_BUNDLE]

Height

height

height

height

height

[HEIGHT]

[HEIGHT]

[player_height]

[replace_me]

Width

width

width

width

width

[WIDTH]

[WIDTH]

[player_width]

[replace_me]

Sub ID

sub_id

[SUB_ID]

IP Address

ip

a.ip

ip

ip

uip

[IP]

[IPADDRESS]

[IP_ADDRESS]

[ip_address]

[replace_me]

User agent

ua

a.ua

ua

ua

ua

[UA]

[USERAGENT]

[USER_AGENT]

[user_agent]

[replace_me]

Operating System Version

osvers

[Operating_System_Version]

Do not track

dnt

dnt

te

[DO_NOT_TRACK]

[DO_NOT_TRACK]

[target_ad_tracking_enabled]

App Name

app_name

appName

appname

appn

appname

app_name

[APP_NAME]

[APPNAME]

[APP_NAME]

[APP_NAME]

[App_Name]

[replace_me]

App Bundle

bundle_id

app_bundle

bundleid

appb

bundleid

app_bundle

[BUNDLE_ID]

[APP_BUNDLE]

[APP_BUNDLE_ID]

[APP_BUNDLE]

[Bundle_ID]

[replace_me]

App IDFA

appidfa

[APP_IDFA]

App AID (Advertising ID?)

appaid

[APP_AID]

App Store ID

appsi

appurl

[APP_STORE_ID]

[APP_STORE_or_Site_URL]

App Store URL

app_store_url

app_storeurl

appstoreurl

appsu

[APP_STORE_URL]

[APP_STOREURL]

[APP_STORE_URL]

[APP_STORE_URL]

App Category

app_category

appc

[APP_CATEGORY]

[APP_CATEGORY]

App Version

appversion

appv

[APP_VERSION]

[APP_VER]

IFA (Identifier for Advertiser) (IDFA for iOS and AID for Android)

ifa

a.idfa

idfa

idfa

idfa

[IFA]

[IDFA]

[IDFA]

[Android_ID_or_iOS_ID_for_Advertisers]

[replace_me]

IDFA MD5 Hex

idfamd5hex

[IDFA_MD5]

IDFA SHA1 Hex

idfasha1hex

[IDFA_HEX]

Device SID

dvc_sid

[DVC_SID]

Device ID

deviceid

[DEVICEID]

Location

loc

[LOCATION]

Geo Location: Latitude

user_lat

lat

loclat

loclat

lat

geo_lat

[USER_LAT]

[LATITUDE]

[LOCATION_LAT]

[LOCATION_LAT]

[Latitude]

[replace_me]

Geo Location: Longtitude

user_lon

lon

loclong

loclong

lng

geo_lon

[USER_LON]

[LONGITUDE]

[LOCATION_LONG]

[LOCATION_LONG]

[Longitude]

[replace_me]

Limit Ad Tracking (for OTT)

lmt

[LMT]

Country

country

[COUNTRY_ID]

Advertising ID

a.aid

aid

adid

[AID]

[ADVERTISING_ID]

[replace_me]

Advertising ID MD1 Hex

aidmd5hex

[ADVERTISING_ID_MD5]

Advertising ID SHA1 Hex

aidsha1hex

[ADVERTISING_ID_HEX]

Windows AID

a.waid

[WindowsAID]

Content ID

contentid

[CONTENT_ID]

Content Title

contenttitle

[CONTENT_TITLE]

Content Length

contentlength

[CONTENT_LENGTH]

Content URL

contenturl

[CONTENT_URL]

Inventory type

i_type

[inventory_type]

Network (WiFi, Cellular or unknown)

network

"[Network_Type_w_c_or_u_for_unknown]"

Carrier

carrier

[Network_Carrier_Name]

 



 

Response example

After receiving the request and bidding, Smarthub responds with such XML:

 

<?xml version=“1.0” encoding=“UTF-8"?>

<VAST version=“2.0”>

  <Ad id=“[HASH]“>

    <InLine>

      <AdSystem>Smarty

      </AdSystem>

      <AdTitle>Smartyads Video Ad

      </AdTitle>

      <Description>RTB Video Ad

      </Description>

      <Creatives>

        <Creative AdID=“123455”>

          <Linear>

          <Duration>00:00:30

          </Duration>

          <VideoClicks>

            <ClickThrough>

              <![CDATA[https://adsite.com/link/link2/]]>

            </ClickThrough>

          </VideoClicks>

            <MediaFiles>

              <MediaFile delivery=“streaming” type=“video/mp4” width=“1920" height=“1080”> <![CDATA[https://library.adsite.com/video/11345_672c784e075030353f247b171eb7a0c3.mp4]]>

              </MediaFile>

            </MediaFiles>

          </Linear>

        </Creative>

      </Creatives>

    </InLine>

  </Ad>

</VAST>