AdGroup Data Object

 

Defines an ad group.

<xs:complexType name="AdGroup">
  <xs:sequence>
    <xs:element name="AdDistribution" type="tns:AdDistribution" nillable="true" minOccurs="0"/>
    <xs:element name="AdRotation" type="tns:AdRotation" nillable="true" minOccurs="0"/>
    <xs:element xmlns:q16="http://schemas.datacontract.org/2004/07/Microsoft.AdCenter.Advertiser.CampaignManagement.Api.DataContracts.V11" minOccurs="0" name="BiddingScheme" nillable="true" type="q16:BiddingScheme"/>
    <xs:element name="ContentMatchBid" type="tns:Bid" nillable="true" minOccurs="0"/>
    <xs:element name="EndDate" type="tns:Date" nillable="true" minOccurs="0"/>
    <xs:element xmlns:q17="http://schemas.datacontract.org/2004/07/System.Collections.Generic" minOccurs="0" name="ForwardCompatibilityMap" nillable="true" type="q17:ArrayOfKeyValuePairOfstringstring"/>
    <xs:element name="Id" type="xs:long" nillable="true" minOccurs="0"/>
    <xs:element name="Language" type="xs:string" nillable="true" minOccurs="0"/>
    <xs:element name="Name" type="xs:string" nillable="true" minOccurs="0"/>
    <xs:element name="NativeBidAdjustment" type="xs:int" nillable="true" minOccurs="0"/>
    <xs:element name="Network" type="tns:Network" nillable="true" minOccurs="0"/>
    <xs:element name="PricingModel" type="tns:PricingModel" nillable="true" minOccurs="0"/>
    <xs:element name="RemarketingTargetingSetting" type="tns:RemarketingTargetingSetting" nillable="true" minOccurs="0"/>
    <xs:element name="SearchBid" type="tns:Bid" nillable="true" minOccurs="0"/>
    <xs:element name="Settings" type="tns:ArrayOfSetting" nillable="true" minOccurs="0"/>
    <xs:element name="StartDate" type="tns:Date" nillable="true" minOccurs="0"/>
    <xs:element name="Status" type="tns:AdGroupStatus" nillable="true" minOccurs="0"/>
    <xs:element name="TrackingUrlTemplate" type="xs:string" nillable="true" minOccurs="0"/>
    <xs:element xmlns:q18="http://schemas.datacontract.org/2004/07/Microsoft.AdCenter.Advertiser.CampaignManagement.Api.DataContracts.V11" minOccurs="0" name="UrlCustomParameters" nillable="true" type="q18:CustomParameters"/>
  </xs:sequence>
</xs:complexType>

ElementDescriptionData Type
AdDistributionDetermines whether the ads within this ad group will be displayed on the content distribution channel, search distribution channel, or both.

Note: The content ad distribution channel is not supported for ad groups in Bing Shopping campaigns or Dynamic Search Ads campaigns.

IMPORTANT: Bing Ads no longer serves ads on the content network and you are no longer able to set the Content ad distribution. If you try to add or update an ad group with ad distribution set only to Content, the CampaignServiceAdGroupMediumNotAllowedForDistributionChannel error will be returned. If you try to add or update an ad group with ad distribution set to both Search and Content, the operation will succeed, however the ad distribution will be stored as Search only.

Starting on November 30th 2017, Bing Ads will delete the remaining Content ad groups. If you want to keep the ad groups, you must set the ad distribution to Search only before November 30th. If you try to add or update content bid in ad group settings the CampaignServiceCannotSetContentBidOnAdGroup error will be returned. Content match type keywords will also be deleted. If you try to add or update a keyword match type to content the CampaignServiceInvalidMatchTypes error will be returned.

Possible values are Search and Content. You may include multiple values as flags. How you specify multiple flags depends on the programming language that you use. For example, C# treats these values as flag values and Java treats them as an array of strings. The SOAP element should include a string that contains a space-delimited list of values for example, <AdDistribution>Search Content</AdDistribution>.

If you include the Search distribution, then by default the ad group's Network will be set to OwnedAndOperatedAndSyndicatedSearch. You can change the default network as described below.

For more information, see What's the difference between the search and content networks? and About ad distribution.

Add: Required
Update: Optional. If no value is specified on update, this Bing Ads setting is not changed.
AdDistribution
AdRotationDetermines how often you'd like the ads in your ad group to show in relation to one another. If you have multiple ads within an ad group, your ads will rotate because no more than one ad from your account can show at a time.

