Back to Bidders

AppNexus

Features

Table of Contents

• Table of Contents
  • Bid Params
  • Video Object
  • User Object
  • App Object
  • Video Bid params and Video MediaTypes params
  • Custom Targeting keys
  • Auction Level Keywords
  • Passing Keys Without Values
  • First Party Data
  • User Sync in AMP
  • Mobile App Display Manager Version
  • Debug Auction
  • Prebid Server Test Request

All AppNexus (Microsoft/Xandr) placements included in a single call to requestBids must belong to the same parent Publisher. If placements from two different publishers are included in the call, the AppNexus bidder will not return any demand for those placements.
Note: This requirement does not apply to adapters that are aliasing the AppNexus adapter.

Bid Params

Starting with Prebid.js version 9.0, an update was made to the appnexusBidAdapter.js file to remove the support for the transformBidParams function. Previously this standard adapter function was used in conjunction of Prebid.js > PBS requests to modify any bid params for that bidder to the bid param format used by the PBS endpoint. Part of the changes for 9.0 in general were to remove these functions from the client-side adapter files, in order to reduce the build size of Prebid.js for those publishers who wanted to make the PBS requests. In the case of our adapter, we instead created a new module named anPspParamsConverter that would mimic behavior of the transformBidParams function. There’s no setup instructions needed on the Prebid.js configs, the module only needs to be included in the Prebid.js build file and it will perform the needed steps. If you have any questions on this change, please reach out to your Microsoft representative and they can help.

Starting with Prebid.js version 7.36.0, an update was made to the appnexusBidAdapter.js file to support bid params in a lower-case underscore format (eg invCode to inv_code) similar to how the params are formatted for the Prebid Server AppNexus bidder. This change was implemented to streamline publisher setups for both projects instead of maintaining separate versions of the same params depending on what setup is used. To avoid breaking changes, the old ‘camelCase’ format is still currently supported for all AppNexus bid params in the appnexusBidAdapter.js file. If you are using an older version of Prebid.js, you will need to continue to use the older ‘camelCase’ format as appropriate. The table below will reflect both formats, though it’s recommended to use the lower-case underscore format where possible going forward (assuming you’re using a compatible version of Prebid.js).

Video Object

For details on how these video params work with the params set in the adUnit.mediaTypes.video object, see Video Bid params and Video MediaTypes params section below.

User Object

App Object

AppNexus supports using prebid within a mobile app’s webview. If you are interested in using an SDK, please see Prebid Mobile instead.

Custom Targeting keys

AppNexus returns custom keys that can be sent to the adserver through bidderSettings: buyerMemberId, dealPriority, and dealCode. The following snippet demonstrates how to add these custom keys as key-value pairs.

pbjs.bidderSettings = {
  appnexus: {
    adserverTargeting: [
      {
        key: "apn_buyer_memberid", // Use key configured in your adserver
        val: function(bidResponse) {
          return bidResponse.appnexus.buyerMemberId;
        }
      },
      {
        key: "apn_prio", // Use key configured in your adserver
        val: function(bidResponse) {
          return bidResponse.appnexus.dealPriority;
        }
      }, {
        key: "apn_dealcode", // Use key configured in your adserver
        val: function(bidResponse) {
          return bidResponse.appnexus.dealCode;
        }
      }
    ]
  }
}

Video Bid params and Video MediaTypes params

It is possible to have setup video params within the adUnit’s AppNexus bid object as well as in the adUnit’s mediaTypes.video object. In this case, there is a set of logic that the AppNexus bid adapter follows to resolve which values should be passed along to the ad server request. Generally speaking, the adapter prefers the values from bid param video object over the mediaTypes video object, in order to preserve historical setups. So for instance, if the playbackmethod field was set in both locations, then the bid params playback_method would be chosen over the mediaTypes playbackmethod. If there are different fields set between the two locations and they don’t overlap, then the mediaTypes.video params would be included along with the bid params.

