This guide provides detailed instructions for integrating the EXCO server into your technology stack setup via VAST integration, enabling you to maximize ad revenue by accessing EXCO’s top market ad server with advanced yield capabilities.
Overview
EXCO’s VAST tag integration allows you to request and retrieve CTV and in-app video ads from EXCO ad server by making a simple HTTP GET method. It can be used in the following scenarios:
- Server-to-Server Integration: This method involves direct communication between the publisher web server and EXCO’s. Ad requests and responses are handled entirely on the server side.
- Client-Side Integration: With this method, the client side interacts directly with EXCO’s ad server. Ad responses are placed within the publisher's web page.
Step-by-Step Integration
VAST Request Syntax
The VAST request has the following syntax:
|
https://v.ex.co/se/vast?pubid=[PUBLISHER_ID]&tagid=[TAG_ID]&env=[ENVIRONMENT] |
The placeholders (e.g. [TAG_ID]) must be replaced by the actual values that are listed in the table below:
| Parameter Name | Macro | VAST tag Query Parameter | Necessity | Description | Example |
| Environment | ENVIRONMENT | env | Required | The environment which the visitors will see the ads on |
app,web,ctv |
| Tag ID | TAG_ID | tagid | Required | The tag ID provided by EXCO | 134556677 |
| Publisher ID | PUBLISHER_ID | pubid | Required | The publisher ID provided by EXCO | ABSCO192JMSO |
Headers
Device IP
While the x-device-ip HTTP header is optional, it is highly recommended for server-side integrations with EXCO server. Correct configuration of this header in server-side environments ensures that EXCO receives the IP address of the end user, rather than the IP address of the server making the call.
Incorrect configuration of the x-device-ip header can result in significant revenue loss. This can occur due to monetization being halted because the network is classified as invalid traffic as the incorrect IP address is flagged as potentially malicious.
If the EXCO server receives both x-device-ip and x-forwarded-for headers, the x-device-ip header will be prioritized. The x-forwarded-for header may contain multiple IP addresses delimited by commas; if this occurs, the first (leftmost) IP address will be treated as the originating client's IP address.
User Agent
Both server-side and client integrations with EXCO server should correctly configure the x-device-user-agent HTTP header. This will ensure that EXCO receives the User Agent of the end user.
If the EXCO server receives both x-device-user-agent and user-agent headers, the x-device-user-agent header will be prioritized.
Examples
| Header | Necessity | Example |
| X-Device-Ip |
Highly Recommended |
111.111.111.111 |
|
X-Device-User-Agent |
Highly Recommended | AppleTV5%2C3%2F17.4 |
| X-Forwarded-For | Optional | 111.111.111.111, 22.222.22.22 |
| User-Agent | Optional | AppleTV5%2C3%2F17.4 |
Query Parameters
The parameters that are universally applicable to all ad environments and types are referred to as general parameters. In-app specific parameters are outlined in the "In-app parameters" sections below.
| Parameter Name | Query Parameter Name | Necessity | Type | Description |
| Placement parameters | ||||
| Environment | env | Required | STRING | The environment which the visitors will see the ads on |
| Tag ID | tagid | Required | STRING | The tag ID provided by EXCO |
| Publisher ID | pubid | Required | STRING | The publisher ID provided by EXCO |
| In App & CTV parameters | ||||
| App Bundle | appb | Required | STRING | The application bundle ID. |
| App Name | appn | Required | STRING | The application name. |
|
App Domain |
appd | Required | STRING | The fully qualified domain of the app. |
| App Store URL | appsu | Required | STRING | Full app store URL |
| Device Identifier Type | ifa_type | Recommended | STRING | An associated IFA type |
| Device Identifier | ifa | Recommended | STRING | The identifier for advertising of the device |
| App Version | appv | Optional | STRING | Application build version. |
| Inventory Partner Domain | ipd | Optional | STRING | A domain to be used for inventory authorization in the case of inventory sharing arrangements between an app owner and content owner. |
| Regs parameters | ||||
| GDPR Applies |
gdpr |
Required (for EU traffic)l | INTEGER | indicates if the given request is from a location where the GDPR applies. |
| GDPR Consent | gdpr_consent | Required (for EU traffic)l | STRING | A consent string passed from various Consent Management Platforms (CMP's) |
| GPP | gpp | Optional | STRING | the Global Privacy Platform (GPP) consent string |
| GPP Section ID | gpp_sid | Optional | INTEGER ARRAY | an array of the section(s) of the GPP string to be applied |
| Coppa |
coppa |
Optional | INTEGER | indicates if the given request is subject to the Children's Online Privacy Protection Act of the US |
| US Privacy | us_privacy | Optional | STRING | A mandatory string for all publishers in which they must pass the privacy consent for users from California |
| Video parameters | ||||
| Impression Height |
h |
Required | INTEGER | video player height in pixels |
| Impression Width | w | Required | INTEGER | video player width in pixels |
| Protocol | video_protocols | Recommended | INTEGER ARRAY | List of supported video protocols. Comma separated string. |
| MIME Types | video_mimes | Recommended | STRING ARRAY | Content MIME types supported. Comma separated string. |
|
API Frameworks
|
video_api | Recommended | INTEGER ARRAY | List of supported API frameworks for this impression. Comma separated string. |
| Placement Type | video_placement | Optional | INTEGER | the video placement type in accordance with IAB video guideline. |
| Placement Sub Type | video_plcmt | Optional | INTEGER | the video sub placement type in accordance with updated IAB video guideline. |
| Ad Maximum Duration | video_maxduration | Optional | INTEGER | Maximum video ad duration in seconds. |
| Skippable | video_skip | Optional | INTEGER | Indicates if the placement imposes ad skippability |
| Playback | video_playbackmethods | Optional | INTEGER ARRAY | the video playback method. Comma separated string. |
| Device parameters | ||||
| User IP | ip | Optional | STRING |
This parameter carries the IP address of the end user and is valuable when the IP address can't be included in the HTTP header of the request. Details about parameter priority are outlined in the "User Agent & IP logic" section below. |
| User Agent | ua | Optional | STRING |
This parameter carries the user agent of the end user and is valuable when the user agent can't be included in the HTTP header of the request. Details about parameter priority are outlined in the "User Agent & IP logic" section below. |
| Device Width | device_width | Recommended | INTEGER |
Screen's physical width in pixels. This is useful when the video impression size differs from the screen size. Recommended for In App |
| Device Height | device_height | Recommended | INTEGER |
Screen's physical height in pixels. This is useful when the video impression size differs from the screen size. Recommended for In App |
| Device Pixel Ratio | device_pixel_ratio | Optional | INTEGER | The ratio of physical pixels to device independent pixels |
| Device PPI | device_ppi | Optional | INTEGER | Screen dimensions in inches |
| Limit Ad tracking | lmt | Optional | INTEGER | “Limit Ad Tracking” signal commercially endorsed. |
| Do not track | dnt | INTEGER | Standard “Do Not Track” flag as set in the header by the browser | |
| Content parameters | ||||
| Content Id | content_id | Optional | STRING | ID uniquely identifying the content. |
| Content Episode | content_episode | Optional | INTEGER | Episode number |
| Content Title | content_episode | Optional | STRING | Content Title |
| Content Series | content_series | Optional | STRING | Content Series |
| Content Season | content_season | Optional | INTEGER | Content Season |
| Content Genre | content_genre | Optional | STRING | Genre that best describes the content |
| Content Producer Name | content_producer_name | Optional | STRING | The name of the content producer |
| Content Producer Domain | content_producer_domain | Optional | STRING | The primary domain of the producer |
| Content Livestream | content_livestream | Optional | INTEGER | Indication of live content |
| Content Categories | content_categories | Optional | STRING ARRAY | Array of content categories using IDs from the IAB taxonomy. |
| Content Keywords | content_keywords | Optional | STRING ARRAY | Comma separated list of keywords describing the content. |
| Content Categories Taxonomy | content_cattax | Optional | STRING | The taxonomy in use for cat. If no cattax field is supplied, the IAB Content Category Taxonomy 1.0 (1) is assumed. |
| Content URL | content_url | Optional | STRING | A single URL of the content |
| Content Language | content_language | Optional | STRING | Content language using ISO-639-1-alpha-2. |
| Content Length | content_length | Optional | INTEGER | Length of content in seconds |
| Network Name | network_name | Optional | STRING | The Network the content is on |
| Channel Name | channel_name | Optional | STRING | The Channel the content is on |
| Channel Domain | channel_domain | Optional | STRING | The primary domain of the channel |
User Agent & IP logic
When sending server 2 server request calls, EXCO uses the following logic to obtain the value for User Agent, Domain and IP:
User Agent: The server will determine the User Agent value by checking the following, in order of priority:
- ua query parameter
- x-device-user-agent header
- user-agent header
IP: The server will determine the IP value by checking the following, in order of priority:
- ip query parameter
- x-device-ip header
- x-forwarded-for header