Note: This feature is not supported for ad groups in Bing Shopping campaigns.

Possible values are OptimizeForClicks and RotateAdsEvenly.

If set to OptimizeForClicks, Bing Ads will predominantly show ads that have the highest click-through rate (CTR).

If set to RotateAdsEvenly, Bing Ads will rotate between your ads on an equal basis. That is, each ad in a particular ad group has an equal chance of being displayed in response to a searcher's query. Sometimes the ads that get the highest CTR are not the ads that get the highest conversions. Using RotateAdsEvenly, you can help ensure that ads with a higher CTR don't unintentionally get precedence over ads with a higher conversion rate. Also if you want to test new ad copy, using RotateAdsEvenly can help ensure that those new ads get an opportunity to be displayed, even if you have other ads within the same ad group that have an established and higher CTR performance history.

Add: Optional. The default value is OptimizeForClicks.
Update: Optional. If no value is specified on update, this Bing Ads setting is not changed.
AdRotation
BiddingSchemeThe bid strategy type for how you want to manage your bids.

For ad groups you can use either of the InheritFromParentBiddingScheme or ManualCpcBiddingScheme objects.

IMPORTANT: If the campaign bid strategy type is set to MaxClicks, MaxConversions, or TargetCpa, the behavior of existing features will change unless you set an individual ad group’s or keyword’s bid strategy to ManualCpc.
- You can continue to set the ad group and keyword bids; however they will not be used by Bing Ads.
- Bing Ads will periodically change your stored ad group or keyword bid settings. You can continue to set new bids, however Bing Ads may change them at any time using this bid strategy type.
- You can continue to set bid adjustments e.g. for age, gender, or location; however with one exception they will not be used by Bing Ads. Bing Ads will not honor any bid adjustments, unless you have set a bid adjustment of -100% (opt out).
- Whether you chose the DailyBudgetAccelerated or DailyBudgetStandard budget type, Bing Ads will use the DailyBudgetStandard budget type.

Also note that you must have conversion tracking (a UET tag and a conversion goal) set up for the EnhancedCpc, MaxConversions, and TargetCpa bid strategy types to work. See Universal Event Tracking for more information.

To set the MaxConversions or TargetCpa bid strategy types, the campaign must have at least 15 conversions in the last 30 days. If you try to add or update a campaign to use one of these strategy types, the requested operation will fail if there is not enough conversion history. If an active campaign uses one of these bid strategy types, and then ceases to meet the minimum conversion history requirement at any time, Bing Ads will stop auto bidding but will continue to use the DailyBudgetStandard budget type. For a new campaign we recommend that you start with EnhancedCpc and then when the campaign has enough conversion history, you can update it to use either the MaxConversions or TargetCpa bid strategy.

Tip: You can set your campaign’s bid strategy to EnhancedCpcBiddingScheme, MaxClicksBiddingScheme, MaxConversionsBiddingScheme, or TargetCpaBiddingScheme and then, at any time, set an individual ad group’s or keyword’s bid strategy to Manual CPC (ManualCpcBiddingScheme).

Note: For campaigns of type Shopping the product partitions inherit the ad group BiddingScheme, and you must be in the Bing Shopping Enhanced CPC pilot. The pilot ID is 340.

Add: Optional. If you do not set this element, then InheritFromParentBiddingScheme is used by default.
Update: Optional. If no value is specified on update, this Bing Ads setting is not changed.
BiddingScheme
ContentMatchBidThe bid to use when the keywords that the service extracts from the content page and the ad group’s keywords match by using an exact match comparison. An exact match results when all of the words in the keyword exactly match the user's query.

IMPORTANT: Bing Ads no longer serves ads on the content network and you are no longer able to set the Content ad distribution. If you try to add or update an ad group with ad distribution set only to Content, the CampaignServiceAdGroupMediumNotAllowedForDistributionChannel error will be returned. If you try to add or update an ad group with ad distribution set to both Search and Content, the operation will succeed, however the ad distribution will be stored as Search only.

Starting on November 30th 2017, Bing Ads will delete the remaining Content ad groups. If you want to keep the ad groups, you must set the ad distribution to Search only before November 30th. If you try to add or update content bid in ad group settings the CampaignServiceCannotSetContentBidOnAdGroup error will be returned. Content match type keywords will also be deleted. If you try to add or update a keyword match type to content the CampaignServiceInvalidMatchTypes error will be returned.

Note: This feature is not supported for ad groups in Bing Shopping campaigns or Dynamic Search Ads campaigns.

