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

  1. Within VAST endpoint, Smarthub provides the buyer (DSP or advertiser) with a link for a GET request. Such link has macros replaced with values.

    Smarthub can provide a connection with demand endpoints using the auto-generated links for sending 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 platforms use 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 and do the macros matching to ensure the correct delivery of the details of the requests between different platforms. See the details in the section below.
    For our part, we create a link that corresponds to the structure and set of macros to the selected partner.
    Note: after creating a link on our side, it must be updated to bring in accordance with the link on the side of the partner.
    The link configuration process is described in detail in 'How to set up endpoint' section.
    Learn more about partners in 'Supported partner platforms' section.
  2. The demand partner, after receiving the request and bidding, should send back an XML response.
    Note: Responses with wrappers are not accepted.
  3. 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 50K 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 endpoint parameters: Set the endpoint Name. We recommend including the format info to the name. For example, DSPname_VAST_Video. This makes easier to track particular formats activity in the statistics. Select the 'VAST' Connection Type:

  • Select one of the Ad Types: Mob, InApp, Desktop, or CTV.
  • VAST – the endpoint link to connect with the demand partner.
    You have two options for creating links for the VAST endpoints: 
    • Build a link for known partners.
      In this case, the endpoint can be linked with one of the partner platforms (see the current list of partners and other additional info here).
      To do so: 
      1. Click ‘Show Suggested Macros’ below the ‘VAST’ field, and select the partner in the 'Ad Server' field:

        The link will be created automatically in a form that preferable for the selected partner, and with the set of macros suitable for that ad type.
        For example, you have selected ‘Partner X’ ad server and InApp ad type. In this case, we will create a link of the following form:
        https://v.partnerx.com/vast?pid={replace_me}&cb=[CB]&ab=[APP_BUNDLE]...
        the link will contain [APP_BUNDLE], [IDFA], and other macros useful for InApp traffic.
        WARNING: The suggested link contains the {replace_me} part (one or more, depending on the partner). It must be replaced with the credentials (one or more identifiers that make the link unique) obtained on the demand partner side.
      2. Create the link on the selected demand partner’s side and copy the credential part of it. For example, copy an identifier part: 3806bcb4fe6002ae7214bf140 taken from the link on the demand partner side, and replace the {replace_me} part on Smarthub side with it.
        The resulting link that will be set up on both sides will look like:
        https://v.partnerx.com/vast?pid=3806bcb4fe6002ae7214bf140&cb=[CB]&ab=[APP_BUNDLE]...
    • Use the endpoint link created via 3rd-party services.
      In this case, the link may be created using an account on 3rd-party service, then copied and pasted into the VAST field. You can edit the link and the macros if needed.
       
  • 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 Default price – the price that is used if there is no price in the response.
  • Set the Spend Limit for the endpoint (optional).
  • Set QPS Limit – maximum QPS allowed for the endpoint. Please do not leave this field empty.
  • Secure Filter – select if DSP will receive secure or non-secure traffic, or both.
  • Filter Porn – select ‘All’ to allow the DSP to receive 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 DSPs that can not read the timeout from the bid request. Ask the demand partner what Tmax they need and set it.

  • Max Bidfloor – set the maximum bid (CPM) at which this DSP agrees to buy traffic.
  • Countries – set the list of countries from which the traffic is allowed or blocked.
  • 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.

  • Player size – if the endpoint only accepts specific video player sizes, you can allow/block the list of sizes to exclude requests that can not be filled.
  • Allowed Sizes – set the allowed sizes. You can select sizes from the list, or add custom sizes.
  • Set the list of allowed Device OS.

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


 

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 50k 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.

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

 

For example, the original ‘sample’ macro contains ‘ip=[IP]’ pair. Real macros, as seen above, contains ‘macros=[value]’ pair with value replaced: ip=123.123.45.67

 

Below is the List of macros used by SmartHub (if not another partner is selected):

Note: You can see the list of available macros for partner platforms in the Macros matching section.

 

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
 

 

Supported partner platforms

 

Currently, SmartHub is able to process macros of different types from several partner platforms. At the moment, we support macros of the following partners depending on a traffic type:

 

Partner InApp Desktop MobileWeb CTV
Cedato        
StreamRail        
SpringServe        
LKQD        
Adtelligent        
 


 

We can transform macros from a format acceptable for the one side to a form acceptable for the other side endpoint. For example, the following link is used to connect to a SpringServe partner: https://vid.springserve.com/vast/12345678?w={{WIDTH}}&h={{HEIGHT}}&cb={{CACHEBUSTER}}&url={{ENCODED_URL}}&ip={{IP}}&ua={{USER_AGENT}}&dnt={{DNT}}&pp={{PRICE_PAID}}&consent={{CONSENT}}&gdpr={{GDPR}}&us_privacy={{US_PRIVACY}}

 

In this case, 12345678 is the identifier that differs the endpoint link among other links. w={{WIDTH}} is the pair ‘macros=value’. Within the bid request, the value must be substituted by real value, for example: w={{640}}

 

Each partner can have its own list of macros, macro names may differ, as well as separators.

 

Note: You can see the list of the Smarthub own macros in Request example section.