This document aims at providing developers with instructions and guidance on how to access AdFalcon API from within their Mobile Websites.
Ad Request Parameters
There are a collection of parameters that are mandatory in all ad requests. If you do not fill the required parameters in a correct way, AdFalcon network will not be able to respond back with an appropriate ad.
For Mobile Web Sites, the mandatory parameters are:
· Site ID (R_SID)
A string conataining a unique site ID of your application or web site.
The optional parameters are extra information related to the user and device which helps AdFalcon’s ads selector engine to get the most relevant ads for the user.
· Test Mode (R_TM)
A boolean intended to inform AdFalcon network about application or web is under the development or maintenance mode. Ex. R_TM: true
Note: Ensure Test Mode Parameter is set to false before releasing your application to the public.
· Ad Unit Size (R_AS)
An integer identifies the ad unit size to be delivered by AdFalcon.
Below are the supported sizes:
|Interstitial_320x480||11||Smartphones Interstitial. Returns Ad with one of the following unit sizes:
· 320 x 480 if the device is portrait
· 480 x 320 if the device is landscape
· Or 300 x 250
|Interstitial_768x1024||12||Tablet Interstitial. Returns Ad with one of the following unit sizes:
· 768 x 1024 if the device is portrait
· 1024 x 768 if the device is landscape
· 600 x 1024 if the device is android with smaller screen and is portrait
· 1024 x 600 if the device is android with smaller screen and is landscape
· Or 500 x 480
|Interstitial_Auto||13||Used in case of universal apps where it will automatically fall back to Interstitial_320x480 when the device is a smartphone or Interstitial_1024x768 when the device is tablet.|
Note: If this Ad Unit Size parameter is not specified, AdFalcon server will choose the best ad size that is suitable for the device’s screen resolution.
· User ID (R_UUID)
A string used to get the unique ID for the user. You can get this value in two ways:
- If you have your own unique ID for each user you can always pass this ID.
- If you do not have a unique ID for each user then you can do the following:
A – Send the first ad request without R_UUID and D_UDID parameters.
B – When AdFalcon receives the request without a unique ID, the system will generate a new unique user id and send it back as follows:
- Set the HTTP header “X-ADFALCON-UUID”
- Set a persistent cookie
- Set UUID field in JSON responses.
C – Get the generated user unique id from X-ADFALCON-UUID HTTP header or from the UUID JSON field.
D – Thereafter, pass the user unique id in the R_UUID in all ad requests that are submitted on behalf of the same user.
· Language (U_LN)
A two chars containing the language of the requested ad in ISO 639-1 language codes format (Two Letters code); for arabic language, pass ar code for language parameter U_LN: ar.
· Age or birthdate (U_AGE or U_BD)
You can add one of these two parameters to determine the age of the user. In the case you pass a birthdate you must send it in the dd.MM.yyyy format
· Gender (U_G)
A char containing the gender of the user
The possible values are:
· Keywords (U_KW)
A string is used to list a collection of keywords in comma separated format. These keywords can be useful since AdFalcon’s ads selector engine will search for ads containing these keywords.
· Country Code (U_CC)
A string containing county code of the end user in ISO 3166-1 alpha-2 format code (two-letter code).
· Area Code (U_AC)
A string containing the user’s area code.
· Postal Code (U_PC)
A string containing the user’s postal/ZIP code.
· Geolocation (D_LA, D_LO)
A double containing the geolocation information of the device. The location information is divided into two values; latitude (D_LA) and longitude (D_LO). Ex. D_LA: 35.54454548, D_LO: 58.981