Ad Recommendation API

VAST Tag Guide

2159 views 2019-08-12 Ofer Garnett 0

Introduction

The VAST tag integration is a campaign recommendation API used to access YouAppi’s video demand portfolio in real time. Publishers using this API are able to display video ads that are the most suitable for their users. YouAppi’s video real-time API is compatible with both client-to-server & server-to-server integrations.

API Request

Request Format

  • Request endpoint: https://onlineapi.youappi.com/v/ad?
  • Request method: GET

Request Parameters

The table below includes all of the fields that are available on the request.

 

 

Parameter Description Mandatory Data Type Possible Values
access_token The partner’s key used to access the API; provided by YouAppi Yes String
request_origin The origin of the request: client or server. Yes String

client

server
app_id The publisher’s package name/bundle ID/native ID. Yes String 284809790
publisher_token A custom ID of the sub-publisher in the publisher’s system Yes String 4568
publisher_name The name of the sub-publisher No String Awesome Game
ad_unit_id ID or description of the ad unit or placement Yes String
user_id_type The device’s advertising ID type – GAID (Google Advertising ID) when the OS is Android or IDFA (ID for Advertisers) when the OS is iOS. Yes String

gaid

idfa
user_id The device’s advertising ID Yes String
ip The client’s IP address Only when request_origin = server String
ua The client’s user agent string; must be URL-encoded! Only when request_origin = server String
preferred_orientation Preferred orientation of the video No String

portrait

landscape
companion_img_sizes Additional companion banners of the same app, added to the video ad using the following format: widthxheight, separated by comma. Cannot be used with html_comp_support parameter at the same time. No String 320×480
min_duration Minimum duration of video accepted, in seconds. No Integer
max_duration Maximum duration of video accepted, in seconds. No Integer
min_bitrate Minimum Bitrate of encoded video No Integer
max_bitrate Maximum Bitrate of encoded video No Integer
start_delay

Time in seconds for the video start delay

(If the start delay value is greater than 0, then the position is mid-roll and the value indicates the start delay.)

 No Integer
playback_method

Playback methods that may be in use.

Only one method is typically used in practice

 No Integer

1 for Autoplay Sound on

2 for Autoplay sound off

3 for Click to play
skippable Indicate whether the video is skippable or not No String

1 or true

2 or false
player_width The video player’s width in pixel No Integer 320/480/768/1024
player_height The video player’s height in pixel No Integer 320/480/768/1024
instl All placements are interstitials Yes Integer
year_of_birth The user’s year of birth No Integer
gender The user’s gender No String
device_lang The device language in ISO-639-1-alpha-2 type No String
html_comp_support Additional HTML companion ad of the same app, added to the video ad. Cannot be used with companion_img_sizes parameter at the same time. No String

1 for yes

0 for no
consent GDPR user’s consent signals the permission to process and store user’s personal information Yes (only for European users) String

1 or true

0 or false

Full consent string
gdpr Indicate if the impression is GDPR regulated or not. Yes (Only for European users) Integer

1 or yes

0 or no
COPPA Indicate if the impression is under COPPA regulation or not. Yes (Only for age restricted users) Integer

1

0

API Response

Response Format

The response of the API is in XML format using VAST 2.0.

No Ads

If there are no ads available, the VAST tag will be empty.

Error Messages

The following is a list of potential errors you may encounter in the response.

500: Internal Server Error

This error may indicate a number of unexpected server errors, and can usually be resolved by re-submitting the request.

4xx: Client Error; may include the following:

  • Invalid access token
  • User ID is missing from request
  • Invalid user ID type
  • Invalid request origin
  • Unsupported device OS/model

The cause for these errors must be corrected before resubmitting the request.

Best Practices

  • Please note that our recommendation engine is set to work under the assumption that calls are made in real-time or close to real-time. Caching – if performed – should be short-term for the duration of one active session per user.
  • Calls can originate from either the server or the client. If the request is sent from a server, the request_origin field must say “server” and the ip and user_agent fields must be populated with the details of the client.
  • To get the best results, please allow 30,000-60,000 impressions for YouAppi’s algorithm to learn your inventory’s DNA.

 

Request URL Generator

access_token :

request_origin :

app_id :

publisher_token :

ad_unit_id :

user_id_type :

user_id :

min_duration :

max_duration :

min_bitrate :

max_bitrate :

start_delay :

playback_method :

skippable :

player_width :

player_height :

instl :

year_of_birth :

gender :

device_lang :

html_comp_support :

consent :

gdpr :

Generated Request URL:

 

 

For list of some of the Ad Server macros, please see here.

For additional information and support please contact support@youappi.com.

Related Articles