Creative Service
You can use the Creative Service to add creatives to AppNexus. All creatives must be attached to an advertiser or publisher.
- You can view your advertiser ID by calling the Advertiser Service.
- You can view your publisher ID by calling the Publisher Service.
- You can attach a creative to a publisher for use as a default creative for a placement. You would then attach the creative to a placement via its ID using the Placement Service.
Hosted and third-party Video and Audio services can only be accessed using the Creative Vast Service. Hosted and third-party HTML creatives can only be accessed using the Creative HTML Service.
Auditing
AppNexus works with members who care deeply about brand and reputation. For this reason, we are careful to ensure that the advertisements (creatives) that pass through our system are acceptable to all parties. For quality assurance, all creatives that serve on third-party inventory must be pre-registered using the Creative Service.
- Creatives are identified by their media_url (either a third-party adserver URL or a Content Delivery Network URL for a Flash, image, or video file).
- AppNexus checks media_urls on a regular basis. If a file disappears, the creative will be treated as unaudited.
- Once a creative has passed AppNexus audit, certain changes to the creative cause it to be resubmitted for audit. For more details, see Changes That Cause Re-Audit.
- For more details on auditing, see Creative Standards and Auditing.
REST API
Add a new creative to one of your advertisers:
Add a new creative to one of your publishers:
Modify an existing creative:
View all creatives:
View all creatives for an advertiser or publisher:
You can filter for creatives based on when they first and last served. This is particularly useful when you are approaching your object limit and need to identify creatives that can be deleted from the system. For more details, see First Run / Last Run.
View a specific creative:
View multiple creatives by ID using a comma-separated list:
View creative audit stats:
The response tells you the number of creatives with each AppNexus, Microsoft, and Google audit status. For the response format, see the example below.
Delete a creative:
You cannot delete a creative that is used as the default creative for a member or placement. Default creatives can be deleted once they are disassociated from a placement.
Find out which fields you can filter and sort by:
JSON Fields
Field | Type (Length) | Description | Default | Required On |
---|---|---|---|---|
| int | The internal ID associated with the creative. | Auto-generated number | PUT, in query string |
| string (100) | The custom code for the creative. | ||
| string (100) | The additional custom code for the creative. | ||
| string (400) | The name for the creative. | ||
type | enum | Read-only. The type of creative. Possible values:
Alpha-Beta Notice This field or feature is part of functionality currently in either Alpha or Beta phase. It is therefore subject to change. | ||
| int | The ID of the advertiser to which the creative is attached. | POST/PUT, in query string, if the creative is attached to an advertiser | |
| int | The ID of the publisher/media buy to which the creative is attached. | POST/PUT, in query string, if the creative is attached to a publisher | |
| int | The ID of the brand of the company advertising the creative. If included, it will be verified by the AppNexus auditing team. If not included, it will be assigned by the auditing team. To retrieve a full list of brands, see the Brand Service. | ||
| enum | Read-only. The state of the creative. Possible values: "active" or "inactive". |
| |
status
| object | The status of the creative describing if the creative is ready to serve. For more details, see Status below. | ||
click_track_result | enum | The result of the click track test, a feature only available in the Console user interface. Possible values: "not_tested", "passed", or "failed". | "not_tested" | |
| array of objects | The list of campaigns to which the creative is associated. For more details, see Campaigns below. This field will only be returned if an | ||
| enum | Deprecated. | ||
| object | The creative template (ex.: When using a template for the "raw-html" format (HTML that will not be served in an iFrame), everything in the | POST | |
| object | This field is no longer in use. |
| |
| array of objects | The values for custom macros used in the creative template. For more details, see Custom Macros below. | POST, if template includes required custom macros | |
| Int | The width of the creative; the string should contain an int. | POST, if template is for the "Banner" or "Expandable" media type | |
| Int | The height of the creative; the string should contain an int. If the creative's template has a Pop media type, then either the creative's height must be set OR pop_window_maximize (in the pop_values field) must be true (but not both).
| POST, if template is for the "Banner" or "Expandable" media type | |
| string (1000) | The URL of the creative - can be image, flash, HTML, javascript (see format). URL must exist and should be on a CDN or equivalent. | POST, if not using content | |
| string (1000) | The URL of the secure (HTTPS) creative - can be image, flash, HTML, javascript (see format) to be served on a secure ad call. URL must exist and should be on a CDN or equivalent. | ||
| string (2000) | click_url is being deprecated in favor of click_target. This value must begin with "http://" or "https://" | POST, if template is for the "image" format | |
| string (1000) | The file name and extension for a hosted creative. Allowed file types: jpg, gif, png, swf, flv, mp4, wmv, f4v, avi, m4v, mov, and mpg. | POST, if adding a hosted creative | |
| string (255) | The ClickTag variable in a Flash creative. AppNexus can execute and track user clicks on a Flash creative only if you provide the exact variable in the file (clickTAG, ClickTag, Clicktag, etc). You can use the ClickTags Service to identify this variable. If you need to specify more than one ClickTag variable for a single creative, please contact support. This field may only be updated (via | ||
| string | Javascript or HTML content when "format" is "raw-js" or "iframe-html". For a hosted creative, the content of the file must be base64-encoded and submitted as a string within the content field. When using a template (ex.:
There is a maximum length in the content field of 65535 characters. | 3rd party tag holder | POST, if not using media_url |
| string | Javascript or HTML content when "format" is "raw-js" or "iframe-html" served on a secure ad call. | ||
| string | The value you pass into the "content" field through the UI will be returned in this field unchanged. The "content" field will contain the content modified by AppNexus to properly serve. This field can also be uploaded directly through the API. In this case, the value uploaded to this field will be referenced in the content section of the UI (Creative Content > Tag field). | POST when submitting as type raw-html. | |
| string | See original_content. This is the secure version of this content. | ||
| string | Read-only. The API pulls out macros and puts them in this field so that the bidder knows which macros to expect. | ||
| enum | The audit status of the creative. Possible values: "no_audit", "pending", "rejected", or "audited".
| "pending" | |
| string | Read-only. The creative auditing team can pass messages about a creative in this field. | ||
| Boolean | If true, the creative will be submitted for auditing. If false, the creative will not be submitted. Unaudited creatives can only run on a network's managed inventory.
| true | |
| enum | The ssl (HTTPS) status of the creative. Only creatives with ssl_status = approved will be eligible to serve on secure inventory. Note: If a creative fails the ssl Sherlock audit, you can submit it for a retest (once you've fixed the downstream non-secure content) by changing this field to "pending". Allowed values:
|
| |
| Boolean | If true, the creative will be submitted for secure (HTTPS) auditing. If false, the creative will not be submitted. If true, either media_url_secure or content_secure is required as well. | false | |
| enum | Deprecated. |
| |
| string | Deprecated. | ||
| enum | This field is no longer in use. |
| |
| string | This field is no longer in use. | ||
| Boolean | If true, the creative is self-audited and thus will not go through platform (AppNexus) audit. The creative can only serve on inventory that accepts your self-classified creative or on inventory that accepts unaudited creatives. | false | |
| Boolean | Read-only. If your creative (1) has not run and (2) has not been modified in 45 days, then it will be automatically marked expired and will not serve on any inventory.
| false | |
| Boolean | Read-only. If Sherlock flags the creative for having malware or loading blacklisted domains, this is set to true to prevent the creative from serving. | false | |
| Boolean | Read-only. If true, the creative is hosted by AppNexus. | ||
| double | The lifetime budget in dollars. Note: To include this field in a GET response, pass attributes=1 in the query string. | unlimited | |
| int | The lifetime limit for number of impressions. Note: To include this field in a GET response, pass attributes=1 in the query string. | unlimited | |
| double | The daily budget in dollars. Note: To include this field in a GET response, pass attributes=1 in the query string. | unlimited | |
| int | The daily limit for number of impressions. Note: To include this field in a GET response, pass attributes=1 in the query string. | unlimited | |
| Boolean | If | true | |
| Boolean | Admin-only. If | ||
| int | You can attach targeting such as gender and geography to a creative by creating a profile and associating it here. | ||
| object | To arrange your creatives in folders for convenience (usually in the UI) you will create a folder using the Creative Folder Service and then associate it here via folder ID or in the Creative Folder service via creative ID. Output is {"id": "41", "name": "MyFolder"} | ||
line_items | array of objects | The line items that are associated with the creative. See Line Items below for more details. | ||
| array of objects | The pixels to serve with the creative. They can be for external impression tracking, external click tracking, or other purposes, such as adding the AdChoices icon to a creative. See Pixels below for more details. | ||
| string (100) | Deprecated. Please use the pixels array instead. The URL of an impression pixel to serve with the media URL or content. | ||
| string (100) | Deprecated. Please use the pixels array instead. The URL of a secure (HTTPS) impression pixel to serve with the media URL content on a secure ad call. | ||
| enum | Deprecated. Please use the pixels array instead. The type of impression pixel. This field must be set if pixel_url is used. Possible values: "javascript" or "image". | ||
| Boolean | Deprecated. If true, the bidder will not serve this creative when an iframe is detected in the ad call. | false | |
| Boolean | Deprecated. | true | |
| string | Write-only. For a flash creative, this is the content of the backup creative that will be served if a user's browser does not support flash. For an in-banner video creative, this is the content of the poster image that will display before users click play and after the video has finished playing. This field must be used in combination with flash_backup_file_name. | POST/PUT, if using flash_backup_file_name | |
| string | Write-only. This field must be used in combination with flash_backup_content. This is the file name and extension of the backup creative. | POST/PUT, if using flash_backup_content | |
| string (100) | For a flash creative, this is the URL of a 3rd-party creative that will be served if the user's browser does not support flash. For an in-banner video creative, this is the URL of the poster image that will display before users click play and after the video has finished playing. | ||
| Boolean | This is a flag used to mark this creative as part of a control/test group in A/B testing. For more information, see Test and Control Targeting (Standard Line Item). | false | |
| array | A list of segments that a user will be added to upon viewing or clicking on this creative. For more information, see Segments below. Example: | ||
| timestamp | Read-only. The date and time when this creative was created. If it was created before January 2010, this will be zero. | ||
| timestamp | Read-only. The date and time when the creative was last modified. | ||
| array of strings | Deprecated. | ||
| enum | Deprecated. | ||
| enum | Deprecated. | ||
| Boolean | If true, the (optional) landing page URL for non-3rd party image and flash creatives is set at the campaign or line item level. See Dynamic Landing Pages for more information. | false | |
| int | Read-only. The size of an uploaded creative (in bytes). | ||
| string (25) | The top line of text displayed in a text creative | POST, if template is for the "text" format | |
| string (70) | The lower line of text displayed in a text creative | POST, if template is for the "text" format | |
| string (35) | The readable URL displayed in a text creative | POST, if template is for the "text" format | |
| enum | The action that the device should take when the creative is clicked. Currently, this field will be set to the only supported click action, "click-to-web" | "click-to-web" | |
| string (2000) | The target of the click_action. For click-to-web, this is the click_url of the creative. | ||
| array of objects | The categories that describe the creative and offer type. Note: To include categories in a GET response, pass attributes=1 in the query string. To retrieve a full list of categories, see the Category Service. | ||
| array of objects | Read-only. The ad servers that deliver the creative or are called for data collection purposes during the delivery of the creative. Note: To include adservers in a GET response, pass | ||
| array of objects | The attributes that describe technical characteristics of the creative, such as "Expandable" or "Video". Note: To include technical attributes in a GET response, pass attributes=1 in the query string. To retrieve a full list of technical attributes, see the Technical Attribute Service. | ||
| object | The language of the creative. To retrieve a full list of languages, see the Language Service. | ||
brand | object | Read-only. The brand of the company advertising the creative and the category associated with the brand. For more details, see Brand below. | ||
| array | Deprecated. | ||
| int | Creatives set to "0" will be submitted for audit with a standard SLA. Creatives submitted with any number other than 0 will result in a priority audit (when enabled) and resulting fees. If you have a supplemental services agreement with AppNexus for priority audits, you can submit a creative for priority audit (auditing within 2 hours during business hours) by setting this field to 2. For more details about priority auditing, see Creative Standards and Auditing. | ||
| timestamp | Read-only. The estimate time of completion for a priority audit. | ||
currency | string | Read-only. The code that defines the advertiser's primary currency (for example, USD). For more details about the currency types available, see Currency Service. | Member's default currency | |
| timestamp | Read-only. The date and time when the creative first served, refreshed on an hourly basis. This value reflects the UTC time zone. To include this information in a GET response, pass | ||
| timestamp | Read-only. The date and time when the creative last served, refreshed on an hourly basis. This value reflects the UTC time zone. To include this information in a GET response, pass | ||
| object | Information needed for mobile creatives to pass the creative audit. See Mobile below. | ||
video_attribute | object | Attributes for third-party in-stream (VAST) and hosted video creatives. To add & update vast creatives, use the | null | |
| object | The | ||
| string | The source of this creative's content. Allowed values:
|
| |
| multi-object | If the value of this creative's |
|
|
| array of objects | Creatives associated with the brands in this array will not serve together in | n/a | |
| array of objects | Creatives associated with the categories in this array will not serve together in | n/a | |
thirdparty_pixels | array of objects | An array of third-party pixels associated with the creative. You can automatically attach these pixels to all creatives owned by an advertiser or member using the Third-party Pixel service or attach them individually at the creative level using the Creative Service. | null | PUT |
native | object | If this creative is a "native ad", this object is populated with the elements required for native ads. For more information, see the description of the Native object below. | null | Required on POST and PUT for native ads. Technically, native ads are identified by our system as those creatives that have a template with a creative_format_id of 12 that identifies them as "native" . |
native_attribute | object | This is the new native object which contains elements required for native ads. For more information, see the description of the Native Attribute object below. | null | Required for native ad with template 39461 |
click_trackers | array of objects | A list of third-party click tracking URLs intended to be used with native creatives. For more information, see Click Trackers below. | ||
impression_trackers | array of objects | A list of third-party impression tracking URLs intended to be used with native creatives. For more information, see Impression Trackers below. | ||
adx_audit | object | Read only. This object contains information about the status and feedback related to the Google AdExchange audit of the creative. Information about whether or not a creative has been approved is returned in the audit_status field. | ||
flash_backup_url_secure | string | This is the secure version of flash_backup_url , which is served on a secure ad call. | ||
msft_external_audit_feedback | string | Deprecated. | ||
msft_external_audit_status | enum | Deprecated. | ||
member_id | int | The ID of the member that owns the creative. | ||
media_assets | array of objects | The asset id of the original file and a field describing what the asset must be used for. It is used to associate AppNexus hosted files to your creative. This array will auto-populate when uploading files via the API. For more information, see Media Assets below. | ||
ad_type | string | This field only applies when you are associating creatives to augmented line items. The type of creative used. Possible values:
This value determines how auction items are tracked for the line item's buying strategy, paying strategy, optimization options, creative association, and targeting options. All creatives associated to a line item must have the same ad type, which should match the
|
Brand
The brand
object contains the following fields.
This object is read-only. To set the brand for a creative, use the brand_id
field outside of this object.
Field | Type | Description |
---|---|---|
id | int | Read-only. The ID of the brand of the company advertising the creative. |
name | string | Read-only. The name of the brand of the company advertising the creative. |
category_id | int | Read-only. The ID of the category associated with the brand |
category_name | string | Read-only. The name of the category associated with the brand. The |
Campaigns
Each object in the campaigns
array includes the following fields. To obtain information for "id" or "code" fields, you can use the Campaign Service.
Field | Type (Length) | Description | Required On |
---|---|---|---|
id | int | The ID of the campaign. Either "id" or "code" is required when updating campaign association. | PUT |
campaign_id | int | The ID of the campaign. | |
creative_id | int | The ID of the creative. | |
name | string | Read-only. The name of the campaign. | |
state | enum | Read-only. The state of the campaign. Possible values: "active", "inactive", or "parent_inactive". | |
code | string | The custom code for the campaign. Either "id" or "code" is required when updating line item association. | PUT |
Competitive Brands
For more information about brands, see the Brand Service.
Name | Type | Description | Default | Required on |
---|---|---|---|---|
id | int | The ID of the brand. |
|
|
name | string | The name of the brand. |
|
|
Competitive Categories
For more information about categories, see the Category Service.
Name | Type | Description | Default | Required on |
---|---|---|---|---|
id | int | The ID of the category. |
|
|
name | string | The name of the category. |
|
|
Creative Template
You can use the Creative Template Service to view all rendering templates that can be assigned to creatives.
Field | Type | Description |
---|---|---|
id | int | The ID of creative template. |
name | string | Read-only. The name of the creative template. |
media_subtype_id | int | Read-only. The ID of the media subtype assigned to the template. You can use the Media Subtype Service to view all supported media subtypes. |
format_id | string | Read-only. The name of the format assigned to the template. You can use the Creative Format Service to view all supported formats. |
Frequently Used Creative Templates
For more information, see the Selecting the Correct Template for Your Creative.
Template ID | Creative Type | Requirements |
---|---|---|
1 | Single URL that points to a piece of html code | You will need to pass the URL in the media_url field and set an id of 1 in the template object. |
2 | Single URL that points to a piece of Javascript code | You will need to pass the URL in the media_url field and set an id of 2 in the template object. |
5 | Creative that starts and ends with Javascript components, even if the Javascript code writes HTML. | You will need to pass the Javascript code in the content field and set an id of 5 in the template object. |
6 | Creative that starts and ends with HTML components, even if these HTML components are <script> tags. | You will need to pass the html code in the content field and set an id of 6 in the template object. |
Custom Macros
If the creative template provides default values for a macro, passing the codes and values here is optional. If the template defines a custom macro as required, however, you must pass the code and value for the macro.
Field | Type | Description |
---|---|---|
code | string | The exact name of the macro, as it is used in the code of the creative template, for example, "BORDER_COLOR". |
value | string | The value for the macro. Note that this value must match the type of the macro, as defined in the template. For example, if a macro is of the type "integer", the value must be an integer. The possible macro types are "true/false", "string", "url", "integer", "decimal", and "select_from_list" |
Custom Request Template
Field | Type | Description |
---|---|---|
id | int | The creative custom request template associated with this creative, if its |
timeout_ms | int | If this is a "mediation" creative, it will make at least one HTTP request to an external ad server, which may in turn make one or more additional requests. This is the time beyond which we will not wait any longer for this creative to be populated with content. For more information, see the Creative Custom Request Template Service. |
last_modified | timestamp | The date and time at which the custom request template was last modified. |
Line Items
Each object in the line_items
array includes the following fields. To obtain information for "id" or "code" fields, you can use the Line Item Service.
Field | Type (Length) | Description | Required On |
---|---|---|---|
name | string | Read-only. The name of the line item. | |
state | enum | Read-only. The state of the creative. Possible values: "active" or "inactive". | |
id | int | The ID of the line item. Either "id" or "code" is required when updating line item association. | PUT |
code | string | The custom code for the line item. Either "id" or "code" is required when updating line item association. | PUT |
Media Assets
The media_assets
array of objects contain the following fields:
Field | Type | Description |
---|---|---|
media_asset_id | int | The unique ID of the creative asset. |
creative_field | string | This field denotes what that particular creative asset must be used for. Possible valid values are:
|
For each media_assets
array, the following rules apply:
- Each field value can only be used once per creative. For example, you cannot have two 'flash_backup_url' assets.
- The value must be one of the valid values.
- VAST / HTML5 creatives must have one, and only one, asset.
- All other creatives can have 0 or more media assets.
Example:
Mobile
Field | Type | Description |
---|---|---|
alternative_landing_page_url | string | An alternative landing page URL that can be viewed in a desktop browser for creatives that have a landing page targeted to a specific device, operating system, or carrier. You must provide an auditable URL in order for your creative to pass auditing. |
Native
The "native"
object contains the following fields. For more information, see Add a native ad creative in the Examples.
Field | Type | Description |
---|---|---|
title | text | The title displayed with the native ad. |
description | text | A short description of the ad's offer to the user. |
full_text | text | The full text of the native ad. Much longer than description . |
context | string | The social context where the native ad will appear in the application. This varies depending on the media subtype of the native ad. For example, it may be a string such as |
icon_img_url | string | The URL of the icon image for the native ad. We don't validate this; you must ensure that the URL resolves to the proper icon image for your native ad type. Will contain a secure URL (HTTPS/SSL) if the auction is secure. |
main_media | array of objects | The main content that will appear in the body of the native ad. For now, we only support images and only one image can be associated with a native creative. For more information, see Main Media below. |
sponsored | string | The brand name that the user should associate with this creative. |
cta | string | The "call to action" text of the ad, e.g., "Download now" . |
rating | object | If the advertisement is for an app, this will display the app's rating in the relevant app store. Note that the rating is provided by the advertiser. We do not directly pull ratings from app stores. |
click_url | string | The destination URL that will open if the user clicks the ad. Note that this URL could launch an app on a device. |
click_fallback_url | string | A fallback web URL to be used if the deep link provided in the click_url is not supported on the device. For mobile inventory only. |
custom_key_values | array of objects | Some sellers allow the buyer to pass a list of custom key/value pairs. For more information, see Custom Key Values below. |
Main Media
Name | Type | Description |
---|---|---|
width | int | The width of the main native ad media. |
height | int | The height of the main native ad media. |
media_url | string | The URL from which the media can be downloaded. |
media_url_secure | string | Like media_url , but with SSL. |
There can only be one main_media object associated with a native creative.
Custom Key Values
Name | Type | Description |
---|---|---|
custom_key | string | A seller-defined key string. |
custom_value | string | A seller-defined value string. |
Click Trackers
Name | Type | Description |
---|---|---|
click_tracker_url | string | A third-party click tracking URL. |
Impression Trackers
Name | Type | Description |
---|---|---|
impression_tracker_url | string | A third-party impression tracking URL. |
impression_tracker_url_secure | string | A third-party impression tracking URL (that uses SSL) |
Native Attribute
The native_attribute
object contains the following fields. For more information, see Adding a native creative - new in Examples .
Field | Type | Description |
---|---|---|
link | object | URLs associated with the native creative. See Link below for details. |
image_trackers | array of objects | A list of third-party impression tracking URLs intended to be used with native creatives. For more information, see Image Trackers below. |
javascript_trackers | array of objects | A list of third-party impression tracking URLs. For more information, see Javascript Trackers below. |
data_assets | array of objects | Attributes of the native creative. See Data Assets below for more details. |
image_assets | array of objects | Attributes of each individual image. See Image Assets for more details. |
privacy_url | string | If support was indicated in the request, URL of a page informing the user about the buyer's targeting activity. AppNexus does not provide a default privacy link. |
Link
The link
object contains the landing page URL, fallback URL and Trackers associated with the native creative. The link
object is required for native attribute.
The link
object includes the following fields:
Field | Type | Description | Required On |
---|---|---|---|
url | string | The landing page of the native creative. | |
fallback_url | string | A backup url if the main deeplink url is not supported. |
|
trackers | array of objects | A list of third-party tracking URLs intended to be used with native creatives. See Trackers below for more details. |
All native creatives are submitted for secure auditing by default.
- If the secure url has not been specified for any tracker (image trackers, javascript trackers, and creative image asset trackers), secure audit is disabled for that creative.
- If the secure URL has not been specified, but URL is prefixed with `https`, the creative will be submitted for secure audit.
Trackers
Field | Type | Description |
---|---|---|
url | string | A third-party tracking URL. |
url_secure | string | (optional) A secure third-party tracking URL. |
Image Trackers
Name | Type | Description |
---|---|---|
url | string | A third-party impression tracking URL. |
url_secure | string | A third-party impression tracking URL (that uses SSL) |
Javascript Trackers
Name | Type | Description |
---|---|---|
url | string | A third-party javascript tracking URL. |
url_secure | string | A third-party javascript tracking URL (that uses SSL) |
Data Assets
The data_assets
object includes the following fields:
Field | Type | Description |
---|---|---|
data_type | string | The asset type for the native creative. Possible values:
|
value | string | The description of the
|
Image Assets
The image_assets
object includes the following fields:
Field | Type | Description |
---|---|---|
image_type | string | The format of the image. Possible values include:
|
media_asset_id | int | The id of the media asset. Required for hosted native creatives. if |
creative_asset_image | object | The object containing details of the creative asset. Required for third-party native creatives. See details in Creative Asset Image below. |
Creative Asset Image
Field | Type | Description |
---|---|---|
url | string | The landing page url of the image. |
url_secure | string | The secure landing page url of the image. |
width | int | The width of the image. Value must be > 0 |
height | int | The height of the image. Value must be > 0 |
Pixels
You use this array to add AppNexus-approved and custom pixels to a creative. You can add up to five pixels for a creative.
AppNexus-approved pixels are from trusted, commonly-used providers. Most of them do not cause the creative to be resubmitted for audit. To add an AppNexus-approved pixel to a creative, you need to pass only the pixel_template_id and the number of params that the pixel requires. See the Adding an AppNexus-approved pixel to a creative example below for further guidance. Note that you can use the Pixel Template Service to get information about these pixels, including whether or not they trigger re-audit.
Custom pixels are defined by you and do cause the creative to be resubmitted for audit. To add a custom pixel, you need to pass only the format and, depending on the format, the content or url. See the Adding a custom pixel to a creative example below for further guidance.
When you make a PUT call to update the pixels array, the array is completely overwritten with the information in the JSON-formatted file. Therefore, if the array already includes pixels, be sure to include those pixels in the JSON-formatted file as well.
Field | Type | Description | ||
---|---|---|---|---|
id | int | Read-only. The AppNexus-assigned ID of the pixel array. You will associate pixels via the pixel_template_id, content, or URL fields listed below. | ||
pixel_template_id | int | The ID of the AppNexus-approved pixel. You can use the Pixel Template Service to get this ID. | ||
param_1 | string | For AppNexus-approved pixel: The value for the first parameter in the pixel content or URL. To find out how many parameters are required for an AppNexus-approved pixel, use the Pixel Template Service. | ||
param_2 | string | For AppNexus-approved pixel: The value for the second parameter in the pixel content or URL. | ||
param_3 | string | For AppNexus-approved pixel: The value for the third parameter in the pixel content or URL. | ||
param_4 | string | For AppNexus-approved pixel: The value for the fourth parameter in the pixel content or URL. | ||
param_5 | string | For AppNexus-approved pixel: The value for the fifth parameter in the pixel content or URL. | ||
format | enum | The format of the pixel. Possible values: "raw-js", "url-html", "url-js", or "url-image". | ||
content | string (255) | If the pixel format is "raw-js", the HTML or JavaScript content to serve with the creative. | ||
secure_content | string (255) | If the pixel format is "raw-js", the HTML or JavaScript content to serve with the creative on a secure (HTTPS) ad call. | ||
url | string (255) | If the pixel format is "url-html", "url-js", "url-image", or "raw-url", the URL of the HTML, JavaScript, or Image pixel to serve with the creative. | ||
secure_url | string (255) | If the pixel format is "url-html", "url-js", "url-image", or "raw-url", the URL of the HTML, JavaScript, or Image pixel to serve with the creative on a secure (HTTPS) call. |
Pop Values
The pop_values fields are deprecated, and ignored/not used by our systems.
These fields should be included in a "pop_values" array within the creative JSON. Please see below for an example.
Field | Type (Length) | Description | Default | Required On |
---|---|---|---|---|
pop_window_maximize | Boolean | If true, the publisher's tag should maximize the window. Only relevant for creatives with format "url-html" and "url-js". If pop_window_maximize is set to true, then neither "height" nor "width" should be set on the creative. | false | |
pop_is_tag_initiated | Boolean | If true, the creative's tag will initiate the pop. If false, then the AppNexus Impression Bus will initiate the pop. | false | |
pop_window_title | string (255) | The title of the popped window. Only applies to pops with pop_is_tag_initiated set to false. Not guaranteed to be supported in all browsers | Network name | |
pop_statusbar | Boolean | If true, a status bar is shown in the popped window. Only applies to pops with pop_is_tag_initiated set to false. Not guaranteed to be supported in all browsers. | true | |
pop_menubar | Boolean | If true, a menu bar is shown in the popped window. Only applies to pops with pop_is_tag_initiated set to false. Not guaranteed to be supported in all browsers. | true | |
pop_resizable | Boolean | If true, the popped window is resizable. Only applies to pops with pop_is_tag_initiated set to false. Not guaranteed to be supported in all browsers. | true | |
pop_scrollbars | Boolean | If true, scroll bars are shown in the popped window. Only applies to pops with pop_is_tag_initiated set to false. Not guaranteed to be supported in all browsers. | true | |
pop_toolbar | Boolean | If true, a toolbar is shown in the popped window. Only applies to pops with pop_is_tag_initiated set to false. Not guaranteed to be supported in all browsers | true | |
pop_addressbar | Boolean | If true, an address bar is shown in the popped window. Only applies to pops with pop_is_tag_initiated set to false. Not guaranteed to be supported in all browsers | true |
Segments
These fields will be included in the Segments array:
Field | Type | Description | Required on |
---|---|---|---|
id | int | The ID of the segment. | POST, PUT |
segment_id | int | The ID of the segment. This field contains the same information as the | |
action | enum | The action taken by users that will add them to the segment. Possible values: "add on view" or "add on click". | POST, PUT |
name | string | The segment's name. |
Status
Name | Type | Description | Default | Required on |
---|---|---|---|---|
user_ready | boolean | The status of the creative set by the user describing if the creative is ready to serve or not. Possible values: "true" or "false" | true |
|
hosted_assets_association_complete | boolean / null | Read-only. Status of the creative uploaded by AppNexus' internal systems. Possible values: "true" or "false" for hosted creatives and "null" for third-party creatives. |
Third-party Pixels
The thirdparty_pixels array contains the fields in the table below. These fields, except for id
, are read-only. Use this service to update the id
of a third-party pixel or attach third-party pixels to individual creatives.
Field | Type | Description | Required on |
---|---|---|---|
id | int | The pixel's ID. | PUT |
name | string | Read-only. The full name of the pixel. | |
active | Boolean | Read-only. The current status of the pixel (true = active). | |
audit_status | string | Read-only. Audit status of the pixel. |
First Run / Last Run
To include the first_run
and last_run
fields in a GET response, pass flight_info=true
in the query string. You can also filter for creatives based on when they first and last served, as follows:
Retrieve only creatives that have never served
Retrieve only creatives that first served on or after a specific date
Retrieve only creatives that first served on or before a specific date
Retrieve only creatives first served within a specific date range
Retrieve only creatives that last served on or after a specific date
Retrieve only creatives that last served on or before a specific date
Retrieve only creatives that last served within a specific date range
Stats
The stats
object has been deprecated (as of October 17, 2016). Use the Report Service to obtain statistical information instead.
Changes That Cause Re-Audit
Once a creative has passed AppNexus audit (audit_status is "audited"), changing any of the following fields causes the creative to be resubmitted for audit (allow_audit is set to "pending"):
- width
- height
- content
- media_url
- click_url
- template
- custom_macros
- media_subtypes
- language
- categories
- technical_attributes
- brand_id
- pixel_url
- pixels (if adding or removing a custom pixel or an AppNexus-approved pixel)
- text_title (if text creative)
- text_description (if text creative)
- text_display_url (if text creative)
- pop_window_maximize (if pop creative)
- pop_is_tag_initiated (if pop creative and changing from false to true)
- video_attribute
- media_assets
Also, if the audit_status is "no_audit", changing allow_audit from "false" to "true" causes the creative to be resubmitted for AppNexus audit.
Creative Macros
AppNexus has predefined some macros that can be used within the creative's media_url
, content
, click_url
, and pixel_url
fields. For a complete list, see Creative Macros.
Click Tracking Example:
Examples
Adding a banner image creative (hosted)
Add a mobile banner image creative (hosted)
Adding a banner flash creative (hosted)
Adding a banner flash creative (third-party URL)
Adding a MediaMind expandable creative (third-party URL)
Adding a Pointroll expandable creative (third-party HTML tag)
Adding a popup image creative (third-party URL)
Adding a popunder image creative (third-party URL)
Adding an in-banner video (third-party video file)
Adding an in-banner video (third-party XML file)
Adding a creative that uses a custom rendering template
Adding a secure creative
Submitting a creative for priority audit
Canceling a creative audit
Viewing audit stats for all creatives
Adding an AppNexus-approved pixel to a creative
Adding a custom pixel to a creative
Adding a third-party pixel to a creative
Adding a creative (third-party HTML tag)
Adding a native ad creative
Adding a native creative - new