The Adhere Ad Server provides two web service APIs:

• Request Ad Web Service
• Track Ad Click Web Service

Request Ad Web Service

Applications and Web Services may use the following API to request an ad from the Adhere Ad Server. The applications call the following URL:
The above URL shows only the mandatory parameters. there are optional parameters that can be used that provide more specific user profile information which can be used by the ad server for targeting ads to specific user profiles.

Mandatory Parameters

• www.yoursite.com, replace with the actual domain name or IP address of the ad server
• accountid, replace ### with the accountid of the operator which is found on the web interface of the ad server under the section Inventory → Operators → <operator name> → Account Configuration
• password, replace xxxx with the password of the operator which is set when creating the operator account, or can be changed under the section Inventory → Operators → <operator name> → Account Configuration
• transactionId, replace hh:mm:ss:### with the current time concatenated with a unique number (e.g. 14:48:13:15903). This number is of no use for the ad server. The ad server includes the transaction id in its response to the incoming request. The application uses the transation id to associate a response from the ad server with the corresponding request.
• messagetype, replace kkk with the message type you wish to retrieve. The messagetype parameter can be any of the following:
  • txt: pure text ad for SMS messages
  • pic: a picture SMS ad optionally followed with a text tag line. The format of the picture SMS ad is discribed below
  • mobwebtext: a web text banner with the associated URL
  • mobwebbanner: a web image banner with the associated URL
  • audioad: a raw audio ad
  • videoad: a raw video ad
  • picturead: a raw picture ad
• language, replace ll with the code for the requested ad language. currently supported languages are English(en) and Arabic(ar)

Optional Parameters
The following URL shows an example request that includes all mandatory and optional parameters:

• age, replace ## with the age of the ad recipient
• gender, replace q with the gender of the ad recipient: m (male), f (female), or u (unkown)
• purchasingpower, replace ## with a number between 1 and 100 that represents the purchasing power of the ad recipient
• keywords, replace ["->mmm->nnn","->ppp","->sss->ttt->uuu", ...] with one or more keywords representing the interests of the recipient. The keywords are represented hierarchically in JSON format. For example: "[->movies","->travel->europe->spain","->cars->suv]". The arrow '->' is a separator between the different levels in the hierarchy.

• location, replace->xxx->yyy->zzzwith the location of the ad recipient. The location is represented hierarchically. For example, ->country->state->city (->usa->california->sunnyvale). The arrow '->' is a separator between the different levels in the hierarchy.
• devicetype, replace ->aaa->bbb->ccc with the device type used by the ad recipient. For example, ->mobile manufacturer->series name ->model number (->nokia->eseries->e71). The arrow '->' is a separator between the different levels in the hierarchy.
• size, replace ## with the maximum ad size (in bytes) accepted by the requesting application. If the ad server fails to find an ad smaller than the specified size, no ad is returned.
• destinationnumber, replace defgh with the mobile phone number of the ad recipient.

Types of Ads
The response from the ad server will vary depending on the requested ad type. If the ad server can not find a matching ad of the specified type it will return an empty string.

The formats of the different ad types are described below:

• txt, raw text in ASCII format if language is English, or Unicode format if language is Arabic. for example:
  
  Text Ad
• pic, a hexadecimally-encoded string that always starts with a zero then the following:
  
  • two digits for the length of the text data
  • text data
  • four characters for the length of the picture data
  • two characters for the width of the the bitmap image
  • two characters for the height of the the bitmap image
  • the actual bitmap data
  010546167206c696e6500fc480e0000019ff1ff180000000003301b019c0000000002200a00c400000000024004004200000000004004004000000000f8400400400000000174400400400000000104400400400000000d8e43843c40db000012f947c47e4124e000392147c47e41249000492147c47e47249000452244c4664d249000a2fd44c466492490
  In the above example:
  • The length of the text data is 10
  • The actual text data is 546167206c696e65. This is English (ASCII text) representing "Tag line". There is no indication whether the text data is English (ASCII) or Arabic (Unicode). If the application specifies the language as English in the request, then the returned ad text must be English, else if the application specifies the language as Arabic in the request, then the returned ad text must be Arabic.
  • The 4 characters 00fc (decimal 252) are the length of the picture data
  • The 2 characters 48 (decimal 72) are the width of the bitmap
  • The 2 characters 0e (decimal 14) are the height of the bitmap
  • The remaining 252 characters are the actual bitmap data. The served image is
  
  The format described above is very similar to the Nokia OTA bitmap format. Both formats are identical starting from the bitmap width field, except that Nokia OTA bitmap format uses a two-character depth field after the bitmap height field and before the actual bitmap data. The bitmap depth field has been omitted in the Adhere bitmap format described above.


• mobwebtext, HTML code containing the text banner. The text is hyperlinked to the specified URL configured in the ad server. For example:
  <a href='http://www.site.com'>Welcome to Site</a>
• mobwebbanner, HTML code containing the web banner and the tag line below the image. The image and the text are hyperlinked to the specified URL configured in the ad server. For example:
  <a href='http://www.site.com'><img src='http://www.yoursite.com/adserver/www/storage/webbanner/122634163769335879930050.jpg' border='0' /></a><br /><a href='http://www.site.com'>Welcome to Site</a>
• audioad, a link to an audio ad file. For example:
  http://www.yoursite.com/adserver/www/storage/audioad/1226341598434507267audioad.amr
• videoad, a link to a video file. For example:
  http://www.yoursite.com/adserver/www/storage/videoad/1226341617915274654videoad.3gp
• picturead, a link to a picture file. For example:
  http://www.yoursite.com/adserver/www/storage/picturead/1226341582689807616picturead.jpg

Track Ad Click Web Service

Applications and web services may use the following web service API to record a click on a served ad.
A description of each parameter is listed below

• adid: replace ### with the unique id of the clicked ad
• operatorid: replace xxxx the id of the operator hosting the ad
• transactionid: replace hh:mm:ss:### with the current time concatenated with a unique number (e.g. 14:48:13:15903). This number is of no use for the ad server. The ad server includes the transaction id in its response to the incoming request. The application uses the transation id to associate a response from the ad server with the corresponding request.