Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Use the Console API to Synchronize Your Inventory Structure

This page walks shows you through the process of mapping how to use the Console API to map your supply to the corresponding objects within AppNexus , and test the mapping with a debug auction. Please follow these instructions for each publisher you work with.

To map your supply using the Console APIUI, see Use the UI to Synchronize Your Inventory Structure.

Panel
borderColor#000000
bgColor#FFD28C
borderWidth1
borderStylesolid
titleOn This Page
Table of Contents
maxLevel2
minLevel2
maxlevel3
minlevel3

...

Before You Begin

Before getting started, please ensure you begin, you must meet the following criteria:

  • You have access to the Console API wiki space
  • You have reviewed our API onboarding materials 
  • You have received API credentials
  • You have generally familiarized yourself with how the API functions
  • You completed API onboarding.
  • You are familiar with the AppNexus Sell-Side Object Hierarchy.
Info

The rest of this document assumes an understanding of the Console API and the AppNexus sell-side object hierarchy.

Step 2. How Bid Requests Map to Publishers and Placements

For each integration type, there are 2 fields that can be used to indicate a mapping to AppNexus sell-side objects. For example:

  • ASI
    • ext_pub_code maps to the publisher.code field in AppNexus
    • ext_placement_code maps to the placement.code field in AppNexus
  • OpenRTB
    • BidRequest.Site.Publisher.id maps to the publisher.code field in AppNexus
    • BidRequest.Site.id maps to the placement.code field in AppNexus
Tip
For custom integration types, you can contact AppNexus Support via our Customer Portal to learn how your bid requests map to AppNexus publishers and placements.

The following steps will explain how to create publisher and placement objects with the proper configuration to accept those mappings.

Step 3. Creating a Publisher

The first thing you'll do is create a new publisher, specifying the publisher.code if you're using one.

POST: http://api.appnexus.com/publisher?member_id=XXXX&create_default_placement=false (where XXXX is your member ID)

Code Block
languagejs
titleJSON
{"publisher": {"name": "AAAA", "is_oo":true, "code": "BBBB", "reselling_exposure":"CCCC"}}
  • AAAA: set this to the name of the publisher
  • BBBB: (optional) set this to the value passed in the bid request for mapping to the publisher object
  • CCCC: (optional) set this to "public" or "private" based on whether you would like the publisher's name to be exposed to buyers, or not.

Once you have POST'ed successfully, the API will provide the ID of the newly-created object in its response.  You'll need to store this value for further use.

Step 4. Creating a Site (a.k.a. Placement Group)

Next, we'll create one or more Sites (or Placement Groups), which are simply a grouping mechanism if you have a large number of placements within one Publisher.  Using one is mandatory, multiple is optional.

...

  • You have worked with AppNexus to create a global ad quality profile to control which creatives can appear on your publishers' inventory. 

Step 1. Create a Publisher

Use the Publisher Service to create a new publisher that's mapped to your inventory.

Note

The code field is required for all external sellers at both the publisher and placement levels and is highly recommended for all other sellers to ensure that your inventory is as granular as possible so that it can be investigated accurately for quality issues, and specifically for domain detectability. While not required, this step will help you to split your inventory into highly detectable and less detectable tags, allowing you to isolate the impacts of non-detectable domains on the rest of your inventory's viability.

Your JSON must include the following fields:

Table Plus
FieldTypeDescriptionDefault
namestring (255)Name of the legal entity of the company you pay money to. For instance, if you buy from espn.com, the publisher should be named as the legal entity for ESPN. 
is_ooboolean

If true, the publisher is owned and operated by the network, meaning the network gets 100% of the revenue.   Setting this to true also enables you to skip setting up payment rules.

false
codestring (100)The code that identifies the publisher from your inventory.  Use the value of the BidRequest.Site.Publisher.id or BidRequest.App.Publisher.id  fields. 
reselling_exposureenumThe publisher's exposure for reselling to other members of the platform. Possible values: "public" or "private.""private"
stateenumThe state of the publisher. Possible values: "active" or "inactive.""inactive"

Code Block
$cat publisher.json

{
"publisher": {
	"name": "PUBLISHER_NAME", 
	"is_oo": true, 
 	"code": "PUBLISHER_CODE", 
	"reselling_exposure": "private",
	"state": "active"
	 }
}

$curl -b cookies -c cookies -d @publisher.json -X POST 'https://api.appnexus.com/publisher?member_id=MEMBER_ID&create_default_placement=false'

The API returns the ID of the newly created object in its response. Save this value for use in the next two steps.

Step 2. Create a Site (Placement Group)

Use the Site Service to create one or more sites (or placement groups) associated with the publisher you created in step 1. Sites are simply a grouping mechanism for placements. At least one site is required, but you don't need to create additional ones if you don't need further granularity. 
Each site should represent a grouping of placements that:

  1.  Are associated with the same domain (both mobile and standard web)
  2. Or are associated with the same mobile app

