Ad Connect API

Vdopia provides a Ad Connect API to their advertiser partner to create/manage campaigns in Vdopia system.


This API has three part 

1: Creating campaigns 

2: Pausing Campaign/Ads

3: Resuming Campaign/Ads


1-Creating Campaign


    SSL Only : (URL)

            https://mobile.vdopia.com/rest/campaign/create


To create a new campaign on Vdopia, send a POST request to the create URL with a json object. The object to post is defined below. 

 Key   Value   Required
 name      Required
 start_time "YYYY-MM-DD HH:MM" Required
 end_time "YYYY-MM-DD HH:MM" Required(local time)
 timezone 3 letter timezone code.
e.g. PST,EST,CST, MST Daylight savings are automatically applied
Required
 template_id Pricing model (CPM, CPC, CPL), Channel Targeting , Category Targeting, Age Targeting, Geographic targeting, Currency, Review Status Required (setup by Vdopia upon request)
 price Price as per the pricing Required model in the template Required
 budget Decides the total Required number of impressions/clicks/leads Required
 API_USER_ID API user id provided by Required Vdopia Required
 API_SECRET API secret provided by Required Vdopia Required
 locobject If template does not Optional outline location targeting, refer to the Location Object below Optional
 Category If the template does not Optional outline category targeting please refer to the possible content category options below Optional
 price_model If the template does not Optional outline pricing model, please refer to the possible pricing model options below. Optional
 ads Object that outlines all Required the creatives used for the campaign, each set of creative will receive a separate ad_id and can be used to preview the campaign Required


Location Object
JSON Array of Min and max latitude and longitude where the you require the campaign to run.

[ {“minlat”:, “minLong”: , “maxlat”:, “maxlong”:},{“minlat”:, “minLong”: , “maxlat”:, “maxlong”:}..... ]

This is basically an array of bounding boxes: [BoundingBox1, BoundingBox2, BoundingBox3... ] 



BoundingBox
 Key   Value   Description
 minLat -180 to 180 Minimum latitude of the bounding box
 maxLat -180 to 180 Maximum latitude of the bounding box
 minLong -90 to 90 Minimum longitude of the bounding box
 maxLong -90 to 90 Maximum longitude of the bounding box


Please note these values wrap around hence ensure that you are passing minLat which is usually less than maxLat and minLong which is usually less than maxLong.





Category Values

 Code   Value 
 AU Automotive
 TR Travel & Places
 SC Science & Technology
 SP Sports
 CR Cricket
 MU Music
 HC Humor & Comedy
 PA Pets & Animals
 NE News
 NA Navigation
 BU Business
 HF Healthcare & Fitness
 SH Showbiz
 LF Lifestyle
 PO Politics
 FI Finance
 EN Entertainment
 GA Games
 SN Social Networking
 PH Photo & Video
 PR Productivity
 BO Books
 UT Utilities
 ED Education
 ME Medical
 RE Reference
 WE Weather


Price Model
 Value   Description
 CPM Cost per thousand impressions, the price declared in the API will you billed that amount for every 1000 impressions Vdopia runs
 CPC Cost per click, the price declared in API will mean that you will be billed that amount for every click that Vdopia records.
 CPL Cost per every lead, the price declared in the API will mean that you will be billed that amount for every lead that Vdopia records.


Note on CPL pricing: Since CPL pricing models are entirely dependent on the API user responding back with the lead tracker with the right parameters. All CPL pricing campaigns will be run at a very slow rate until conversion trackers are regularly called, the rate will be monitored to ensure that the tracking and conversions are constantly happening. In case conversions stop happening or the rate dramatically reduces the campaign delivery will decrease or even entirely stop.



A better more controlled option is to either choose CPC or CPM pricing model and request Lead based optimization, Vdopia system will ensure that the leads are captured and optimized upon. In case the leads or conversions stop at any point in time, Vdopia will notify the account owner about possible remedial actions.





Age Group

 Value 
teen
20-35
35-50
50+


Ads Object

Ads object is an array of all ad objects associated with the campaign. Format for all ads need to be the same.

[AdObject1, AdObject2, AdObject3...]

AdObject is an object containing all the assets required to visually run a campaign. With the .VDO technology Vdopia is capable of using different kinds of assets to generate video advertisement. You may also choose to run different ad objects for different periods of time using this API.



AdObject
 Key   Values   Commnets
 format Described in the table Required below Required
 start_time "YYYY-MM-DD HH:MM" Required
 videofile URL for the video file Videofile to process Videofile or screenshotlist Required for format=video,vdobanner
 Imageurl URL for the banner Required for format=banner, static, leadervdo

