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
- 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. - 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.
- 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: is required. |
publisherdomain.com/fun/article2981 |
DOMAIN |
The domain where the impression happens. Note: At least one of these macros: 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: 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>