Microsoft Monetize - Mobile ad call reference

Article
02/13/2024

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 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

Note that device ID fields are case sensitive.

Note

Several of these parameters need to be URL encoded.

Parameter	Type	Required?	Description
aaid	string	No	The Google advertising identifier for Android devices as retrieved from Google Play services.
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.
devtime	int	No	The time on the device, measured in seconds since the epoch, or UNIX Time.
devtz	string	No	The device's timezone.
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`.
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.
idfa	string	No	The Apple advertising identifier for iOS devices running iOS 6+.
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.
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.
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.
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.
md5udid	string	No	The MD5 hash of the `ANDROID_ID`. This should only be sent for Android devices. This should be URL encoded.
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.
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.
sha1udid	string	No	The SHA1 hash of the `ANDROID_ID`. This should only be sent for Android devices. This should be URL encoded..
size	string	No	The requested banner size, e.g., `"320x50"`, or the screen size for Interstitial ads.
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"`.
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 curl command line tool to request the ad from the server; for more information about curl, 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.

$ 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 type field are "in-feed-standard" and "recommendation-widget."
The web page/app is required to ping the impression_trackers only when the native ad is displayed.

The web page/app is required to ping the click_trackers when 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"}]}

Share via

Microsoft Monetize - Mobile ad call reference

Query string parameters

Examples

JavaScript

JSON

Banner

Interstitial

No ad returned

Error message

HTML

Native Ads

Empty response

Response with Native Ads

Additional resources

Share via

Microsoft Monetize - Mobile ad call reference

Query string parameters

Examples

JavaScript

JSON

Banner

Interstitial

No ad returned

Error message

HTML

Native Ads

Empty response

Response with Native Ads

Related topics

Additional resources