Optional for adformat=video
 expanded_image_url URL for expanded banner the left side of the image will be covered with video so please use the aspect ratio to create banners that appear consistant Required for vdobanner
 screenshot_list Price as per the pricing Required model in the template Required
 budget [imageurl1,imageurl2, imageurl3...] Videofile or screenshotlist Required for format=video,vdobanner, maximum of 360 urls. Sequence is important
 audio_url URL pointing to MP3 file soundtrack Optional, used only when screenshotlist method is used for generating video ads
 duration Duration in seconds Optional, used only when screenshotlist method is used. This is used to compute framerates to render screenshots.
 dimensions 320x48, 300x250, 728x90 Required for adformat: banner (any), vdobanner (320x48, 300x250), leadervdo (728x90) , Dimensions of the creative, the imageurl should match the size else exceptions would be raised.
 expanded_dimensions 320x75 Required for adformat: vdobanner and dimensions=320x48
 video_dimensions {width}x{height} Must follow the aspect ratio, all screenshots/videos will be checked for matching aspect ratio and dimensions.
 video_aspect_ratio 4x3 or 16:9 Screenshots and Video will be scaled and checked accordingly
 destination_url URL to lead user to once a click event occurs Can have Vdopia macros defined below ([VDO_click_ID] macro is required for all CPL campaigns)
 valid_from “YYYY-MM-DD HH:MM” Screenshots and Video will be scaled and checked accordingly
 valid_to “YYYY-MM-DD HH:MM” Optional. Time when the ad stops running; follows the timezone specified in the campaign object


Following is an example curl request to call the create api: curl -X POST \
-H "Content-Type: application/json" \
-d '{"name":"Pizza Hut 2012","startTime":"2012-12-06 12:23",
   "endTime":"2012-12-06 12:23", "timezone":"PST", "template_id":1234,

   "API_USER_ID":121, "API_SECRET": "THIS_IS_A_SAMPLE_SECRET",
    "locobject":[{"minlat": -74.004901, "minlong": 41.9995495,
      "maxlat": -73.004901 , "maxlong": 41.0005495}],
   "ads":[{" format ":"video",
        "screenshot_list":[ "http://myserver.com/images/frame1.jpg",
       "http://myserver.com/images/frame2.jpg",
       "http://myserver.com/images/frame3.jpg",
       "http://myserver.com/images/frame4.jpg",
       "http://myserver.com/images/frame5.jpg"],
       "duration":10, "video_dimensions":"320x180",
      "audio_url":"http://myserver.com/music/background.mp3",
      "destination_url":"http://myserver.com/mylandingpage"
   }]
}' https://mobile.vdopia.com/rest/campaign/create

Please note in the above example dimensions of frames must match 320x180px. Also the last frame stays on for 5 seconds after the 10-second duration is complete. You may place messages any “Actionable” messages for your customer in this frame.



Output

The output of the creation API is as defined below:


 Key   Value
 campaign_id Id of the campaign, for reporting , pause, resume, requests
 ad_id_list Id(s) of each ad created using the create api
 ad_preview_url URL to preview each ad, has a macro [AD_ID], you will need to replace the macro with actual ad_id from the ad_id_list.
 error_description When you get a 400 Bad Request or 401 Unauthorized as status, this will be populated with a human readable string describing the error.
 status 201 Created
400 Bad Request
401 Unauthorized


2-Pausing Campaigns/Ads


    SSL Only : (URL)

            https://mobile.vdopia.com/rest/campaign/pause




 Key   Value   Required
 minLat -180 to 180 Minimum latitude of the bounding box
 API_USER_ID API user id provided by Vdopia Required
 API_SECRET API secret provided by Vdopia Required
 campaign_id Id of the campaign, for reporting , pause, resume, requests Required
 ad_id Id for the ad that you want to pause. Optional. If you have this parameter, the campaign will not be automatically paused.


The output of the pause API is as defined below:

Output

The output of the creation API is as defined below:


 Key   Value
 error_description When you get a 400 Bad Request as status, this will be populated with a human readable string describing the error.
 status 202 Accepted
400 Bad Request
401 Unauthorized


3-Resuming Campaign/Ads


    SSL Only : (URL)

            https://mobile.vdopia.com/rest/campaign/resume




 Key   Value   Required
 API_USER_ID API user id provided by Vdopia Required
 API_SECRET API secret provided by Vdopia Required
 campaign_id Id of the campaign that you want to resume Required
 ad_id Id for the ad that you want to resume. Optional. If you have this, the campaign will not be automatically resumed if it was paused earlier.


Output

The output of the pause API is as defined below:


 Key   Value
 error_description When you get a 400 Bad Request or 401 Unauthorized as status, this will be populated with a human readable string describing the error.
 status 202 Accepted
400 Bad Request
401 Unauthorized
Comments