Server-to-Server Mediation (API Spec)

The MoPub Server-to-Server API makes it easier for ad networks and demand partners to connect with the MoPub platform outside of SDK libraries. To integrate with MoPub through the Server-to-Server API, follow the integration approval process and technical specifications.

Integration Process

  1. Please read through all of articles that appear in the left sidebar of our Demand Help Center. Most of these concept apply to server-side mediation partners.
  2. Video Support Section
    • This section includes information about video support and best practices. Please read through all three documents.
  3. Reference SDK Changelogs to verify functionality of all ad formats in each SDK version:
  4. Build to our API Specifications
  5. Test your creatives end-to-end in the MoPub Sample App.

Completion of the integration does not guarantee approval or immediate testing on the MoPub side. There can be a delay as the technical team works through the queue of integration requests. Integration of the Network Reporting API is required for testing.

Ad Request Specifications

  • The ad request from MoPub to the integrated platform will be in a JSON Format and sent in the specification outlined in the link above.
  • The ad request will be sent to a predetermined endpoint URL which the integration candidate needs to provide to Mopub. This should be a new endpoint if you are currently integrated with MoPub. Changes to the URL will require 45 days advanced notice by the integrated platform to MoPub.
  • iTunes Store ID and Google Package Name are passed in the bundle ID field not App ID
  • Only the site or app object will be included, not both
  • App ID must be unique per platform and app
  • Tag ID:
    • Must be unique per ad size (not ad format), platform, and app
    • Publisher customers should have the ability to generate more than one ID per ad size.
  • Native ads are not supported through server-to-server integrations.
  • IMPORTANT: All fields will be populated in the request if available. We will never pass null values or empty strings. If noted as “not always passed,” that parameter may not always be present in the request. For example, if the request doesn’t contain an SDK version, we will omit “ver” from the request.
  • It’s possible that an attribute is marked as not always passed when there is very low probability of this happening. E.g., country is passed >99% of the time.
  • _ Adomain: _ Must match the top level domain for the advertiser landing page and must be passed with only .com or .countrycode appended (e.g., domain.com or domain.ie).In the case of app store destinations, the adomain should represent the app’s equivalent URL and not the full app store URL (e.g., for Candy Crush Saga, the adomain should be “candycrushsaga.com” and not “king.com”). In the case of apps that do not have a registered domain, please use [app name].com (e.g., mopubapp.com).

GDPR

For more information about GDPR, see our FAQ

User.ext.gdpr

Signals whether or not the request is subject to GDPR regulations. It will do so via the extension attribute “gdpr” which is an integer that indicates: 0 = No, 1 = Yes. The extension is an object.

User.ext.consent

The extension attribute “consent” will convey user consent when GDPR regulations are in effect. This string will pass “1” indicating the user has provided consent or “0” indicating that the user has not consented. The extension is an object.

If we do not have consent, we will not be collecting the following fields. Additionally, all of these fields except IFA will be omitted from the request. IFA will be present, however it will contain zeroes.

  • Advertising ID
  • Lat/Long
  • Age
  • Gender
  • Interest and demographic keywords
  • IP address: we will truncate the 8 lowest bits
  • city
  • metro
  • region
  • zipcode

Video Support

  • Publishers cannot control the min/max values that are passed in the request. Network partners must discuss video preferences with their customers prior to serving video.
  • Video support applies to VAST video
  • Review the following:
  • Video specific fields are also included in the MoPub ad request specifications that are hosted on this page

Ad Response Specifications

Link to Ad Response Specifications

  • Your ad response must be in a JSON Format.
  • All fields except the “video” field and “price” are REQUIRED.
    • You are not required to pass the ad “price” (in CPC/CPM) or the price you are valuing the ad impression as. However, it is recommended you pass this value to help optimize performance for publishers.
  • The impression tracking URL must be passed in the nurl field. MoPub will call this URL from the user’s device when the ad renders.
  • The “crid” field uniquely identifies an ad creative. As such for the same creative, it should have the same value.
  • The “crtype” attribute contains information on the type of creative which the ad network is serving. It’s value could be one of the following: [{“VAST 2.0”, “MRAID 1.0”, “MRAID 2.0”, “Image Ad”, “HTML5”, “JS”}].
  • iFrames are not supported.
  • If there is no matching ad or if the ad network does not want to send back any response, simply return with HTTP 204 Response.
  • The Ad Network needs to respond in less than 250ms or the request will time out.

Sample JS Response

    {
       "id":"fcc3ce49-6abd-473a-818e-0645bda6033a",
       "seatbid":[
          {
             "bid":[
                {
                   "adm":"<INSERT MARKUP>",
                   "adomain":[
                      "domain.com"
                   ],
                   "crid":"111491",
                   "crtype":"JS",
                   "impid":"1",
                   "iurl":"http://adserver.com/pathtosampleimage.jpg",
                   "nurl":"http://adserver.com",
                   "price":3               //optional
                }
             ]
          }
       ]
    }

