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 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"}]}