Microsoft Invest - Mobile ad call reference
Note
Microsoft Advertising now supports a domain, adnxs-simple.com, which does not send or read browser cookies on requests. Clients can leverage this cookie-free domain when there is no consent to use personal data. Relevant calls initiated by Microsoft Advertising will automatically use this domain when there is no consent or when cookies are not required for the function. For more information, see Part of Service Policies
This document describes our mobile ad calls, the /ssmob and /mob calls, which are used to request ads for mobile apps. These calls include information about the client device as query string parameters.
For definitions of all the supported parameters, see Query string parameters below. For examples of real mobile ad calls, see the Examples.
Note that the /ssmob and /mob calls described on this page are for mobile app traffic only.
Since this ad call is for mobile app inventory, attempts to pass web site domains, including via the deprecated referrer parameter, will be ignored. This also means that the site_domain field in Reporting Guide will be set to blank, since it is not needed for app traffic.
Important
Mobile Tag Format Generation
The mobile ad call tag format is not generated by our platform. You will need to export placement tags and then modify them.
If you have set up a CNAME record for ad serving, we recommend using a separate CNAME for mediated ad requests on /ssmob calls that points to mediation.adnxs.com. We do not recommend using a custom CNAME for /mob calls.
Tip
Valid Carrier Codes for running Debug Auctions
Trying to run a debug auction on mobile? You'll need to spoof the carrier parameter. For a list of valid carrier codes, see Mobile Carrier Codes.
Query string parameters
The mobile ad call accepts the query string parameters shown below. For examples of mobile ad call requests, see the examples at the bottom of the page.
Important
Device ID fields are case sensitive.
Note
Several of these parameters need to be URL encoded.
| Parameter | Type | Required? | Description |
|---|---|---|---|
id |
int | Yes | The unique ID of the placement where the ad will serve. If you'd rather not pass the raw placement ID, you can pass in a combination of member and inv_code parameters. For more information, see the documentation for those parameters. |
member |
int | No | (Optional) The member ID of the member on whose placement the ad will serve. Instead of passing the placement ID, you can pass a combination of this field and inv_code to uniquely identify a specific placement. |
inv_code |
string | No | (Optional) A user-supplied "code" (arbitrary string) that identifies a particular placement. Instead of passing the placement ID, you can pass a combination of this field and member to uniquely identify a specific placement. |
appid |
string | No (but strongly recommended; see description) | This string is used to identify a mobile app running on Android or iOS devices. - On Android, this is the app's package name. It's formatted as follows: com.example.helloworld.- On iOS, this is the app's iTunes ID. It's formatted as follows: 123456789.Many buyers set targeting and reporting based on appid. Failing to supply a correct appid will make your inventory unattractive to these buyers. Therefore, passing this field is strongly recommended when supply_type is set to "mobile_app". Note that this is what our Mobile SDKs do when they request an ad. (See the below to see how our SDK passes the appid.)To find the app ID for a particular Android or IOS app, find the app's detail page ? the easiest way is to do a web search. The URL of the app store's detail page will show the app's ID (highlighted here in red for visibility). For example, here are the detail pages for the "Fussball" app: - Google Play: https://play.google.com/store/apps/details?id=de.telekom.FUSSBALL.DE - iTunes: https://itunes.apple.com/de/app/fussball.de/id422052549 |
carrier |
string | No | Name of the mobile carrier. This is optional because our system can usually deduce the carrier from the device's IP address. |
connection_type |
string | No | The type of network used by the device. Allowed values are "wifi" or "wan". |
devmake |
string | No | Manufacturer of the device requesting an ad. |
devmodel |
string | No | Model of the device requesting an ad. |
LimitAdTrackingEnabled |
boolean | No | If true, the user has set the system-level preference to not receive behaviorally targeted ads. Allowed values: true, false, 1, or 0.Tip: For more information about the system-level ads preferences on iOS, see Opt out of interest-based ads from iAd. For more information about the system-level ads preferences on Android, see Advertising ID. |
dnt |
boolean | No | Note: This field is deprecated, and may be removed in the future. Use the LimitAdTrackingEnabled flag instead.If true, the user has set the system-level preference to not receive behaviorally targeted ads. Allowed values: true, false, 1, or 0. |
devtime |
int | No | The time on the device, measured in seconds since the epoch, or UNIX Time. |
devtz |
string | No | The device's timezone. |
md5udid |
string | No | The MD5 hash of the ANDROID_ID. This should only be sent for Android devices. This should be URL encoded. |
sha1udid |
string | No | The SHA1 hash of the ANDROID_ID. This should only be sent for Android devices. This should be URL encoded.. |
idfa |
string | No | The Apple advertising identifier for iOS devices running iOS 6+. |
aaid |
string | No | The Google advertising identifier for Android devices as retrieved from Google Play services. |
ip |
string | Yes, on /ssmob calls |
IP address of the device making the ad request, e.g., 207.237.150.246.- If not specified for /mob calls, the IP passed via HTTP headers will be used for geo detection instead.- If not specified for /ssmob calls, Microsoft Advertising will not be able to detect geo location, and buyers will therefore not be able to target by geo. |
istest |
boolean | No | Whether this is a test request. Allowed values: true or false, 1 or 0. |
language |
string | No | The device's language, specified with an ISO Language Code. |
loc |
string | No | The user's location expressed in latitude and longitude, in the format: snnn.ddddddddddddd, snnn.ddddddddddddd. Up to 13 decimal places of precision are allowed. |
loc_age |
int | No | Age of the location data in milliseconds. |
loc_prec |
int | No | Precision of the location data in meters. |
max_size |
string | No | The maximum banner size allowed, e.g., "320x250". N/A for Interstitial ads. |
mcc |
int | No | The Mobile Country Code as specified by the ITU. |
mnc |
int | No | The Mobile Network Code as specified by the ITU. |
openudid |
string | No | The OpenUDID of the device. This should only be sent for iOS versions 5 and below. |
orientation |
string | No | Device screen orientation during the ad request. Allowed values are "v" or "h". |
os |
string | No | The operating system of the device. For example, Android 4.0.2. For mobile apps, this is usually provided by the user agent. |
pcode |
string | No | The postal code of the user requesting an ad. If not specified, postal code will be determined from the IP address. |
psa |
boolean | No | If true, PSAs will serve if the auction has no winner. Otherwise, an empty 200 OK HTTP response will be returned. Allowed values: true or false, 1 or 0. |
sha1mac |
string | No | sha1mac was deprecated as of May 7th, 2019. Do not use. |
st |
string | No | The supply type of the inventory, which indicates the environment in which an ad will be shown. Allowed values: "mobile_app", "mobile_web", or "web". Defaults to "mobile_app". |
size |
string | No | The requested banner size, e.g., "320x50", or the screen size for Interstitial ads. |
tmpl_id |
int | No | The supply template identifier. |
ua |
string | No | The user agent string associated with the device requesting an ad. If specified, this value will be used rather than the standard user agent sent via HTTP header. This should be URL encoded. |
Examples
Most of the examples in this section are based on real ad calls made by our Mobile SDK. You should be able to try these out yourself.
The requests differ from those made by the SDK as follows:
- We ask for the ad in varying formats; JavaScript (the default), JSON, and HTML.
- We use the
curlcommand line tool to request the ad from the server; for more information aboutcurl, see the project website at https://curl.haxx.se/.
Note
The id parameter in these examples refers to the Microsoft Advertising placement ID. You will need to replace it with one provided to you by the Microsoft Advertising platform member you're working with.
JavaScript
Important
If no response format is specified, the response will be JavaScript by default.
curl "https://mobile.adnxs.com/mob?id=1281482&idfa=610B91D7-8F0D-423A-A98E-333DC41D04A2&devmake=Apple&devmodel=x86_64&appid=ANX.FunWithBeingMediatedByMoPub&ua=Mozilla%2F5.0%20%28iPhone%3B%20CPU%20iPhone%20OS%207_0_3%20like%20Mac%20OS%20X%29%20AppleWebKit%2F537.51.1%20%28KHTML%2C%20like%20Gecko%29%20Mobile%2F11B508&orientation=v&connection_type=wifi&devtime=1389725718&language=en&native_browser=0&psa=1&st=mobile_app&sdkver=1.7&size=320x50" document.write('<a href="https://nym1.mobile.adnxs.com/click?_Knx0k1iUD_8qfHSTWJQPwAAAAAAAPA__Knx0k1iUD_8qfHSTWJQP6DymlWmmrZKp-qJIdPe_STeGiJTAAAAAMqNEwC-AwAAvgMAAAIAAADtN2oAPsYCAAYAAQBVU0QAVVNEAEABMgARIAAAS7AAAgMCAQIAAAAADSiQdwAAAAA./cnd=%21LAZnOQjmx04Q7e-oAxi-jAsgBA../referrer=https%3A%2F%2Fapps.mobile.adnxs.com/clickenc=https%3A%2F%2Faww.reddit.com" target="_blank"><img width="320" height="50" style="border-style: none" src="https://placekitten.com/g/320/50"/></a>');
JSON
Important
In order to receive a JSON response, you must add &format=json to the query string of your request.
Banner
curl "https://mobile.adnxs.com/mob?id=1281482&idfa=610B91D7-8F0D-423A-A98E-333DC41D04A2&devmake=Apple&devmodel=x86_64&appid=ANX.FunWithBeingMediatedByMoPub&ua=Mozilla%2F5.0%20%28iPhone%3B%20CPU%20iPhone%20OS%207_0_3%20like%20Mac%20OS%20X%29%20AppleWebKit%2F537.51.1%20%28KHTML%2C%20like%20Gecko%29%20Mobile%2F11B508&orientation=v&connection_type=wifi&devtime=1389725718&language=en&native_browser=0&psa=1&format=json&st=mobile_app&sdkver=1.7&size=320x50" { "status": "ok", "ads": [{"type":"banner", "width":320, "height":50, "content": "<script type=\"text/javascript\">document.write('<a href=\"https://nym1.mobile.adnxs.com/click?_Knx0k1iUD_8qfHSTWJQPwAAAAAAAPA__Knx0k1iUD_8qfHSTWJQP-ciduUWOCtUp-qJIdPe_SR4FSJTAAAAAMqNEwC-AwAAvgMAAAIAAADtN2oAPsYCAAYAAQBVU0QAVVNEAEABMgARIAAA4pUABQMCAQIAAAAAkSZ64AAAAAA./cnd=%21LAZnOQjmx04Q7e-oAxi-jAsgBA../referrer=https%3A%2F%2Fapps.mobile.adnxs.com/clickenc=https%3A%2F%2Faww.reddit.com\" target=\"_blank\"><img width=\"320\" height=\"50\" style=\"border-style: none\" src=\"https://placekitten.com/g/320/50\"/></a>');</script>"}] }
Interstitial
curl 'https://mobile.adnxs.com/mob?id=1281482&md5udid=8747a995943822f78754d20587f7b4f7&sha1udid=028df4e36437e98f9e93c3ae0f9f99e512a28cee&devmake=motorola&devmodel=DROID%20X2&carrier=Verizon%20Wireless&appid=com.example.helloworldinterstitial&ua=Mozilla%2F5.0%20(Linux%3B%20U%3B%20Android%202.3.5%3B%20en-us%3B%20DROID%20X2%20Build%2F4.5.1A-DTN-200-18)%20AppleWebKit%2F533.1%20(KHTML%2C%20like%20Gecko)%20Version%2F4.0%20Mobile%20Safari%2F533.1&orientation=v&size=360x640&promo_sizes=300x250,320x480&language=en&devtime=1396901116263&connection_type=wan&native_browser=0&psa=1&format=json&st=mobile_app&sdkver=1.14' { "ads": [ { "content": "<script type="text/javascript">document.write('<a href="https://nym1.mobile.adnxs.com/click?_Knx0k1iUD_8qfHSTWJQPwAAAAAAAPA__Knx0k1iUD_8qfHSTWJQP833ijTfLRsp7_epnuN8OQDtBENTAAAAAMqNEwC-AwAAvgMAAAIAAABRoWAAPsYCAAYAAQBVU0QAVVNEACwB-gARIAAAA6YABQMCAQIAAAAAGScpIgAAAAA./cnd=%21vQWKNQjmx04Q0cKCAxi-jAsgBA../referrer=https%3A%2F%2Fapps.mobile.adnxs.com/clickenc=https%3A%2F%2Faww.reddit.com" target="_blank"><img width="300" height="250" style="border-style: none" src="https://placekitten.com/300/250"/></a>');</script>", "height": 250, "width": 300, "type": "interstitial" } ], "status": "ok" }
No ad returned
curl "https://mobile.adnxs.com/mob?id=656561&size=320x480&devmake=Motorola&devmodel=Droid&pcode=12561&LimitAdTrackingEnabled=false&appid=com.example.hello_world&format=json"
Note
No JSON response is returned if no ad is returned.
Error message
curl "https://mobile.adnxs.com/mob?id=656561&size=320x480&devmake=Motorola&devmodel=Droid&pcode=12561&LimitAdTrackingEnabled=false&appid=com.example.hello_world&format=json&FOO=BAR" { "status": "error", "errorMessage": "invalid input parameter: FOO" }
HTML
Important
In order to receive an HTML response, you must add &format=html to the query string of your request.
curl "https://mobile.adnxs.com/mob?id=1281482&idfa=610B91D7-8F0D-423A-A98E-333DC41D04A2&devmake=Apple&devmodel=x86_64&appid=ANX.FunWithBeingMediatedByMoPub&ua=Mozilla%2F5.0%20%28iPhone%3B%20CPU%20iPhone%20OS%207_0_3%20like%20Mac%20OS%20X%29%20AppleWebKit%2F537.51.1%20%28KHTML%2C%20like%20Gecko%29%20Mobile%2F11B508&orientation=v&connection_type=wifi&devtime=1389725718&language=en&native_browser=0&psa=1&format=html&st=mobile_app&sdkver=1.7&size=320x50" <script type="text/javascript">document.write('<a href="https://nym1.mobile.adnxs.com/click?_Knx0k1iUD_8qfHSTWJQPwAAAAAAAPA__Knx0k1iUD_8qfHSTWJQP1bxcdIRjzU7p-qJIdPe_STAFyJTAAAAAMqNEwC-AwAAvgMAAAIAAADtN2oAPsYCAAYAAQBVU0QAVVNEAEABMgARIAAAQq8AAQMCAQIAAAAAuibhDAAAAAA./cnd=%21LAZnOQjmx04Q7e-oAxi-jAsgBA../referrer=https%3A%2F%2Fapps.mobile.adnxs.com/clickenc=https%3A%2F%2Faww.reddit.com" target="_blank"><img width="320" height="50" style="border-style: none" src="https://placekitten.com/g/320/50"/></a>');</script>
Native ads
Note
Native ads are not available from the /ssmob endpoint.
Empty response
curl 'https://mobile.adnxs.com/mob?id=4448024' {"status":"no_bid","version":1}
Response with native ads
Tip
The "native" array in this response contains a set of native ad objects. For more information about native creatives, see the Creative Service.
Things to note about the native ad response include:
Possible values of the
typefield are"in-feed-standard"and"recommendation-widget."The web page/app is required to ping the
impression_trackersonly when the native ad is displayed.The web page/app is required to ping the
click_trackerswhen a click is detected.$ curl 'https://mobile.adnxs.com/mob?id=4469257' {"status":"ok","version":1,"ads":[],"mediated":[], "native": [{"type":"in-feed-standard","title":"Disqus rocks","description":"Let us disqus!", "fulltext":"Disqus rocks really long text","iconimgurl":"https://dummyimage.com/100x100?text=ICON", "mainmedia":[{"label":"default","width":800,"height":500,"url":"https://dummyimage.com/800x500?text=MAINIMAGE"}],"cta":"download", "clicktrackers": ["https://secure-nym.adnxs.com/click?AAAAAAAA8D8AAAAAAADwPwAAAAAAAPAAAAAAAAA8D8AAAAAAADw PzmS3KNRni9xPwJNJXfgutNwtVAAAAAAkyRAC-AwAAvgMAAAIAAACs95cBFPAGAAYAAQBVU0QAVVNEAAEAAQARIAAALe8BAgMAAQIAAAAAQBir5QAAAAA. /cnd=%21fwYfPAiWscsDEKzv3wwYlOAbIAQ./", "https://dummyimage.com/1x1?text=CLICK-TRACKER","https://dummyimage.com/1x1?text=CLICK-TRACKER2"], "impressiontrackers": ["https://secure-nym.adnxs.com/it?e=wqT3QLXA8DOAQAAAgDWAAUIre-sqAUQuaTynprK55dxGPnw6e i-pWCyABKi0JAAAAAAAA8D8RBQgMAPAGREJACERCQApEQmoMInkkAI4vgdAvgdIAlCs798MWJTgG2AGaJFAcAB4rd4DgAEBigEDVVNEkgUG8FCYAQGgAQGoAQGwAQC4AQLAAQPIAQ DQAQDYAQDgAQDwAQCKAjp1ZignYScsIDQxNjA3MywgMTQyNjc5ODUwOSk7dWYoJ3InLCAyNjczNjU1NiwyHgDwbJICnQEhUlI2Nkd3aVdzY3NERUt6djN3d1lBQ0NVNEJzd0FEZ0F RQVJJdmdkUWllU1FBbGdBWVBjRGFBQndBSGdBZ0FFQWlBRUFrQUVCbUFFQm9BRUJxQUVEc0FFQXVRRUFBQUFBQUFEd1A4RUIJDExBQThEX0pBZFlYNHB5SDFRQkEyUR0oGC1BQkFQ VUIJLCwuLpoCHSFmd1lmUEE2oADsbE9BYklBUS7YAugh3ALH0wGAAwCIAwGQAwCYAxagAwGqAwCwAwC4AwDAA6wCyAMA2AMA4AMB6AMC8AMB&dlo=1", "https://dummyimage.com/1x1?text=IMP-TRACKER","https://dummyimage.com/1x1?text=IMP-TRACKER2"], "click_url":"https://disqus.com"}]}