REST Resource: placements

  • The Placement resource defines the properties of an ad placement, including its ID, associated advertiser and campaign, name, size, compatibility, pricing, and tag settings.

  • Video settings for a placement include configurations for companion creatives, transcoding, skippability, orientation, OBA icons, and duration.

  • Various tag formats can be generated for a placement, such as standard, iframe, javascript, and tracking tags.

  • Additional settings allow for opting out of video active view, ad blocking, and tag wrapping, and also include conversion domain overrides and YouTube integration settings.

  • The document also provides information on the different methods available for interacting with Placement resources, such as generating tags, getting, inserting, listing, patching, and updating placements.

Resource: Placement

Contains properties of a placement.

JSON representation 
{
  "id": string,
  "accountId": string,
  "subaccountId": string,
  "advertiserId": string,
  "campaignId": string,
  "name": string,
  "siteId": string,
  "keyName": string,
  "directorySiteId": string,
  "paymentSource": enum (PaymentSource),
  "compatibility": enum (Compatibility),
  "size": {
    object (Size)
  },
  "kind": string,
  "paymentApproved": boolean,
  "pricingSchedule": {
    object (PricingSchedule)
  },
  "placementGroupId": string,
  "primary": boolean,
  "tagSetting": {
    object (TagSetting)
  },
  "tagFormats": [
    enum (PlacementTagFormat)
  ],
  "contentCategoryId": string,
  "placementStrategyId": string,
  "lookbackConfiguration": {
    object (LookbackConfiguration)
  },
  "comment": string,
  "status": enum (PlacementStatus),
  "publisherUpdateInfo": {
    object (LastModifiedInfo)
  },
  "lastModifiedInfo": {
    object (LastModifiedInfo)
  },
  "sslRequired": boolean,
  "idDimensionValue": {
    object (DimensionValue)
  },
  "advertiserIdDimensionValue": {
    object (DimensionValue)
  },
  "campaignIdDimensionValue": {
    object (DimensionValue)
  },
  "siteIdDimensionValue": {
    object (DimensionValue)
  },
  "directorySiteIdDimensionValue": {
    object (DimensionValue)
  },
  "placementGroupIdDimensionValue": {
    object (DimensionValue)
  },
  "externalId": string,
  "createInfo": {
    object (LastModifiedInfo)
  },
  "videoSettings": {
    object (VideoSettings)
  },
  "videoActiveViewOptOut": boolean,
  "vpaidAdapterChoice": enum (VpaidAdapterChoice),
  "adBlockingOptOut": boolean,
  "additionalSizes": [
    {
      object (Size)
    }
  ],
  "wrappingOptOut": boolean,
  "partnerWrappingData": {
    object (MeasurementPartnerWrappingData)
  },
  "activeStatus": enum (PlacementActiveStatus),
  "conversionDomainOverride": {
    object (PlacementConversionDomainOverride)
  },
  "adServingPlatformId": string,
  "siteServed": boolean,
  "allowOnYoutube": boolean,
  "youtubeSettings": {
    object (YoutubeSettings)
  }
}
Fields
id

string (int64 format)

ID of this placement. This is a read-only, auto-generated field.
accountId

string (int64 format)

Account ID of this placement. This field can be left blank.
subaccountId

string (int64 format)

Subaccount ID of this placement. This field can be left blank.
advertiserId

string (int64 format)

Advertiser ID of this placement. This field can be left blank.
campaignId

string (int64 format)

Campaign ID of this placement. This field is a required field on insertion.
name

string

Name of this placement.This is a required field and must be less than or equal to 512 characters long.
siteId

string (int64 format)

Site ID associated with this placement. On insert, you must set either this field or the directorySiteId field to specify the site associated with this placement. This is a required field that is read-only after insertion.
keyName

string

Key name of this placement. This is a read-only, auto-generated field.
directorySiteId

string (int64 format)

Directory site ID of this placement. On insert, you must set either this field or the siteId field to specify the site associated with this placement. This is a required field that is read-only after insertion.
paymentSource

enum (PaymentSource)

Payment source for this placement. This is a required field that is read-only after insertion.
compatibility

enum (Compatibility)

Placement compatibility. DISPLAY and DISPLAY_INTERSTITIAL refer to rendering on desktop, on mobile devices or in mobile apps for regular or interstitial ads respectively. APP and APP_INTERSTITIAL are no longer allowed for new placement insertions. Instead, use DISPLAY or DISPLAY_INTERSTITIAL. IN_STREAM_VIDEO refers to rendering in in-stream video ads developed with the VAST standard. This field is required on insertion.
size