Your JSON must include the following fields:

Table Plus
FieldTypeDescriptionDefault
namestring (255) Domain or app bundle ID passed through this site. 
supply_typeenum

Specifies whether this is a site viewed on a desktop browser ("web"), a site viewed on a mobile browser ("mobile_web"), or an app run on a mobile device ("mobile_app"). This distinction allows the buyer to target campaigns to the particular supply type where they want to advertise, for example, an advertiser may upload creatives optimized for mobile browsers with mobile landing pages.

"web"

Code Block
languagejs
title
$cat site.json
{
	"site": {
		"name": "DOMAIN_NAME_OR_APP_BUNDLE_ID", 
 	 	"supply_type": "SUPPLY_TYPE"
		}
}

$curl -b cookies -c cookies -d @site.json -X POST 'https://api.appnexus.com/site?member_id=

...

MEMBER_ID&publisher_id=

...

PUBLISHER_ID'

The API returns the ID of the newly created object in its response. Save this value for use in the next step. 

Step 3. Create a Placement

Use the Placement Service to create placements associated with the publisher and site you created in

...

steps 1 and 2.   

Note

The code field is required for all external sellers at both the publisher and placement levels and is highly recommended for all other sellers to ensure that your inventory is as granular as possible so that it can be investigated accurately for quality issues, and specifically for domain detectability. While not required, this step will help you to split your inventory into highly detectable and less detectable tags, allowing you to isolate the impacts of non-detectable domains on the rest of your inventory's viability.

Your JSON must include the following fields:

Table Plus
FieldTypeDescriptionDefault
namestring (255)Name associated with the publisher. 
codestring (100)The code that identifies the placement from your inventory.  Use the value of the BidRequest.Site.id or BidRequest.App.id field. 

Example

Code Block
languagejs
titleJSON
{"site$cat placement.json

{
	"placement": {
		"name": "AAAAPLACEMENT_NAME", "supply_type
	 	"code": "BBBB"}}
  • AAAA: set a name for the site
  • BBBB: allowed values are "web", "mobile_web", or "mobile_app"
    • if you set "web", AppNexus will assume that all impressions for underlying placements are for desktop browser inventory (regardless of banner, video, native, etc)
    • if you set "mobile_web", we will assume that all impressions are for mobile browser
    • if you set "mobile_app", we will assume that all impressions are for mobile applications

Step 5. Creating a Placement

Finally, we'll create one or more Placements, which are the most granular sell-side objects.

...

PLACEMENT_CODE"
		}
}

$curl -b cookies -c cookies -d @placement.json -X POST 'https://api.appnexus.com/placement?member_id=

...

MEMBER_ID&publisher_id=

...

PUBLISHER_ID&site_id=

...

SITE_ID'

Step 4. Test the Mapping Setup (Optional)

You can test that the mapping is working correctly by using a debug auction. Send a test impression to our endpoint with the debug parameters and check that the impression reaches the expected placement.

{"placement
Code Block
languagejs
titleJSON
Example debug auction for a video impression using the OpenRTB protocol
collapsetrue
$cat debug.json

{ 
	"id": { 
		"nameimp": "AAAA", "code": "BBBB"}}
  • AAAA: set a name for the placement
  • BBBB: (optional) set this to the value passed in the bid request for mapping to the placement object

...

[{
			"id": "1",
			"video": {
				"mimes": [
					"application/x-shockwave-flash",
					"video/mp4",
					"video/x-flv" 
					],
				 "linearity": 1, 
				 "minduration": 0, 
				 "maxduration": 999, 
				 "protocols": [2,5], 
				 "w": 640, 
				 "h": 360,
				 "startdelay": 0,
				 "minbitrate": 0,
				 "maxbitrate": 1500,
				 "delivery": [2],
				 "pos": 0,
				 "api": [1]
				 	},
				 "bidfloor": 1,
				 "bidfloorcur": "EUR"
				} ], 
			"site": {
				"domain": "test.com" },
				"device": {
						"dnt": 0,
						"ua": "Mozilla/5.0 (Windows NT 6.3; WOW64; rv:39.0) Gecko/20100101 Firefox/39.0",
						"ip": "212.185.163.114",
						"os": "Win_8",
						"osv": "8",
						"js": 0,
						"devicetype": 2 
						},
				 "user": {
						 "buyeruid": "APPNEXUS_USER_ID" 
							}, 
				"at": 2, 
				"tmax": 100, 
				"cur": ["EUR","USD"]}'

$curl -b cookies -c cookies -s -i d @debug.json 'https://<MEMBER_NAME>-<GEO>.com/openrtb2?member_id=MEMBER_ID&debug_member=DEBUG_MEMBER&dongle=DONGLE'

In the example above, <GEO> has potential values: "useast","uswest","apac","emea"

Related Topics