To note - not all the fields between the two locations have a single direct comparison, nor are all fields from the mediaTypes.video object are supported by the ad server endpoint. The fields/values set in the mediaTypes.video object follow the OpenRTB convention, while our bid params follow the convention for the ad server endpoint (which is not a straight OpenRTB endpoint). The AppNexus bid adapter converts the matching fields from the mediaTypes.video object where there is a correlation to help support as much as possible. For example, to help infer the context field, the adapter will look to the mediaTypes.video.plcmt, mediaTypes.video.startdelay, and mediaTypes.video.placement fields to help determine the appropriate context value. The startdelay field is included here to help clarify the type of instream video that is used (ie pre/mid/post-roll).

If you want to transition from video bid params to use the mediaTypes.video params (to simplify the adUnit setup), please contact your AppNexus contact to help identify the proper fields/values are populated to ensure a smooth transition.

Auction Level Keywords

It’s possible to pass a set of keywords for the whole request, rather than a particular adUnit. Though they would apply to all adUnits (which include the appnexus bidder) in an auction, these keywords can work together with the bidder level keywords (if for example you want to have specific targeting for a particular adUnit).

Below is an example of how to define these auction level keywords for the appnexus bidder:

pbjs.setConfig({
  appnexusAuctionKeywords: {
    genre: ['classical', 'jazz'],
    instrument: 'piano'
  }
});

Like in the bidder.params.keywords, the values here can be empty. Please see the section immediately below for more details.

Passing Keys Without Values

It’s possible to use the keywords parameter to define keys that do not have any associated values. Keys with empty values can be created in Prebid.js and can also be sent through Prebid Server to AppNexus. The following are examples of sending keys with empty values:

keywords: {
  myKeyword: '',
  myOtherKeyword: ['']
}

The preceding example passes the key myKeyword with an empty value. The key myOtherKeyword contains an empty value array.

You can define keys with values and without values in the same keywords definition. In this next example, we’ve defined the key color with an array of values: red, blue, and green. We’ve followed that with the key otherKeyword with an empty value array.

keywords: {
  color: ['red', 'blue', 'green'],
  otherKeyword: ['']
}

First Party Data

Publishers should use the ortb2 method of setting First Party Data.

At this time however, the appnexus bidder fully reads the First Party Data when using the Prebid Server and Prebid Server Premium endpoints. The client-side version of the appnexus bidder has partial support to read all the various keywords parameters from the First Party Data fields. There is also some special support with the segment fields but only from known sources which are specifically configured. All other First Party Data fields are not read at this time.

PBS/PSP supports all first party data fields: site, user, segments, and imp-level first party data.

User Sync in AMP

If you are syncing user id’s with Prebid Server and are using AppNexus’ managed service, see AMP Implementation Guide cookie-sync instructions for details.

Mobile App Display Manager Version

The AppNexus endpoint expects imp.displaymanagerver to be populated for mobile app sources requests, however not all SDKs will populate this field. If the imp.displaymanagerver field is not supplied for an imp, but request.app.ext.prebid.source and request.app.ext.prebid.version are supplied, the adapter will fill in a value for diplaymanagerver. It will concatenate the two app fields as <source>-<version> fo fill in the empty displaymanagerver before sending the request to AppNexus.

Debug Auction

Enabling the AppNexus Debug Auction feature should only be done for diagnosing the AppNexus auction. Do not enable this feature in a production setting where it may impact users.

To understand what is happening behind the scenes during an auction, you can enable a debug auction by adding an apn_prebid_debug cookie with a JSON string. For example:

{ "enabled": true, "dongle": "QWERTY", "debug_timeout": 1000, "member_id": 958 }

To view the results of the debug auction, add the pbjs_debug=true query string parameter and open your browser’s developer console.

Prebid Server Test Request

The following test parameters can be used to verify that Prebid Server is working properly with the server-side Appnexus adapter. This example includes an imp object with an Appnexus test placement ID and sizes that would match with the test creative.

"imp": [{
  "id": "some-impression-id",
  "banner": {
    "format": [{
      "w": 600,
      "h": 500
    }, {
      "w": 300,
      "h": 600
    }]
  },
  "ext": {
    "appnexus": {
      "placement_id": 13144370
    }
  }
}]

"Send All Bids" Ad Server Keys

Back to Bidders