object (Size)

Size associated with this placement. When inserting or updating a placement, only the size ID field is used. This field is required on insertion.
kind

string

Identifies what kind of resource this is. Value: the fixed string "dfareporting#placement".
paymentApproved

boolean

Whether payment was approved for this placement. This is a read-only field relevant only to publisher-paid placements.
pricingSchedule

object (PricingSchedule)

Pricing schedule of this placement. This field is required on insertion, specifically subfields startDate, endDate and pricingType.
placementGroupId

string (int64 format)

ID of this placement's group, if applicable.
primary

boolean

Whether this placement is the primary placement of a roadblock (placement group). You cannot change this field from true to false. Setting this field to true will automatically set the primary field on the original primary placement of the roadblock to false, and it will automatically set the roadblock's primaryPlacementId field to the ID of this placement.
tagSetting

object (TagSetting)

Tag settings for this placement.
tagFormats[]

enum (PlacementTagFormat)

Tag formats to generate for this placement. This field is required on insertion.

Acceptable values are:

  • "PLACEMENT_TAG_STANDARD"
  • "PLACEMENT_TAG_IFRAME_JAVASCRIPT"
  • "PLACEMENT_TAG_IFRAME_ILAYER"
  • "PLACEMENT_TAG_INTERNAL_REDIRECT"
  • "PLACEMENT_TAG_JAVASCRIPT"
  • "PLACEMENT_TAG_INTERSTITIAL_IFRAME_JAVASCRIPT"
  • "PLACEMENT_TAG_INTERSTITIAL_INTERNAL_REDIRECT"
  • "PLACEMENT_TAG_INTERSTITIAL_JAVASCRIPT"
  • "PLACEMENT_TAG_CLICK_COMMANDS"
  • "PLACEMENT_TAG_INSTREAM_VIDEO_PREFETCH"
  • "PLACEMENT_TAG_INSTREAM_VIDEO_PREFETCH_VAST_3"
  • "PLACEMENT_TAG_INSTREAM_VIDEO_PREFETCH_VAST_4"
  • "PLACEMENT_TAG_TRACKING"
  • "PLACEMENT_TAG_TRACKING_IFRAME"
  • "PLACEMENT_TAG_TRACKING_JAVASCRIPT"
contentCategoryId

string (int64 format)

ID of the content category assigned to this placement.
placementStrategyId

string (int64 format)

ID of the placement strategy assigned to this placement.
lookbackConfiguration

object (LookbackConfiguration)

Lookback window settings for this placement.
comment

string

Comments for this placement.
status

enum (PlacementStatus)

Third-party placement status.
publisherUpdateInfo

object (LastModifiedInfo)

Information about the last publisher update. This is a read-only field.
lastModifiedInfo

object (LastModifiedInfo)

Information about the most recent modification of this placement. This is a read-only field.
sslRequired

boolean

Whether creatives assigned to this placement must be SSL-compliant.
idDimensionValue

object (DimensionValue)

Dimension value for the ID of this placement. This is a read-only, auto-generated field.
advertiserIdDimensionValue

object (DimensionValue)

Dimension value for the ID of the advertiser. This is a read-only, auto-generated field.
campaignIdDimensionValue

object (DimensionValue)

Dimension value for the ID of the campaign. This is a read-only, auto-generated field.
siteIdDimensionValue

object (DimensionValue)

Dimension value for the ID of the site. This is a read-only, auto-generated field.
directorySiteIdDimensionValue

object (DimensionValue)

Dimension value for the ID of the directory site. This is a read-only, auto-generated field.
placementGroupIdDimensionValue

object (DimensionValue)

Dimension value for the ID of the placement group. This is a read-only, auto-generated field.
externalId

string

External ID for this placement.
createInfo

object (LastModifiedInfo)

Information about the creation of this placement. This is a read-only field.
videoSettings

object (VideoSettings)

A collection of settings which affect video creatives served through this placement. Applicable to placements with IN_STREAM_VIDEO compatibility.
videoActiveViewOptOut

boolean

Whether Verification and ActiveView are disabled for in-stream video creatives for this placement. The same setting videoActiveViewOptOut exists on the site level -- the opt out occurs if either of these settings are true. These settings are distinct from DirectorySites.settings.activeViewOptOut or Sites.siteSettings.activeViewOptOut which only apply to display ads. However, Accounts.activeViewOptOut opts out both video traffic, as well as display ads, from Verification and ActiveView.
vpaidAdapterChoice

enum (VpaidAdapterChoice)

VPAID adapter setting for this placement. Controls which VPAID format the measurement adapter will use for in-stream video creatives assigned to this placement.

Note: Flash is no longer supported. This field now defaults to HTML5 when the following values are provided: FLASH, BOTH.
adBlockingOptOut

boolean

Whether this placement opts out of ad blocking. When true, ad blocking is disabled for this placement. When false, the campaign and site settings take effect.
additionalSizes[]

object (Size)

Additional sizes associated with this placement. When inserting or updating a placement, only the size ID field is used.
wrappingOptOut

boolean

Whether this placement opts out of tag wrapping.
partnerWrappingData

object (MeasurementPartnerWrappingData)

Measurement partner provided settings for a wrapped placement.
activeStatus

enum (PlacementActiveStatus)

Whether this placement is active, inactive, archived or permanently archived.
conversionDomainOverride

object (PlacementConversionDomainOverride)

Optional. Conversion domain overrides for a placement.
adServingPlatformId

string (int64 format)

Optional. Ad serving platform ID to identify the ad serving platform used by the placement. Measurement partners can use this field to add ad-server specific macros. Possible values are:

  • 1, Adelphic
  • 2, Adform
  • 3, Adobe
  • 4, Amobee
  • 5, Basis (Centro)
  • 6, Beeswax
  • 7, Amazon
  • 8, DV360 (DBM)
  • 9, Innovid
  • 10, MediaMath
  • 11, Roku OneView DSP
  • 12, TabMo Hawk
  • 13, The Trade Desk
  • 14, Xandr Invest DSP
  • 15, Yahoo DSP
  • 16, Zeta Global
  • 17, Scaleout
  • 18, Bidtellect
  • 19, Unicorn
  • 20, Teads
  • 21, Quantcast
  • 22, Cognitiv
  • 23, AdTheorent
  • 24, DeepIntent
  • 25, Pulsepoint
siteServed

boolean

Optional. Whether the ads in the placement are served by another platform and CM is only used for tracking or they are served by CM. A false value indicates the ad is served by CM.
allowOnYoutube

boolean

Optional. Whether the placement is enabled for YouTube integration.
youtubeSettings

object (YoutubeSettings)

Optional. YouTube settings for the placement. The placement must be enabled for YouTube to use this field.

PaymentSource

Payment source for Placement If you change this enum make sure you keep the FE enum XFA.Placement.PaymentSourcesEnum in java/com/google/ads/xfa/site/app/models/placement.js in sync.

Enums
PLACEMENT_AGENCY_PAID
PLACEMENT_PUBLISHER_PAID

PlacementTagFormat

Enums
PLACEMENT_TAG_STANDARD
PLACEMENT_TAG_IFRAME_JAVASCRIPT
PLACEMENT_TAG_IFRAME_ILAYER
PLACEMENT_TAG_INTERNAL_REDIRECT
PLACEMENT_TAG_JAVASCRIPT
PLACEMENT_TAG_INTERSTITIAL_IFRAME_JAVASCRIPT
PLACEMENT_TAG_INTERSTITIAL_INTERNAL_REDIRECT
PLACEMENT_TAG_INTERSTITIAL_JAVASCRIPT
PLACEMENT_TAG_CLICK_COMMANDS
PLACEMENT_TAG_INSTREAM_VIDEO_PREFETCH
PLACEMENT_TAG_TRACKING
PLACEMENT_TAG_TRACKING_IFRAME
PLACEMENT_TAG_TRACKING_JAVASCRIPT
PLACEMENT_TAG_INSTREAM_VIDEO_PREFETCH_VAST_3
PLACEMENT_TAG_IFRAME_JAVASCRIPT_LEGACY
PLACEMENT_TAG_JAVASCRIPT_LEGACY
PLACEMENT_TAG_INTERSTITIAL_IFRAME_JAVASCRIPT_LEGACY
PLACEMENT_TAG_INTERSTITIAL_JAVASCRIPT_LEGACY
PLACEMENT_TAG_INSTREAM_VIDEO_PREFETCH_VAST_4
PLACEMENT_TAG_TRACKING_THIRD_PARTY_MEASUREMENT

