Partner API Integration

Adgebra Ad-Serving API integration Guidelines

These API integration guidelines will be able to request demand from adgebra in real time by sending required parameters in API calls. In response, adgebra will send ad details that can be used to serve ads on the Web, Push Notifications, and In-App environment.

Ad elements

1. Request Format:

https://adgebra.co.in/AdServing/PushNativeAds?pid=[Partner_Id]&mkeys=[KEYWORDS]&dcid=9&nads=[Number_of_Ads]&deviceId=[Device_ID]&uid=[Unique_ID]&gaid=[Goodle_Advertiser_ID]&ip=[IP_address]&url=[whitelisted_Domain_mapping_url]&pnToken=[Token_Id]&inApp=[In_App]&slotId=[Slot_ID]&templateId=[Template_ID]&articleTitle=[Article_Title]&articleDescp=[Article_Description]&refUrl=[Refer_URL]&chToken=[Token_Id]&osType=[Operating_System_Type]&osVersion=[Operating_System_Version]&deviceBrand=[Device_BrandName]&deviceModel=[Device_ModelName]

1. Request Parameters:

Parameter	Definition	Mandatory	Description
pid	Partner ID	Yes	It is a unique identifier that adgebra requires. It will be shared by adgebra team at the time of initial setup.
mkeys	Meta Keywords	No	Meta keywords present on the page. Multiple keywords should be sent separating by commas in singleEncodedformat. It is recommended to send meta keywords so that adgebra can respond with most relevant ads.
dcid	Delivery Channel ID	Yes	This is an ad format ID that adgebra requires. For Native, it is 9.
nads*	Number of ads	Yes	Number of ads required to serve in the request. adgebra will accept maximum 8 ads in one request. For any value greater than 8, adgebra will send response with only 8 ads.
deviceId	Device ID	Yes	Desktop – 2 Mobile – 1
uid	Unique ID	Yes	Pass a unique ID of the user. In case of APP, pass GUID/Advertiser ID
ip	IP Address	Yes	LATEST IP address of the user at client end. It helps adgebra to identify from which geo location, the request has come, so that it can serve relevant ads to the user.
url	URL	Yes	Domain from which the request has come. In case of push notification, at least domain URL should be sent. In case of In-App, the app name should be sent.
pnToken	Token (PIN)	Yes	It is an authentication PIN – adgebra will send response only if it is successfully verified. Adgebra will share the password at the time of initial setup.
gaid	Unique ID	Yes	The Google Advertising ID is a user-specific and unique identifier for advertising created by Google Play.
inApp	In-App	No – Web, Notification Yes – In-App	If the request is sent from In-App environment then this flag should be 1. Otherwise it should be 0.
slotId	Slot ID	No	Slot ID of the Ad placement.
templateId	Template ID	No	Template ID
articleTitle	Article Title	No	Article title in single encoded format
articleDescp	Article Description	No	Article description
refUrl	Refer URL	No	Article landing page URL
chToken	Unique Pin	Yes	Unique pin - exactly same value as against pnToken
osType	Operating System	Yes	Operating System type eg : windows,linux,ios,andoid etc
osVersion	Operating System Version	Yes	Operating System Version based on the operating system type
deviceBrand	Device Brand Name	Yes	Device brand name eg : samsung, apple, vivo
deviceModel	Device Model Name	No	Device model name based on brand name eg ; Apple 16 Pro, Samsum s22 ultra

1. Request Example:

https://adgebra.co.in/AdServing/PushNativeAds?pid=123&mkeys=cricket%2Cipl%2Cvirat&dcid=9&nads=3&deviceId=1&uid=9c98c8c8863ce7ef&ip=156.26.55.11&url=xyz.com&pnToken=KGnveR3b2h5H3VdH&gaid=Google_123&slotId=0&templateId=128&osType=android&articleTitle=We%20Get%20Excited%20Not%20Nervous%20Looking%20at%20Lively%20Pitches%3A%20Kohli&articleDescp=WATCH%20%7C%20We%20Get%20Excited%20Not%20Nervous%20Looking%20at%20Lively%20Pitches%3A%20Kohli%20on%20Perth%20Track&refUrl=https%3A%2F%2Fwww.news18.com%2Fcricketnext%2Fvideos%2Fwatch-we-get-excited-looking-at-lively-pitches-rather-than-nervous-virat-kohli-on-perth-track-1972185.html&chToken=KGnveR3b2h5H3VdH