The minimum and maximum bid range depends on the account's currency. For more information, see Currencies.

You can set a content match bid if the AdDistribution value includes Content.

Specifying a content match bid at the keyword level overrides the ad group’s content match bid value.

Add: Optional. If you do not set a bid, it will be set to the minimum depending on your account's currency.
Update: Optional. If no value is specified on update, this Bing Ads setting is not changed.
Bid
EndDateThe date that the ads in the ad group will expire.

If you do not specify an end date, the ads will not expire. The end date can be extended to make an ad group's ads eligible for delivery, even after the ad group expires.

The end date is inclusive. For example, if you set EndDate to 12/31/2020, the ads in the ad group will expire at 11:59 PM on 12/31/2020. The time is based on the time zone that you specify at the campaign level.

Add: Optional. To set no end date when adding an ad group, set the EndDate element to null.
Update: Optional. If no value is specified on update, this Bing Ads setting is not changed. To delete the existing end date setting, and effectively set no end date when updating an ad group, set the EndDate element to a date equal to or later than January 2, 2050. When you retrieve the ad group next time, this element will be nil i.e. it will not be set to January 2, 2050.
Date
ForwardCompatibilityMapThe list of key and value strings for forward compatibility. This element can be used to avoid otherwise breaking changes when new elements are added in future releases.

Note: Forward compatibility changes will be noted here in future releases. There are currently no forward compatibility changes for the AdGroup object.
KeyValuePairOfstringstring array
IdThe system generated identifier of the ad group.

Add: Not allowed.
Update: Read-only and Required
long
LanguageThe language of the ads and keywords in the ad group.

For possible values, see Ad Languages.

Note: For ad groups in Dynamic Search Ads campaigns, only English is supported.

IMPORTANT: Support for multiple languages at the campaign level is in pilot. If languages are set at both the ad group and campaign level, the ad group-level language will override the campaign-level language. The customer is enabled for the pilot if the GetCustomerPilotFeatures response includes pilot number 310. Pilot participants will be able to set multiple languages at the campaign level, and during update will be able to delete the ad group level language by specifying an empty string value (""). If you leave this element nil, then the ad group language will not be updated. If your application depends on ad group language being set, then you must prepare for the possibility that ad group language will be nil. More specific dates and implementation details will be provided later through the Bing Ads API Blog, and in the meantime you should update your application right away to support the change.

Add: Optional if the campaign has one or more languages set, and otherwise language is required.
Update: Optional if the customer is in the Campaign Languages pilot, and otherwise update is not allowed. If you are not in the pilot and try to change the language during update, an error will be returned.
string
NameThe name of the ad group.

The name must be unique among all active ad groups within the campaign. The name can contain a maximum of 128 characters.

Add: Required
Update: Optional. If no value is specified on update, this Bing Ads setting is not changed.
string
NativeBidAdjustmentThe percent amount by which to adjust your bid for native ad placements above or below the base ad group or keyword bid.

Note: Not everyone has this feature yet. If you don’t, don’t worry. It’s coming soon.

Supported values are negative one hundred (-100) through positive nine hundred (900). Setting the bid adjustment to -100 percent will prevent native ad placements from showing for this ad group.

Set this element to zero (0) if you do not want any bid adjustment for native ad placements. If this element is null you will inherit the NativeBidAdjustment setting of the ad group's Campaign.

Add: Optional
Update: Optional. This property will only be updated if you also set the UpdateNativeBidAdjustment element of the UpdateAdGroups request message to true, and otherwise this property will be ignored. If the ad group already has a native bid adjustment, and you want to remove it to effectively inherit the NativeBidAdjustment setting of the ad group's Campaign, set this element to null.
int
NetworkThe search networks where you want your ads to display.

Possible values are OwnedAndOperatedAndSyndicatedSearch, OwnedAndOperatedOnly, and SyndicatedSearchOnly.

You must not set Network if the AdDistribution is set to Content, otherwise an error will be returned.

If you select one of the syndicated search options, you can call the SetNegativeSitesToAdGroups or SetNegativeSitesToCampaigns operation to prevent the ads from displaying on specific syndicated search websites.

Add: Optional. The default is OwnedAndOperatedAndSyndicatedSearch.
Update: Optional. If no value is specified on update, this Bing Ads setting is not changed.
Network
PricingModelThe only supported pricing model in Bing Ads is based on cost per click (CPC).

With Cpc, each time the user clicks your ad, the service charges your account based on your bid. The actual charge is based on the auction results and may be less than your bid value.

