Ads

You can create and manage ads, using these fields.

Fields

The following fields are available for creating and managing ads:

Name

Description

Type

Add

Update

Campaign ID

The ID of the campaign associated with the ad.

long

required

optional

Ad Group ID

The ID of the ad group associated with the ad.

long

required

optional

Object ID

The ID of the ad.

long

N/A

required

Description

Description text displayed when your ad appears in content streams or in the other eligible native ad positions. Maximum 150 characters. Use {city}, {state}, {state_abbr}, {country} and {country_abbr} macros to add geo locations for user personalized ads. Use the {time} macro for flash sale ads.

string

required

optional

Ad Name

An optional name or tag given to the ad. Maximum limit of 255 characters.

string

optional

optional

Title

Title text when your ad appears in content streams or in the other eligible native ad positions. Maximum limit is 50 characters. Use {city}, {state}, {state_abbr}, {country} and {country_abbr} macros to add geo locations for user personalized ads. Use {time} macro for flash sale ads.

string

required

optional

Title 2

Additional title text for search and search on native ads. If you use Title + Title 2, the maximum limit is 30 characters for each line. Title 2 for standard Native only campaigns is not supported at this time.

string

required

optional

Display URL

The user-friendly URL displayed to the user. Maximum limit is 35 characters.

long

required

optional

Landing URL

The landing URL associated with the ad. The landing URL is the web address that a user is sent to after clicking on the ad. Maximum limit is 2048 characters. Use {city}, {state}, {state_abbr}, {country} and {country_abbr} macros to add geo locations for user personalized ads.

The landing URL should include the tracking params provided by the tracking partner that was specified at the campaign level for app installs.

In INSTALL_APP campaigns, use this field to input the tracking URL provided by your attribution vendor. Note that the ${PIXEL_ID} and ${PIXEL_CONTEXT} macros need to be included in the tracking URL.

Here is an example of a valid landingUrl for an app install ad: https://hastrk0.com/5034488/${PIXEL_CONTEXT}${PIXEL_ID}.

string

required

optional

Impression Tracking URL

Supported third-party impression tracking URL.

string

optional

optional

Mail Asset URL

A URL to a high-resolution image for a mail sponsored ad. This can only run on VISIT_WEB and CPC price type. Note also that the image can only be a 2MB JPEG, PNG or GIF image.

string

Optional

Optional

Ad Image URL

A valid URL for a square image in eligible native ad positions. The ideal image size is 627x627; smaller images will not be accepted.. The maximum size is 7MB. Larger images with either the same aspect ratio or with a height and width that are off the ideal dimensions by up to a combined 10% will be accepted as well as will be automatically cropped at the center. Note: This is required for Image and Video Ads

string

optional

optional

Ad HQ Image URL

A valid URL to a high resolution image that will be used in eligible native ad positions. The ideal image size is 1200x627; smaller images will not be accepted. Larger images with either the same aspect ratio or with a height and width that are off the ideal dimensions by up to a combined 10% will be accepted as well as will be automatically cropped at the center. The maximum file size is 7MB. Note: This is required for Image and Video Ads.

string

optional

optional

Ad Portrait Image URL

A valid URL to a high-resolution 720p to 1080p vertical (portrait) image that will be used in eligible mobile moments and portrait native ad positions. The ideal image size is 1080x1920 (9:16 aspect ratio); smaller images will not be accepted. Larger images with either the same aspect ratio or with a height and width that are off the ideal dimensions by up to a combined 10% will be accepted as well as will be automatically cropped at the center. The maximum file size is 7MB. Note that this is required for Portrait Image Ads, Panorama Image Ads, and Portrait Video Ads.

string

optional

optional

Ad Portrait Image BG URL

A valid URL to a high-resolution 720p to 1080p vertical (portrait) image that will be used in eligible mobile moments and portrait native ad positions as a background for native and DPA carousel ads. The ideal image size is 1080x1920 (9:16 aspect ratio); smaller images will not be accepted. Larger images with either the same aspect ratio or with a height and width that are off the ideal dimensions by up to a combined 10% will be accepted as well as will be automatically cropped at the center. The maximum file size is 7MB. Note: This will increase your supply reach for your carousel and DPA ads to mobile moments and portrait native ad positions.