1. Response Format:

[
  {
    "imageUrl": "[Image_Path]",
    "lifeOfAd": "[Validity_of_Ad]",
    "languageId": "[Site_Language_ID]",
    "ctaMessage": "[CTA_Button_NAME]",
    "notificationMessage": "[Description_of_Ad]",
    "trackerUrl": "[Landing_Page_URL]",
    "notificationTitle": "[Short_Text_or_Brand_Name]",
    "icon": "[Short_Text_or_Brand_Name]",
    "notificationImage": "[Ad_Image]",
    "advId": "[Ad_ID]",
    "campId": "[Campaign_ID]",
    "pricingModel": "[Pricing_Model]",
    "currency": "[Current_Format]",
    "price": "[Bid_Price]",
    "brandingLine": "[Brandline]",
    "brandingImageUrl": "[Brand_Image_URL]",
    "clientImpressionTracker": "[Third_Party_Impression_Tracker_URL]",
    "impressionTrackerUrl": "[Impression_Tracker_URL]",
    "landingPageUrl": "[Actual_Landing_Page_URL]",
    "uId": "[UserID]",
    "gaid": "[Google_Advertiser_ID]",
    "size_43_400x300": "[imageurl for the size 400x300]",
    "size_43_200x150": "[imageurl for the size 200x150]",
    "size_43_100x75": "[imageurl for the size 100x75]",
    "size_169_400x225": "[imageurl for the size 400x225]",
    "size_169_200x113": "[imageurl for the size 200x113]",
    "size_169_100x56": "[imageurl for the size 100x56]",
    "size_21_800x400": "[imageurl for the size 800x400]",
    "size_21_400x200": "[imageurl for the size 400x200]",
    "size_21_200x100": "[imageurl for the size 200x100]",
    "size_21_100x50": "[imageurl for the size 100x50]",
    "size_65_600x500": "[imageurl for the size 600x500]",
    "size_65_300x250": "[imageurl for the size 300x250 ]",
    "size_65_100x83": "[imageurl for the size 100x83]",
    "custom_360x240": "[imageurl for the size 360x240]",
    "img990x505": "[imageurl for the size 990x505]",
  }
]

1. Response Parameters

Parameter	Definition	Description
imageUrl	Image URL	The original version of the main image of the ad with dimensions 400x300px. It can be resized and served in any dimension. It is recommended that aspect ratio should not be changed when resizing.
notificationMessage	Notification Message	The description part in the Native ad in single encoded format. It is Mandatory to use for in-App and Push Notification both.
trackerUrl	Tracker URL	On click of ad, user should be redirected to this URL. It is a mandatory parameter. For In-App ads, adgebra will send this URL in single encoded format.
notificationTitle	Notification Title	It is a short text – generally used to mention brand name. It is an optional parameter.
Icon	Icon	It is a small image of 200x200px – generally used as brand logo. It is an optional parameter.
lifeOfAd	Validity of the Ad in minutes	Once the response is sent by adgebra, the ad must be served within this time in minutes.
notificationImage	Notification Image	The compressed version of the main image of the ad with dimensions 360x240px. It can be resized and served in any dimension. It is recommended that aspect ratio should not be changed when resizing.
advId	Advertiser ID	Advertiser ID of which the ad is. This is used for reports & troubleshooting.
campaignId	Campaign ID	Campaign ID of which the ad is. This is used for reports & troubleshooting.
pricingModel	Pricing Model	Pricing Model of the bid price at which adgebra is going to pay. 1 – CPM 2 – CPC
price	Price	Bid Price at which adgebra is going to Pay.
brandingLine	adgebra Branding text	Use it only when branding image URL is not available or cannot be used. (This is an alternative parameter to branding image URL)
brandingImageUrl	adgebra branding image URL
Client Impression Tracker	Third Party Impression Tracker	Additional Impression tracker to be triggered when ad is served if available
impressionTrackerUrl	adgebra impression tracker	To be triggered to notify adgebra about impression being served
osType	Operating System	Operating System type eg : windows,linux,ios,andoid etc
osVersion	Operating System Version	Operating System Version based on the operating system type
deviceBrand	Device Brand Name	Device brand name eg : samsung, apple, vivo
deviceModel	Device Model Name	Device model name based on brand name eg ; Apple 16 Pro, Samsum s22 ultra

