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 VAST endpoint, Smarthub provides the supplier (SSP or publisher) with a link for a GET request;

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.

 

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

 

 

Repacked request example

{
  "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"
  }
}

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>

How to set up Supply Side VAST endpoint

Click 'New endpoint' at the Supply Side.

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

 

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.

 

All other settings can be configured as for usual RTB endpoint, as described here.

 

Click ‘Generate Endpoint’.

 

After the endpoint is saved, you will see such notification with a link:

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

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

Click ‘Macros’ to show or hide the list of available 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" 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’.

 

Related articles