string

optional

optional

Ad Panorama Image URL

A valid URL to a high-resolution horizontal ultra-wide 16:9 image that will be used in eligible 360 panorama moments native ad positions. The ideal image size is 2276x1280 (max of 6826x1280 and up to 48:9 aspect ratio); smaller images will not be accepted. Larger images with either the same aspect ratio or with a height and width that are off the ideal dimensions by up to a combined 10% will be accepted as well as will be automatically cropped at the center. The maximum file size is 7MB. Note: This is required for Panorama 360 Image Ads.

string

optional

optional

Ad Primary Video URL

A valid URL for video ads that will be used in eligible native ad positions. This can be directly uploaded via Bulk by passing the URL location which Native will parse and upload to the Native ad system. Note: This is required for Video Ads running as PromoteBrand or AppInstall campaigns. The technical requirements for video are:

  • Formats: .mp4 .m4v or .mov

  • File Size: 1GB maximum

  • Duration: 5 seconds minimum, 30 seconds maximum for App Install campaigns, 5 minutes maximum for Promote Brand, Visit Web and Mail Sponsored campaigns.

  • Aspect Ratio: Minimum 480x360p (4:3) or 480x270 (16:9). Recommended 640x480 (4:3) or 640x360 (16:9)

  • Video Bitrate: 300kbps. Recommended 500kbps.

  • Audio Quality: If the video has audio, then it must have 2 channel stereo and minimum 32kbps. Recommended 64kbps.

string

optional

optional

Ad Portrait Video URL

A valid URL for mobile moments (portrait) video ads that will be used in eligible mobile moments and portrait native ad positions. This can be directly uploaded via Bulk by passing the URL location which Native will parse and upload to the Native ad system. Note: This is required for Portrait Video Ads running in moments and portrait supply. The technical requirements for video are:

  • Formats: .mp4 .m4v or .mov

  • File Size: 1GB maximum

  • Duration: 5 seconds minimum, 30 seconds maximum for App Install campaigns, 5 minutes maximum for Promote Brand, Visit Web and Mail Sponsored campaigns.

  • Aspect Ratio:9:16, 720p to 1080p

  • Video Bitrate: 750kbps.

  • Audio Quality: If the video has audio, then it must have 2 channel stereo and minimum 62kbps.

string

optional

optional

Status

The status of the ad. Valid values are:

  • Active

  • Paused

Ads are defaulted to Active if no status is provided upon creation.

string

optional

optional

Call To Action Text

Call to action buttons are used to help drive users to take specific actions. See the Call to action section in the API guide for a list of available values.

enum

optional

optional

Video Completed View Tracking URL

Applies only to INSTALL_APP video ads and tracks when your video was played to 100% of its length. Only one Video Completed View Tracking URL is supported per ad.

string

optional

optional

Video Click Tracking URL

Applies only to INSTALL_APP video ads and tracks when the install button was clicked. Only one Video Click Tracking URL is supported per ad.

string

optional

optional

Ad Thumbnail Image URL

A URL to a high-resolution image for an ad. The original image will be scaled to 180 x 180 pixels and can only be a JPEG or PNG image. Required for ads under MailSponsored campaigns.

string

optional

optional

Video Caption URL

Optional video caption file url to accompany the video url provided for video ads. Maximum url length is 1024 characters. The technical requirements for captions are:

  • Formats: .vtt or .srt

  • Maximum File Size: 1MB

  • Maximum 3 lines of text per caption time entry/stamp in the file.

string

optional

optional

Video Autoloop

Optional video autoloop flag to accompany the video url provided for ad. If set to true, the video will autoloop continuously.

boolean

optional. Default: false

optional

Video Scrolling

Optional video scrolling flag to accompany the video url provided for ad. If set to true, the video will utilize mobile swiping for playback in supported native positions.

boolean

optional. Default: false

optional

Video Preview Start Time