1. Response Example:

[
{
"imageUrl": "https://cdn.adgebra.in/images/991_4142_9663/BMW_updated_400x300.jpg",
"notificationMessage": "Own+the+BMW+2GC+at+a+monthly+payment+of+%E2%82%B939%2C300",
"trackerUrl": "https://adgebra.co.in/Tracker/ClickTracker p1=160432&p2=4966&token=91921010700717&p3=&p4=${flag}&slotId=0&templateId=0&pnStatus=1&uid=1421_12345678&pnReferUrl=english.dailyhunt.in&p5=${url}&adg_dummy=1",
"notificationTitle": "BMW+India",
"icon": "https://cdn.adgebra.in/images//991_4142/31781_157791/BMW_Logo.jpg",
"lifeOfAd": "1800",
"notificationImage": "https://cdn.adgebra.in/images/991_4142_9663/BMW_updated_360X240.jpg",
"advId": "4142",
"campId": "32227",
"pricingModel": "1",
"currency": "inr",
"price": "12.0",
"brandingLine": "null",
"brandingImageUrl": "null",
"clientImpressionTracker": "",
"impressionTrackerUrl": "https://adgebra.co.in/AdServing/SPNTracker?bannerId=160432&siteId=4966&dcId=9&deviceId=1&uid=1421_12345678&countryId=1269750&stateId=1264418&cityId=1259229&ipAdrs=203.109.101.177&bidPrice=12.0&apiFlag=1",
"uId": "12345678",
"gaid": "g127j283i42j2344",
"img990x505": "https://cdn.adgebra.in/images/991_4142_9663/990x505.jpg",
"size_43_200x150": "https://cdn.adgebra.in/images/991_4142_9663/BMW_updated_200x150.jpg",
"size_43_100x75": "https://cdn.adgebra.in/images/991_4142_9663/BMW_updated_100x75.jpg",
"size_169_400x225": "https://cdn.adgebra.in/images/991_4142_9663/BMW_updated_400x225.jpg",
"size_169_200x113": "https://cdn.adgebra.in/images/991_4142_9663/BMW_updated_200x113.jpg",
"size_169_100x56": "https://cdn.adgebra.in/images/991_4142_9663/BMW_updated_100x56.jpg",
"size_21_400x200": "https://cdn.adgebra.in/images/991_4142_9663/BMW_updated_400x200.jpg",
"size_21_200x100": "https://cdn.adgebra.in/images/991_4142_9663/BMW_updated_200x100.jpg",
"size_21_100x50": "https://cdn.adgebra.in/images/991_4142_9663/BMW_updated_100x50.jpg",
"size_65_600x500": "https://cdn.adgebra.in/images/991_4142_9663/BMW_updated_600x500.jpg",
"size_65_300x250": "https://cdn.adgebra.in/images/991_4142_9663/BMW_updated_300x250.jpg",
"size_65_100x83": "https://cdn.adgebra.in/images/991_4142_9663/BMW_updated_100x83.jpg"
}
]

Note:

1. At any point in time, if the response is blank or invalid, then it should be handled at the client's end. At times when planned/unplanned adgebra maintenance activity may be scheduled.

2. If no. of available ads is less than requested, then it will send a response for available campaigns, and the remaining elements will be indicated with a message - {"msgCode": "Campaign Not Found"}