Retrieve Ads
From wiki.taptica.com
Contents |
Communications
The communication will be done using the HTTP protocol.
End Point
Service end point:
POST:
Request
• The request is sent via an HTTP POST to the following URL: http://ad.taptica.com/aff_ad
• The content type of the request is application/x-www-form-urlencoded.
• The body of the POST contains URL encoded key/value pairs separated by "&".
Example: Post to: http://ad.taptica.com/aff_ad
Body: v=w&t=2&a=8a7e5381-f568-4331-a30d-3b01c8f98dec&uid=84cb5500-d2a5-c788-740d-91bcc70f9342&r=320x48&i=50.57.113.223&sr=1280x800&u=Mozilla/5.0 (iPhone; U; CPU iPhone OS 4_0 like Mac OS X; en-us) AppleWebKit/532.9 (KHTML, like Gecko) Version/4.0.5 Mobile/8A293 Safari/6531.22.7
Request parameters
| Parameter | Name In Request | Description | Example | Required? |
| User agent | u | The browser user agent of the device making the request | u= Mozilla/5.0 (Linux;U; Android 2.1-update1;iw-il; HTC LegendBuild/ERE27) | No |
| Application id | a | The id of the applications, as registered in Taptica's AdCore servers. | a=C20DC50B-65B9-4B11-8F62-79F9286896B7 | Yes |
| UDID OR IMEI | uid | The id of the device | uid=dc1816eac806878e8d1d5a8ee9406a3f71407895 | Yes |
| Andoid id | tt_deviceid2 | The Android id of the device | tt_deviceid2=aa54c9b9cad7d37 | Yes |
| IDFA | tt_deviceid3 | The Android id of the device | tt_deviceid3=dc1816eac80686a3f7140789578e8d1d5a8ee940 | Yes |
| Mac Address | tt_deviceid4 | The Android/iOS device mac address | tt_deviceid4=44:2A:60:G5:GE:G5 | Yes |
| IP Address | i | Client IP Address | i=84.103.57.1 | Yes |
| Localization | loc | The localization (Language & Country) that is currently chosen for the device ,following the standards of ISO 639-1,ISO 3166-1. | loc=en_GB | No |
| Network type | nt | The type of network the device is currently connected to ("wifi" or "carrier") | nt=carrier | No, |
| Marital status | marital | Marital status of the user. options are: "single", "divorced", "engaged", "relationship", or "swinger" | marital=single | No |
| Income | income | Annual income (in USD) , e.g. 10000. | income=10000 | No |
| Interests | interests | a comma separated list of keywords denoting user's area of interests. | interests=cars,sports,F1,stocks | No |
| Education | edu | Education level of the user ("UG" or "PG") | edu=UG | No |
| Resolution | r | Resolution of the ad request | r=320x50 | Yes |
| Ad Type | t | Ad type - Text (1), Banner (2), Html (3), All (0) | t=2 | Yes |
| Gender | gender | Gender, Male, Female, All | gender=male | No |
| Age | age | Age of the user | age=27 | No |
| Date Of Birth | dob | User's Date of birth(Format: yyyyMMdd) | dob=19820211 | No |
| Latitude | lat | Location by latitudes lines | lat=40.714353 | No |
| Longitude | lon | Location by longitude lines | lon=-74.005973 | No |
| Response Type | rt | JSON=0, XML=1, XHTML=2, types of response | rt=0 | No |
Response
The data is returned in a JSON format.
• The JSON returned by Taptica AdCore servers is a single object, composed of simple fields of JSON Type String, described in the section below.
Example:
{"adyxAdRequestGuid":"c1059ef9-424c-4785-8350-cd86a8b71d1e",
"adType":"banner",
"imageUrl":"http://ad.taptica.com/bMO_Banner_320x50.png...",
"impUrl":"http://ad.taptica.com/aff_b...",
"imageAltText":null,
"adUrl":"http://tracking.taptica.com/aff_ic?tt_cid=c1059ef9424c47858350cd86a8b71d1e&el=GbtixRMFpArEVHfprXTgVAQ3WW...",
"urlType":"web",
"beacon":null,
"adInterval":"10"}
* Note: Not in use for API (urlType, beacon, adInterval)
• The response type can be either: Textual ad, Graphical Ad or an Error Message.
The JSON of each response type is described below.
Textual Ads
| Parameter | Description | Example |
| adyxAdRequestGuid | Unique identifier of an ad request | "{21EC2020-3AEA-1069-A2DD-08002B30309D}" |
| adType | The type of an ad. Must have the value "text" | "text" |
| adText | The text to be displayed on the ad | "Click here! The best offer you can ever get" |
| adUrl | A URL to which the user should be redirected upon clicking on the ad | "http://www.taptica.com" |
Graphical Ads
| Parameter | Description | Example |
| adyxAdRequestGuid | Unique identifier of an ad request | "{21EC2020-3AEA-1069-A2DD-08002B30309D}" |
| adType | The type of an ad. Must have the value "banner" | "banner" |
| imageURL | A URL from which the graphical ad image should be retrieved | "http://ad.taptica.com/images/file1.jpg" |
| impURL | A URL from which the impression should be sent to the server | "http://ad.taptica.com/aff_i..." |
| adUrl | A URL to which the user should be redirected upon clicking on the ad | "http://ad.taptica.com/..." |
Html Ads
| Parameter | Description | Example |
| AdRequestGuid | Unique identifier of an ad request | "{21EC2020-3AEA-1069-A2DD-08002B30309D}" |
| adType | The type of an ad. Must have the value "html" | "html" |
| adUrl | A URL to which the user should be redirected to (usually Html Page) | "http://www.taptica.com" |
Error Message
| Parameter | Description | Example |
| errorId | The identifier of the error that occurred. If needed, extra text describing the error will be written into the errorText. | "5" |
| errorText | Contains additional information regarding the retrieved error. | "The error had happened due to the following unexpected reason: unsupported client" |
List of errors
| errorID | Description |
| -1 | Unknown error. In this case, the errorText parameter will include the information that describes the error. |
| 0 | Server overload |
| 1 | Server could not find an appropriate ad (because of age restriction , for example) |
| 2 | Application id is missing |
| 3 | Application id wasn't found on database |
| 4 | User agent is missing |
| 5 | User agent is not supported |
| 6 | Test mode value is not supported |
| 7 | Resolution size and/or density are not supported |
| 8 | Resolution size and/or density are in the wrong format |
| 9 | Postal code is in wrong format |
| 10 | Area code is in wrong format |
| 11 | Location is in wrong format |
| 12 | Birth date is in wrong format or is invalid |
| 13 | Gender is in wrong format |
| 14 | Unique Identifier is missing |
| 15 | Unique Identifier value is in wrong format or is invalid |
| 16 | Localization is missing |
| 17 | Localization value is in wrong format or is invalid |
| 18 | Net type value is in wrong format or is invalid |
| 19 | Marital status value is not supported |
| 20 | Income value is in wrong format or is invalid |
