Integration‎ > ‎

Server Ad API

Introduction

The Vdopia Ad API allows publishers and partners to request ads from the platform and place them on their sites/apps. The API supports most of Vdopia's moblie ad formats. The different output formats allows integration with different kinds of ad containers like mobile web sites, full-page interstitials in apps or banner web views. 

This API is available on Vdopia servers at the location:
http://serve.vdopia.com/adserver/html5/adFetch

Ad Request

The caller needs to construct a URL containing all the parameters required to specify the ad context and type of ad desired.

Examples

Request Url For XHTML Response:

http://serve.vdopia.com/adserver/html5/adFetch/?ak=AX123&adFormat=preappvideo&sleepAfter=0&version=1.0&requester=acmecorp&ipAddress=166.137.8.134&di=981A6F712C121&output=xhtml

The response for this request would have the following structure:
<?xml version='1.0' encoding='utf-8' ?> <ad type='xhtml'> <xhtml><![CDATA[{Ad HTML content to be loaded in client browser/web-view}]]></xhtml> </ad>

Request Url For XML Javascript Response:

http://serve.vdopia.com/adserver/html5/adFetch/?ak=AX123&adFormat=preappvideo&sleepAfter=0&version=1.0&requester=acmecorp&ipAddress=166.137.8.134&di=981A6F712C121&output=javascript

The response for this request would have the following structure:

<?xml version='1.0' encoding='utf-8' ?> <ad type='javascript'> <xhtml><![CDATA[{Ad JS to be loaded into browser/web-view}]]></xhtml> </ad>

Ad Request Parameters:

The parameters supported by the API are listed in the following table:

Vdopia-Ad-Tag-Parameters


Targeting Parameters

User targeting (demographic / behavioral) information to allow a more informed selection of ads.


Example of encoded Targeting parameters:
target_params=sex%3Df%7Cbirthday%3D1989-07-25%7Cethnicity%3DLatino%2FHispanic%7Clanguage%3DSpanish
We pick up best available ad format based on inout adFormat and allowed ad formats in the portal. Here is the document which explains this.

Error response

 Error Code  Description
 201
 Invalid API Key
 202  Invalid ad format
 203  No Ad found for the specified parameters (could be because of no campaigns targeted, campaigns exhausted for the day, targeting parameters etc.)

Examples

No ad found:
http://serve.vdopia.com/adserver/html5/adFetch/?ak=KEYWITHNOADS&adFormat=banner&sleepAfter=0&version=1.0&requester=acmecorp&ipAddress=166.137.8.134&di=981A6F712C121&output=xhtml

Response:

<?xml version='1.0' encoding='utf-8' ?> <ad type='error'> <errorCode>203</errorCode> <errorReason>No ad found.</errorReason> </ad>

Invalid API Key request:
http://serve.vdopia.com/adserver/html5/adFetch/?ak=NONEXISTENTAK&adFormat=preappvideo&sleepAfter=0&version=1.0&requester=acmecorp&ipAddress=166.137.8.134&di=981A6F712C121&output=xhtml

Response:

<?xml version='1.0' encoding='utf-8' ?> <ad type='error'> <errorCode>201</errorCode> <errorReason>Invalid API Key.</errorReason> </ad>


Invalid API Format:
http://serve.vdopia.com/adserver/html5/adFetch/?ak=AX123&adFormat=nosuchformat&sleepAfter=0&version=1.0&requester=acmecorp&ipAddress=166.137.8.134&di=981A6F712C121&output=xhtml

Response:

<?xml version='1.0' encoding='utf-8' ?> <ad type='error'> <errorCode>202</errorCode> <errorReason>Invalid ad format requested.</errorReason> </ad>

Comments