Adomni uses the VAST specification for third-party media players to fetch ad content to play on their devices. VAST is used to serve both images and videos.
To use our VAST endpoint, you will need to create an account and add your devices.
See below for a walkthrough of the VAST integration process or try it out with our VAST simulator.
The following example uses VAST v2.0. Adomni also offers a VAST v3.0 endpoint which follows the same approach but different XML element names in a few cases.1. VAST Request
Make a HTTP request to Adomni's VAST endpoint for each device using its device key:
Note: When your device's schedule is full, you can make a VAST call with the URL param: ?notifyOnly=true, which returns an empty
<VAST> element. We log these requests and it helps with monitoring and troubleshooting.
Parse the XML response and use the
<Creatives> element to see what ad content there is to play. If there’s no content to play, you’ll get an empty
At this point, you may also wish to validate media width/height, type, and duration.3. Prefetch Content
Prefetch the creative(s) you expect to play (see:
<MediaFile> element). Or, see below for an alternative approach.
Play the ad content in your media player.5. Indicate a successful play (or error)
After playing the content, make a GET request to Impression URL provided in the
<Impression> element. Or, if there is a problem with the creative (such as it’s not a supported type), call the error URL found in
Note: Before calling the error URL, replace
[ERRORCODE] in the querystring with a value taken from the list of valid error codes.
Some developers prefer using their own internal identifier when making VAST requests, instead of Adomni's device key. This avoids the need to keep track of the Adomni device key on your side. We accomplish this by associating your internal identifier to the device in our system, in a field called "Integration Key".
The above call results in the same output as a normal VAST request using the device key.
If you'd like to take this approach, contact your Adomni representative and we'll provide you with your owner key and work with you to get the internal IDs mapped on our side.
For slow internet connections, it can be useful to prefetch content before the VAST request so you have ample time to download large files such as videos.
To accomplish this, you can call a special prefetch URL which returns all content expected to play in the next ~24hrs:
This endpoint returns a JSON document containing an array of file URLs:
Note that there is no guarantee that there won't be additional content that shows up in a subsequent VAST request since content can be added at any point. So you'll still want to handle checking for new content returned in the VAST response.
If you are using an Integration Key for your identifier, you can call the prefetch URL like so:
When possible, it's a good idea to account for intermittent internet connections or system outages.
In this situation, play confirmations (calls to the
<Impression> URL) should be queued and retried at a later time.
In order to support this, the
<Impression> URL should be appended with the parameter:
t=[timestamp], where the
[timestamp] is a timestamp in epoch milliseconds (e.g.
t=1546273150000) representing when the play in question ended.
t=[timestamp] is important for two reasons: 1) accurate play reporting, and 2) without the
t=[timestamp] param, calls to the impression URL made in rapid succession are ignored to prevent abuse/misreporting.
<Impression>URL expires 4hrs after showing up in a VAST response. After 4hrs, the URL will still work but will not be counted as a play in Adomni's system.
variant=cdatato the VAST request URL.
Checklist of decisions to make before a VAST integration:
Checklist of common dev tasks:
<Impression>element, or indicate an error by calling the
<Error>URL, substituting the appropriate
t=[timestamp]param to the Impression URL.