Optional start time (in seconds) to start the video clip or preview for Mail Trailer Video Ad. Default is 0 sec. The duration of the video clip will always be for 5 sec.

integer

Optional. Default is 0 sec for all video ads and video trailer ads.

optional

Is Ad Template

The ad template for DPA.

boolean

optional

optional.

Ad Asset Styles

A key-value list of styles to represent additional ad styles - call to action styling and portrait template container colors when an image, video, or carousel ad gets rendered as a single image upgraded to portrait moments ad.

Possible values are

  • callToActionText, supporting only bgColor (background color) for the call to action button. Valid options are:

    • 000000 (black)

    • FFFFFF (white)

    • B50003 (red)

    • 2D6400 (green)

    • 005194 (blue)

  • container, supporting only bgColorGradientLinear1 and bgColorGradientLinear2 for background gradient color palette and textColor for title/description text coloring.

  • Format is for the color values in the container are: rgb({d},{d},{d}) - Each digit must be an integer between 0 and 255. - Hex code not including the hashtag (e.g. 99CC00). It must be a valid hex triplet six characters long.

  • container.bgColorGradientLinear1 and container.bgColorGradientLinear2 and their parent styles are all optional. However, if one is provided and the other is left blank, then the blank one should be filled in to have the same value as the provided one.

  • Both colors must maintain a given contrast ratio with either white or black (one or the other - one color maintaining with white and the other maintaining with black is not allowed).

  • Both colors must also maintain a given contrast ratio with callToActionText.bgColor (for now, 2:1, as this will allow all CTA background colors to work against both system gray and system black) - for example, if red is selected as the button color, then the background should not also be some shade of red.

  • Background colors cannot both be white (FFFFFF) - one can be white, but not both.

  • If the background colors result in a generated text color of black and the user has provided a callToActionText.bgColor value of FFFFFF (white), input will get rejected (a white button, which will be a transparent button with a white outline and white text, cannot mix with black ad text).

Example:

callToActionText.bgColor=FFFFFF, container.bgColorGradientLinear1=000000, container.bgColorGradientLinear2=000000, container.textColor=FFFFFF

Key-value pairs

optional

optional.

End Date

The end date associated with a flash sale ad. Format: yyyy/mm/dd HH:mm:ss {timezone}. Both the countdown date and the timezone are combined in the same CSV value. For example: 2018/04/15 13:30:00 America/Los_Angeles. Note the space between the date and the timezone. Use delete_value to erase the flash sale configuration.

string

required

optional

Editorial Status

The editorial status of the ad. Valid values are:

  • Not reviewed

  • Pending review

  • Approved

  • Rejected

enum

N/A read-only

N/A read-only

Rejection Reasons

The list of reasons the ad was editorially rejected due to policy. The reasons are separated by a pipe character symbol, like this: ‘|’.

string

N/A read-only

N/A read-only

Optimize Assets

Supported only for carousel ads. When specified as TRUE, the best-performing card will be displayed first.

boolean

optional

optional

Run as Single Image

Supported only for carousel ads. When specified as TRUE, the carousel ad is allowed to run as a single image ad in some supply.

boolean

optional

optional

Countdown Prefix

Supported only for carousel ads. Valid values are:

  • Starts in

  • Sale starts in

  • Launches in

  • Ends in

  • Sale ends in

  • Offer ends in

  • Deadline in

  • Deal ends in

  • Expires in

  • Time left

  • Premieres in

enum

optional

optional

Create an Ad

The following example contains the fields required for creating an ad. All other fields in this spreadsheet are blank and are not shown:

Action

Object Type

Campaign ID

Ad Group ID

Title

Description

Display URL

Landing URL

Sponsored By

Add

Ad

75614

564

Your Title

Your ad’s description

www.displayurl.com

www.landingurl.com

Company Name

Update an Ad

When updating an ad, the only required fields are Action, Object Type, Object ID and the fields you would like to update. The following example shows updating the title for an ad with an ID of 4201 other fields in this spreadsheet are blank and are not shown:

Action

Object Type

Object ID

Title

Update

Ad

4201

The new title for your ad.