VAST Demand 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 backward, 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 buyer (DSP or advertiser) with a link for a GET request;

Such link has macros replaced with values. 

The demand partner, after receiving the request and bidding, should send back an XML response.

Then, depending on the type of supply partner, Smarthub sends it as XML, or repacks it into OpenRTB-specified format and sends it further.

Note: For the correct operation of VAST endpoints, it is recommended to install a certificate on the balancer (if the QPS limit is 20K or more) or on the server (if the QPS limit is 10k or more). We recommend the wildcard certificate.

 

How to set up Demand Side VAST endpoint

Click 'New endpoint' at the Demand Side:

 

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

Set the Default price – the price that is used if there is no price in the response.

 

As we currently cannot create a VAST link for demand-side endpoint, you can use 3rd-party services to create it, and then copy and paste into VAST field of the endpoint.

Note: We have improved the work with macros: now we support all the macros of our partners, automatically recognizing the type by the value of the macro.

 

Then, do the rest of the settings (which are almost the same as for OpenRTB endpoints):

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

  • Set the margin for the endpoint. We usually recommend to set margin 0% for DSPs, and increase it only for those DSPs that bid with high prices.

  • Set the Spend Limit for the endpoint (optional).

  • Set QPS Limit – maximum QPS allowed for the endpoint. Please do not leave this field empty.

  • Set Auction type: 1st price or 2nd price auction, or Optimized model. We recommend the Optimized model.

  • Endpoint – the endpoint link you have received from the DSP.

  • Select at least one of the allowed Ad traffic Types (Mob, InApp, Desktop).

  • Set Filters:

    • Mismatched IP Filter –  if you turn this filter on, the system will filter out sources on which a high percentage of IP mismatches are observed. By IP mismatches, we mean cases when IP in request and IP on which impression happens are different. 

    • Mismatched Bundle Filter – this filter does the same as Mismatched IP filter, but tracks mismatches of bundles.

    • Filter out CTV (dev.types 3, 6, 7) – set if the endpoint is not allowing Connected TV traffic.

    • Only with IFA – select this setting if the DSP requires the identifier for advertiser (IFA) in a request.

    • Pre-bid filter (IP) – allow requests from SSPs that use prebid with IP.

    • Pre-bid filter (Device ID) – allow requests from SSPs that use prebid with device id.

 

Secure Filter – select if DSP will receive secure or non-secure traffic, or both.

Filter Porn – select ‘All’ to allow the DSP receiving any traffic including the adult traffic; select ‘Exclude Adult’ if the adult traffic is not allowed; select ‘Only Adult’ if the DSP is interested to receive only adult traffic.

Note: Such traffic is identified by the system using keywords in domain names.

 

Min tmax – set minimal tmax that you will be sending in requests to the DSP. Requests with lower tmax value will not be sent.

Note: Set this parameter for the DSPs that can not read the timeout from the bid request.

Ask the partner what Tmax they need and set it.

Max Bidfloor – set the maximum bid (CPM) at which this DSP agrees to buy traffic.

 

Allowed Countries – set the list of countries from which the traffic is allowed.

Allowed Sizes – set the allowed sizes. You can select sizes from the list, or add custom sizes.

Select allowed or blocked SSPs if needed.

Note: please add your own SSP endpoints to the blacklist in case you have endpoints on both Supply and Demand sides.

 

Set the list of allowed Device OS.

 

Set the ‘DSP Statistics API link’ that you received from the DSP. This is the link that allows you to receive statistics from the DSP side.

WARNING: you must change dates in the link to [%Y-m-d%] symbols.

After you have specified the statistic API link, click 'Test' to verify it. You  will receive ‘code 200’ notification in case of success.

 

After finished, click ‘Save’.


 

Click ‘Generate Endpoint’.


 

Note: A necessary requirement for establishing a DSP endpoint is a security certificate on a balancer (for endpoints with over 20k QPS) or on a server (for those with as high as 10k QPS). We recommend using wildcard certificate.


 

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

Note: there are only responses/requests repacked into OpenRTB format.

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

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

 

Request example:

 

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

 

Response example:

 

Request example

The original request that the Smarthub sends to the DSP contains 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

 

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

The minimal bidfloor for the request.

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

 

 

Response example

Based on the VAST request above, SmartHub expects such XML response:

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