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:

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.

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.

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>