Native 1.2 Ad Markup bidding (ADM)

Requirements for using Native 1.2 ADM

Native Ad Markup Bidding (ADM) enables your bidder to submit native ad markup via the adm field in the OpenRTB bid response. Instead of registering every creative with Microsoft Monetize, register one creative for each of the following combinations:

• Unique ad campaign or brand you represent
• Unique supported language

Get started with Native ADM

Your bidder must be enabled for this feature. If you're unsure whether your bidder is enabled, check with your Monetize account representative or open a product support ticket.

Once enabled, follow these two steps to buy inventory via ADM:

1. Register individually branded creatives – All creative assets associated with this brand will serve through this registered creative.
2. Bid with dynamic creative assets – The ad markup submitted in the bid response should match the registered creative.

Register Native creatives

Register one creative per brand and language combination using the Creative Service. Consider the following when registering a creative:

• The creative must represent one of the actual ads dynamically passed in the bid response for this brand.
  • The specific ad chosen for registration does not matter.
  • The creative must be eligible to serve on Monetize inventory.
• The creative must undergo a platform audit.
• When registering a native creative, several OpenRTB and Microsoft macros are supported. See the Tracking Macros section below for a list of macros supported in adm.
• You do not need to specify the brand_id field; Monetize sets this during the audit.
• Bids must use the OpenRTB protocol.
• Include impression and click trackers when registering your creative. The ad markup in the bid response should use the same set of vendors (or fewer) that were registered with the creative.

Bid with native ADM

Specifications

Considerations

• Use native creative template 39461.
• Native creative assets must be passed via the seatbid.bid.adm object.
  • Include image assets, data assets, and event trackers.
  • These assets will serve instead of the creative asset you initially registered.

Bid response’s bid object

• The other bid response objects are not listed here. For more information, see our bid response documentation.
• Bidders should submit ad markup in the standard OpenRTB seatbid.bid.adm field.
• You must include a registered creative ID in one of the following bid response fields (adid, crid).
• The crid or adid value must match the corresponding branded creative object.

Bid response fields

ADM object

Event trackers response object

Native ext object

Monetize supports a single native ext object for Monetize-specific extensions.

Field definitions

Asset object

Monetize supports the following fields to define one or more native asset objects, which are included as a JSON-encoded string in the adm field of the bid object.

Field definitions

Title object

Defines a title asset in a native adm object.

Image object

Image ext Object

Monetize supports a single native ext object for Monetize-specific (formerly AppNexus) extensions.

Field definitions

Image ext AppNexus object

Monetize supports the following fields in the appnexus extension object:

Data object

We support all data asset types found in the IAB OpenRTB Native Ads Specification 1.2.

Link object

Defines the link for a native asset. When clicked, the user is directed to the specified URL. This object can only be defined on the parent adm object.

Field definitions

Custom macros

When an enabled bidder submits ad markup, the seatbid.bid.ext.appnexus.custom_macros extension field is ignored.

• If the admarkup field is not returned at all, the registered creative content will serve by default. In this case, seatbid.bid.ext.appnexus.custom_macros is supported as usual.

Field definitions

Bid response example

{
  "seatbid": [
    {
      "bid": [
        {
          "nurl": "https://rtb-fakeurl.com/lax/wintrk=CwE&wp=${AUCTION_PRICE}&curr=${AUCTION_CURRENCY}&aid=${AUCTION_AD_ID}",
          "adid": "12345",
          "crid": "test_code",
          "price": 2.50,
          "adm": {
            "link": {
              "url": "https://rtb-fakeurl.com"
            },
            "ver": "1.2",
            "assets": [
              {
                "id": 1,
                "img": {
                  "w": 1200,
                  "h": 627,
                  "url": "https://rtb-fake-image-url.com",
                  "ext": {
                    "appnexus": {
                      "prevent_crop": 1
                    }
                  }
                }
              },
              {
                "id": 2,
                "title": {
                  "text": "AD"
                }
              },
              {
                "id": 3,
                "data": {
                  "value": "abc.com"
                }
              }
            ],
            "privacy": "https://rtb-fake-privacy-url.com",
            "eventtrackers": [
              {
                "event": 1,
                "method": 1,
                "url": "https://rtb-fakeurl.com/price=${AUCTION_PRICE}"
              }
            ]
          },
          "impid": "3226285750417000001",
          "id": "6ab34155-c960-1111-abcd-52b7321adbbb"
        }
      ],
      "seat": "123"
    }
  ],
  "id": "3",
  "cur": "USD"
}

Server-side impression tracking

For bidders using native ADM, submit the win notification URL in seatbid.bid.nurl. It is expected that the bidder will include the ${PRICE_PAID} or ${AUCTION_PRICE} macro in this URL to receive win price information.

Field definitions

Tracking macros

Some publishers periodically audit creatives, which can generate false impression and click tracking events. When Microsoft detects audit events:

• Any URL-encoded ${AUCTION_PRICE} macro in adm expands to the string "AUDIT".
• Any URL-encoded ${AN_IS_AUDIT} macro expands to 1.

The following macros support impression and click tracking. See ADM macros example below for usage details.

Macro reference

Encoding and notification

All OpenRTB macros must be URL-encoded. To use these macros, ensure they are properly encoded in pixels as described above.

Microsoft supports both seatbid.bid.nurl and seatbid.bid.burl for server-side win notification. These must be submitted in the respective bid response field.

Creative example

This example uses four data assets and two image assets, but you can choose to use a different combination depending on the assets you want to register. (Remember, you must have at least one asset of each type.) For more details on native creative assets, see the Creative Service.

Related topics

• Ad markup (ADM) Bidding Overview
• Banner Ad Markup (ADM) in Bid Responses
• Video Ad Markup (ADM) in Bid Responses