PlacementStatus

Placement status for placements.

Enums
PENDING_REVIEW Placement is not yet reviewed by publisher.
PAYMENT_ACCEPTED Placement Ad Serving fee is accepted by publisher
PAYMENT_REJECTED Placement Ad Serving fee is rejected by publisher
ACKNOWLEDGE_REJECTION Advertisers has accepted rejection of placement ad serving fee. This will suppress future notification on DDMM UI
ACKNOWLEDGE_ACCEPTANCE Advertisers has accepted acceptance of placement ad serving fee. This will suppress future notification on DDMM UI
DRAFT Advertisers is still working on placement not yet ready for Publisher review; default status for pub-paid placements

VideoSettings

Video Settings

JSON representation 
{
  "companionSettings": {
    object (CompanionSetting)
  },
  "transcodeSettings": {
    object (TranscodeSetting)
  },
  "skippableSettings": {
    object (SkippableSetting)
  },
  "orientation": enum (PlacementOrientation),
  "kind": string,
  "obaSettings": {
    object (ObaIcon)
  },
  "obaEnabled": boolean,
  "durationSeconds": integer,
  "publisherSpecificationId": string
}
Fields
companionSettings

object (CompanionSetting)

Settings for the companion creatives of video creatives served to this placement.
transcodeSettings

object (TranscodeSetting)

Settings for the transcodes of video creatives served to this placement. If this object is provided, the creative-level transcode settings will be overridden.
skippableSettings

object (SkippableSetting)

Settings for the skippability of video creatives served to this placement. If this object is provided, the creative-level skippable settings will be overridden.
orientation

enum (PlacementOrientation)

Orientation of a video placement. If this value is set, placement will return assets matching the specified orientation.
kind

string

Identifies what kind of resource this is. Value: the fixed string "dfareporting#videoSettings".
obaSettings

object (ObaIcon)

Settings for the OBA icon of video creatives served to this placement. If this object is provided, the creative-level OBA settings will be overridden.
obaEnabled

boolean

Whether OBA icons are enabled for this placement.
durationSeconds

integer

Duration of a video placement in seconds.
publisherSpecificationId

string (int64 format)

Publisher specification ID of a video placement. Possible values are:

  • 1, Hulu
  • 2, NBC
  • 3, CBS
  • 4, CBS Desktop
  • 5, Discovery
  • 6, VEVO HD
  • 7, VEVO Vertical
  • 8, Fox
  • 9, CW Network
  • 10, Disney
  • 11, IGN
  • 12, NFL.com
  • 13, Turner Broadcasting
  • 14, Tubi on Fox
  • 15, Hearst Corporation
  • 16, Twitch Desktop
  • 17, ABC
  • 18, Univision
  • 19, MLB.com
  • 20, MLB.com Mobile
  • 21, MLB.com OTT
  • 22, Polsat
  • 23, TVN
  • 24, Mediaset
  • 25, Antena 3
  • 26, Mediamond
  • 27, Sky Italia
  • 28, Tubi on CBS
  • 29, Spotify
  • 30, Paramount
  • 31, Max

CompanionSetting

Companion Settings

JSON representation 
{
  "companionsDisabled": boolean,
  "enabledSizes": [
    {
      object (Size)
    }
  ],
  "imageOnly": boolean,
  "kind": string
}
Fields
companionsDisabled

boolean

Whether companions are disabled for this placement.
enabledSizes[]

object (Size)

Allowlist of companion sizes to be served to this placement. Set this list to null or empty to serve all companion sizes.
imageOnly

boolean

Whether to serve only static images as companions.
kind

string

Identifies what kind of resource this is. Value: the fixed string "dfareporting#companionSetting".

TranscodeSetting

Transcode Settings

JSON representation 
{
  "enabledVideoFormats": [
    integer
  ],
  "kind": string
}
Fields
enabledVideoFormats[]

integer

Allowlist of video formats to be served to this placement. Set this list to null or empty to serve all video formats.
kind

string

Identifies what kind of resource this is. Value: the fixed string "dfareporting#transcodeSetting".

SkippableSetting

Skippable Settings

JSON representation 
{
  "skippable": boolean,
  "skipOffset": {
    object (VideoOffset)
  },
  "progressOffset": {
    object (VideoOffset)
  },
  "kind": string
}
Fields
skippable

boolean

Whether the user can skip creatives served to this placement.
skipOffset

object (VideoOffset)

