AdGroup Data Object - Campaign Management

Defines an ad group.

Syntax

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

Elements

Element Description Data Type
AdDistribution Determines whether the ads within this ad group will be displayed on the content distribution channel, search distribution channel, or both.

Possible values are Search and Content; however, Bing Ads no longer serves ads on the content network. Starting July 30th, 2017 you cannot set the Content ad distribution either. 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. By end of calendar year 2017, Bing Ads will migrate the remaining Search and Content ad groups to Search only. Then when you retrieve the ad groups which were previously set to Search and Content, the ad distribution will be Search only. By end of calendar year 2017, Bing Ads will also delete Content-only ad groups.

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
AdRotation Determines 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.

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
BiddingScheme The 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, the multiplier will inform rather than directly modify or override the automated bid. For auto bidding the multiplier is used as a weighted percentage to inform Bing Ads about how much you value the criterion relative to other criteria. For example, a -50% bid multiplier for a mobile device criterion with the Max Conversions bid strategy to indicate that you value conversions from mobile traffic half as much as other device types. The same bid multiplier with the Max Clicks bid strategy would indicate that you value clicks on mobile half as much as other device types. The valid range of values that you can use to inform auto bidding is -100.00 through 30.00.
- 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).

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
ContentMatchBid The 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.

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
EndDate The 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
ForwardCompatibilityMap The list of key and value strings for forward compatibility to avoid otherwise breaking changes when new elements are added in the current API version.

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

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

For possible values, see Ad Languages.

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.

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
Name The 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 256 characters.

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

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 intent ads from showing for this ad group.

Set this element to zero (0) if you do not want any bid adjustment for intent ads. 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
Network The 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
PricingModel The 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.

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
RemarketingTargetingSetting The 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.

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
SearchBid The 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
Settings Reserved for future use. Setting array
StartDate The 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
Status The 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
TrackingUrlTemplate The 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
UrlCustomParameters Your 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

Requirements

Service: CampaignManagementService.svc v11
Namespace: https://bingads.microsoft.com/CampaignManagement/v11

Used By

AddAdGroups
GetAdGroupsByCampaignId
GetAdGroupsByIds
UpdateAdGroups