Sample Video Response:

    {
       "id":"663dda9a-1689-4f6f-9484-7e443540f45e",
       "seatbid":[
          {
             "bid":[
                {
                   "adm":"<<INSERT VAST MARKUP>>",
                   "adomain":[
                      "domain.com"
                   ],
                   "attr":[
                      6
                   ],
                   "crid":"111491",
                   "crtype":"VAST 2.0",
                   "ext":{
                      "video":{
                         "duration":16,
                         "linearity":1,
                         "type":"VAST 2.0"
                      }
                   },
                   "impid":"1",
                   "iurl":"http://adserver.com/pathtosampleimage.jpg",
                   "nurl":"http://adserver.com",
                   "price":10               //optional
                }
             ]
          }
       ]
    }

iTunes Category to IAB Category Mapping

Inventory in MoPub is categorized with a primary and secondary iTunes category. These category values are passed to buyers directly in the “cat” array in either the app or site object. The iTunes Categories are also used to statically map to IAB Tier I categories in each case and in some cases the Tier II category. The resulting array will contain the primary and secondary iTunes category as well as the IAB categories that are derived from both.

As an example, if an app is classified as “Travel” and “Weather,” the resulting “cat” array would be: [“travel”, “weather”, “IAB20”, “IAB15”, “IAB15-10”]. IAB20 is the single category map from Travel and IAB15 and IAB15-10 are the dual maps from Weather.

Note: For a complete list of possible IAB content categories, please refer to the IAB OpenRTB Spec – Table 6.1.

iTunes Category IAB Tier I Category IAB Tier II Category
Books IAB1 Arts & Entertainment IAB1-1 Books & Literature
Business IAB3 Business  
Education IAB5 Education  
Entertainment IAB1 Arts & Entertainment  
Finance IAB13 Personal Finance  
Games IAB9 Hobbies & Interests IAB9-30 Video & Computer Games
Healthcare and Fitness IAB7 Health & Fitness  
Lifestyle IAB14 Society Audio Ad (Auto Play)
Medical IAB7 Health & Fitness)  
Music IAB1 Arts & Entertainment IAB1-6 Music
Navigation IAB20 Travel  
News IAB12 News  
Photography IAB9 Hobbies & Interests IAB9-23 Photography
Productivity IAB3 Business  
Reference IAB24 Uncategorized  
Social Networking IAB24 Uncategorized  
Sports IAB17 Sports  
Travel IAB20 Travel  
Utilities IAB3 Business  
Weather IAB15 Science IAB15-10 Weather

Default Blocked Categories

IAB Value Category
IAB25 Non-Standard Content
IAB26 Illegal Content
IAB7-39 Sexuality
IAB8-5 Cocktails/Beer
IAB8-18 Wine
IAB9-9 Cigars

Win Notification URL

We exclusively use the “nURL” parameter for win notifications. For each response, the “nURL” attribute contains the win notice URL. The client calls this notice URL to inform the partner of the win. nURL will fire when all assets in the ad markup are successfully retrieved and the webview (actual ad slot) becomes visible to the user. At this point in time, MoPub does not support encoding substitution macros through the server-to-server connection.

  • MoPub has created a formalized server-to-server program and unified spec for all of our network partners. If performance issues arise, we ask that our partners troubleshoot and analyze why there may be issues on their end.To help our partners investigate issues, we created a Troubleshooting Guideline to follow. Please see steps outlined below:
    1. Review the SDK Changelogs to verify functionality of all ad formats in each SDK version. * Android Changelog * iOS Changelog * We highly recommend that networks report off of the MoPub SDK version to isolate where creatives may be breaking
    2. Isolate poor performing creatives and test them on the MoPub Sample App
    3. Compare ad server metadata from the server-to-server integration and SDK integration and see if any data is missing.
      • For example, are you properly ingesting location data?
      • Investigate which metrics are not performing when compared to an SDK integration (CTR, conversions, etc..).
        • What are the differences?
        • If there are click issues, please test the creatives (see step #2)
    4. Have one publisher test both the server-to-server and SDK integrations. Where are the performance differences? Compare the same variables across S2S and SDK performance are compared (ie: apps, geos, platform, MoPub SDK version, size, device, creative type, app version). Where is performance lacking?
  • If comparing SDK and S2S integrations, make sure you are running the exact same ad formats through both integrations (MRAID, HTML, VAST video, etc..)
  • Investigate when your impression tracker is fired on your SDK for each ad format.

API Changelog

10/19/2015:

  • Added ‘secure’ flag to request imp.ext object to indicate bidder must respond with SSL compliant creatives
  • Removed references to UIDH

7/13/2015:

  • Clarified that publishers should have the ability to generate multiple tag IDs per placement/size.

7/1/2015

  • Updated video spec

2/6/2015:

  • Updated for MRAID 2.0 support. API = 3 for MRAID v1, API = 5 for MRAID v2
  • Removed section for legacy MRAID 2.0 support
  • Removed references to banner.ext.mraid object
  • Modified video maxduration to 1000
  • Clarified that make/model are also supported on Android
  • Made minor updates to clarify descriptions for some parameters

11/24/2014

Added additional support for app category, geo object, uidh, and blocked categories.

  • app.cat
  • bcat
  • device.ext.uidh
  • device.geo

10/1/2014

  • Added clarification around TagIDs and ad format

  • Require either App or TagID

8/22/2014

  • TagID is required

8/7/2014

  • Clarified itunes Store ID and Google Package Name are passed in the bundle ID field not App ID

Last updated October 10, 2018

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2018 MoPub Inc.