Amount of time to play videos served to this placement before the skip button should appear. Applicable when skippable is true.
progressOffset

object (VideoOffset)

Amount of time to play videos served to this placement before counting a view. Applicable when skippable is true.
kind

string

Identifies what kind of resource this is. Value: the fixed string "dfareporting#skippableSetting".

PlacementOrientation

Enums
ANY
LANDSCAPE
PORTRAIT

MeasurementPartnerWrappingData

Placement tag wrapping

JSON representation 
{
  "measurementPartner": enum (MeasurementPartner),
  "linkStatus": enum (MeasurementPartnerLinkStatus),
  "wrappedTag": string,
  "tagWrappingMode": enum (TagWrappingMode)
}
Fields
measurementPartner

enum (MeasurementPartner)

Measurement partner used for wrapping the placement.
wrappedTag

string

Tag provided by the measurement partner during wrapping.
tagWrappingMode

enum (TagWrappingMode)

Measurement mode for the wrapped placement.

TagWrappingMode

Enums
NONE
BLOCKING
MONITORING
MONITORING_READ_ONLY
VIDEO_PIXEL_MONITORING
TRACKING
VPAID_MONITORING
VPAID_BLOCKING
NON_VPAID_MONITORING
VPAID_ONLY_MONITORING
VPAID_ONLY_BLOCKING
VPAID_ONLY_FILTERING
VPAID_FILTERING
NON_VPAID_FILTERING
BLOCKING_FILTERING_VPAID
BLOCKING_FILTERING_VPAID_ONLY

PlacementConversionDomainOverride

JSON representation 
{
  "conversionDomains": [
    {
      object (PlacementSingleConversionDomain)
    }
  ]
}
Fields
conversionDomains[]

object (PlacementSingleConversionDomain)

PlacementSingleConversionDomain

JSON representation 
{
  "conversionDomainId": string,
  "conversionDomainValue": string
}
Fields
conversionDomainId

string (int64 format)
conversionDomainValue

string

YoutubeSettings

Contains the YouTube settings.

JSON representation 
{
  "businessName": string,
  "businessLogoCreativeIds": [
    string
  ],
  "longHeadlines": [
    string
  ],
  "descriptions": [
    string
  ],
  "callToActions": [
    enum (CallToAction)
  ],
  "headlines": [
    string
  ]
}
Fields
businessName

string

Optional. The business name.
businessLogoCreativeIds[]

string (int64 format)

Optional. The IDs of the creatives to use for the business logo. Currently only one creative is supported.
longHeadlines[]

string

Optional. The long headlines. Currently only one long headline is supported.
descriptions[]

string

Optional. The descriptions. Currently only one description is supported.
callToActions[]

enum (CallToAction)

Optional. The call to actions. Currently only one call to action is supported.
headlines[]

string

Optional. The headlines associated with the call to actions. Currently only one headline is supported.

CallToAction

Call to action type.

Enums
CALL_TO_ACTION_UNKNOWN
CALL_TO_ACTION_LEARN_MORE
CALL_TO_ACTION_GET_QUOTE
CALL_TO_ACTION_APPLY_NOW
CALL_TO_ACTION_SIGN_UP
CALL_TO_ACTION_CONTACT_US
CALL_TO_ACTION_SUBSCRIBE
CALL_TO_ACTION_DOWNLOAD
CALL_TO_ACTION_BOOK_NOW
CALL_TO_ACTION_GET_OFFER
CALL_TO_ACTION_SHOP_NOW
CALL_TO_ACTION_VISIT_STORE
CALL_TO_ACTION_CALL_NOW
CALL_TO_ACTION_VIEW_MENU
CALL_TO_ACTION_TEST_DRIVE
CALL_TO_ACTION_SCHEDULE_NOW
CALL_TO_ACTION_BUY_NOW
CALL_TO_ACTION_DONATE_NOW
CALL_TO_ACTION_ORDER_NOW
CALL_TO_ACTION_PLAY_NOW
CALL_TO_ACTION_SEE_MORE
CALL_TO_ACTION_START_NOW
CALL_TO_ACTION_VISIT_SITE
CALL_TO_ACTION_WATCH_NOW

Methods

generatetags

 Generates tags for a placement.

get

 Gets one placement by ID.

insert

 Inserts a new placement.

list

 Retrieves a list of placements, possibly filtered.

patch

 Updates an existing placement.

update

 Updates an existing placement.