You are not allowed to set this value to Cpm.

Note: This field is deprecated and will be removed in a future version of the Bing Ads API.

Add: Optional. The pricing model will be set to Cpc by default.
Update: Optional. If no value is specified on update, this Bing Ads setting is not changed.
PricingModel
RemarketingTargetingSettingThe targeting setting that is applicable for all audiences e.g., custom audiences and remarketing lists that are associated with this ad group. Each audience can be associated with multiple ad groups, and each ad group's remarketing targeting setting is applied independently for delivery.

Possible values are TargetAndBid and BidOnly.

Set this element to TargetAndBid if you want to show ads only to people included in the audience, with the option to change the bid amount. Ads in this ad group will only show to people included in the audience.

Set this element to BidOnly if you want to show ads to people searching for your ad, with the option to change the bid amount for people included in the audience. Ads in this ad group can show to everyone but the bid adjustment will apply to people included in the audience.

Note: This element is not returned in the AdGroup object by default. You must include RemarketingTargetingSetting in the optional ReturnAdditionalFields flags when calling GetAdGroupsByCampaignId and GetAdGroupsByIds.

Add: Optional. The default value is BidOnly.
Update: Optional. If no value is specified on update, this Bing Ads setting is not changed.
RemarketingTargetingSetting
SearchBidThe default bid to use when the user’s query and the ad group’s keywords match by using either a broad, exact, or phrase match comparison.

The minimum and maximum bid range depends on the account's currency. For more information, see Currencies.

You can set a search bid if the AdDistribution value includes Search.

Specifying a broad, exact, or phrase match bid at the keyword level overrides the ad group’s search bid value for the corresponding match type.

Add: Optional. If you do not set a bid, it will be set to the minimum depending on your account's currency.
Update: Optional. If no value is specified on update, this Bing Ads setting is not changed.
Bid
SettingsReserved for future use.Setting array
StartDateThe date that the ads in the ad group can begin serving; otherwise, the service can begin serving the ads in the ad group the day that the ad group becomes active.

The start date cannot be updated after the ad group is submitted.

The start date is inclusive. For example, if you set StartDate to 11/5/2016, the ads in the ad group will start at 12:00 AM on 11/5/2016. The time is based on the time zone that you specify at the campaign level.

Add: Optional. If you do not set the start date, then it will default to today's date and the service can begin serving the ads in the ad group as soon as the ad group status is active.
Update: Optional. If no value is specified on update, this Bing Ads setting is not changed.
Date
StatusThe status of the ad group.

Possible values are Active, Expired, and Paused. The Expired status is read-only.

Add: Optional. The default value is Paused.
Update: Optional. If no value is specified on update, this Bing Ads setting is not changed.
AdGroupStatus
TrackingUrlTemplateThe tracking template to use as a default for all URLs in your ad group.

The following validation rules apply to tracking templates. For more details about supported templates and parameters, see the Bing Ads help article What tracking or URL parameters can I use?

  • Tracking templates defined for lower level entities e.g. ads override those set for higher level entities e.g. campaign. For more information, see Entity Hierarchy and Limits.

  • The length of the tracking template is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit.

  • The tracking template must be a well-formed URL beginning with one of the following: http://, https://, {lpurl}, or {unescapedlpurl}.

  • Bing Ads does not validate whether custom parameters exist. If you use custom parameters in your tracking template and they do not exist, then the landing page URL will include the key and value placeholders of your custom parameters without substitution. For example if your tracking template is for example http://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl}, and neither {_season} or {_promocode} are defined at the campaign, ad group, criterion, keyword, or ad level, then the landing page URL will be the same.



Add: Optional
Update: Optional. If no value is specified on update, this Bing Ads setting is not changed.
string
UrlCustomParametersYour custom collection of key and value parameters for URL tracking.

You may include up to 3 individual CustomParameter objects within the CustomParameters object. Each CustomParameter contains a Key and Value element.

Add: Optional
Update: Optional. If no value is specified on update, this Bing Ads setting is not changed. To remove all custom parameters, set the Parameters element of the CustomParameters object to null or empty. To remove a subset of custom parameters, specify the custom parameters that you want to keep in the Parameters element of the CustomParameters object.
CustomParameters

CampaignManagementService.svc v11

Namespace: https://bingads.microsoft.com/CampaignManagement/v11

AddAdGroups
GetAdGroupsByCampaignId
GetAdGroupsByIds
UpdateAdGroups

Show: