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="AdRotation" nillable="true" type="tns:AdRotation" />
    <xs:element minOccurs="0" name="AudienceAdsBidAdjustment" nillable="true" type="xs:int" />
    <xs:element minOccurs="0" name="BiddingScheme" nillable="true" type="tns:BiddingScheme" />
    <xs:element minOccurs="0" name="CpcBid" nillable="true" type="tns:Bid" />
    <xs:element minOccurs="0" name="EndDate" nillable="true" type="tns:Date" />
    <xs:element minOccurs="0" name="FinalUrlSuffix" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="ForwardCompatibilityMap" nillable="true" type="q15:ArrayOfKeyValuePairOfstringstring" xmlns:q15="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="Network" nillable="true" type="tns:Network" />
    <xs:element minOccurs="0" name="PrivacyStatus" nillable="true" type="tns:AdGroupPrivacyStatus" />
    <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="tns:CustomParameters" />
  </xs:sequence>
</xs:complexType>

Elements

Element Description Data Type
AdRotation Ad rotation sets how often Microsoft Advertising selects which ads to serve, if you have multiple ads within an ad group. Since no more than one ad from your account can show at a time, ad rotation prioritizes ads that appear statistically more likely to perform better.

Note: Ad rotation does not apply to Product Ads.

Possible values for the ad rotation Type are OptimizeForClicks and RotateAdsEvenly.

If set to OptimizeForClicks, Microsoft Advertising prioritizes the ad from the ad group that appears to have the best chance of performing well, based on auction characteristics or factors, such as keyword, search term, device or location. Better-performing ads will show more frequently, and others will be served less often, if at all.

If set to RotateAdsEvenly, Microsoft Advertising provides more balance in rotation between your ads. That is, the ads in a particular ad group have a similar chance of being displayed in response to a searcher's query. Ads are prioritized lower if they have lower ad quality, and therefore might display less often, or not at all.
- The RotateAdsEvenly setting can allow lower-performing ads to display as often as better-performing ads. This might impact ad group performance.
- The RotateAdsEvenly setting will be ignored if you use an automated bid strategy i.e., MaxClicks, MaxConversions, or TargetCpa, as these bid strategies prioritize better-performing ads.

Add: Optional. The default value is OptimizeForClicks.
Update: Optional. If no value is set for the update, this setting is not changed.
AdRotation
AudienceAdsBidAdjustment The percent amount by which to adjust your bid for audience ads above or below the base ad group or keyword bid.

This property is available in Search campaigns if the customer is enabled for the Microsoft Audience Network.

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

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

Add: Optional
Update: Optional. This property will only be updated if you also set the UpdateAudienceAdsBidAdjustment 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 AudienceAdsBidAdjustment setting of the ad group's Campaign, set this element to null.
int
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. For details about supported bid strategies per campaign type, see Budget and Bid Strategies.

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 Microsoft Advertising.
- Microsoft Advertising will periodically change your stored ad group or keyword bid settings. You can continue to set new bids, however Microsoft Advertising 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 Microsoft Advertising 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.
- Even if the AdRotation is set to RotateAdsEvenly, it will be ignored as these bid strategies prioritize better-performing ads.

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 ManualCpcBiddingScheme.

For campaigns of type Shopping the product partitions inherit the ad group BiddingScheme.

Add: Optional. If you do not set this element, then InheritFromParentBiddingScheme is used by default.
Update: Optional. If no value is set for the update, this setting is not changed.
BiddingScheme
CpcBid 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.

Specifying a broad, exact, or phrase match bid at the keyword level overrides the ad group's Cpc 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 set for the update, this 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 this element to null.
Update: Optional. If no value is set for the update, this setting is not changed. To delete the existing end date setting, and effectively set no end date when updating an ad group, set the end 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
FinalUrlSuffix The final URL suffix can include tracking parameters that will be appended to the end of your landing page URL. We recommend placing tracking parameters that your landing page requires in a final URL suffix so that your customers are always sent to your landing page. For more details and validation rules see Final URL Suffix in the technical guides.

This feature is only available for customers in the Final URL Suffix Phase 1 pilot (GetCustomerPilotFeatures returns 533). If you are not in the pilot and attempt to set this property an error will be returned. During calendar year 2019 this feature will be enabled for all customers.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed.
string
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 this object.
KeyValuePairOfstringstring array
Id The system generated identifier of the ad group.

Add: Not allowed.
Update: Read-only and Required
long
Language Your ad language setting determines the language you will use when you write your ads and should be the language of your customers.

IMPORTANT: If languages are set at both the ad group and campaign level, the ad group level language will override the campaign level language.

The supported language strings for Search and Shopping campaigns are: Danish, Dutch, English, Finnish, French, German, Italian, Norwegian, Portuguese, Spanish, Swedish, and TraditionalChinese.

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

For ad groups in Audience campaigns, ad group level language is not supported, and you must set the Languages element of the ad group's campaign to "All".

Add: Optional if the campaign has one or more languages set, and otherwise the language is required for most campaign types. You are not allowed to set this element for ad groups in Audience campaigns.
Update: Optional. If no value is set for the update, this setting is not changed. To remove the language and defer to the campaign level languages, set this element to an empty string value (""). The ad group language cannot be removed until campaign language updates have been processed, which could take up to 12 hours after the campaign languages have been set for the first time. The 12 hour wait time is expected to be removed during Q1 calendar year 2019, and you will then be able to remove ad groups immediately.
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 set for the update, this setting is not changed.
string
Network The search networks where you want your ads to display.

Possible values are OwnedAndOperatedAndSyndicatedSearch, OwnedAndOperatedOnly, and SyndicatedSearchOnly.

For ad groups in Audience campaigns, ad group level network is not supported. The ad groups are in the Microsoft Audience Network.

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.

For more information about networks and ad distribution, see the About Ad Distribution help article.

Add: Optional. The default is OwnedAndOperatedAndSyndicatedSearch.
Update: Optional. If no value is set for the update, this setting is not changed.
Network
PrivacyStatus Indicates whether or not your ad group target criteria e.g., ProfileCriterion are too narrow for ad groups in Audience campaigns.

Add: Read-only
Update: Read-only
AdGroupPrivacyStatus
Settings The ad group settings that typically vary by campaign type.

You can include a maximum of one object per setting type in the list of settings e.g., one TargetSetting.

The CoOpSetting determines whether or not to amplify your partner's bid for the ad group in feed-based cooperative bidding campaigns. The CoOpSetting is only applicable for ad groups in Microsoft Shopping Campaigns that are setup for Cooperative bidding.

The TargetSetting can be used with any campaign type, and determines whether the Age, Audience, CompanyName, Gender, Industry, and JobFunction criterions associated with this ad group use the "target and bid" option or the "bid only" target option. Within the TargetSetting you can have multiple TargetSettingDetail objects i.e., one per CriterionTypeGroup.

Add: Optional. If this element does not include a TargetSetting object, the default bid option for all criterion type groups is effectively "bid only". If this element does not include a CoOpSetting object, the default Cooperative bidding option for the ad group is "bid value" i.e., the auction will use the fixed bid that you set for each BiddableAdGroupCriterion.
Update: Optional. If no value is set for the update, this setting is not changed.
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 is inclusive. For example, if you set the start date to 5/5/2019, the ads in the ad group will start at 12:00 AM on 5/5/2019. 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 set for the update, this setting is not changed. The start date cannot be updated after the ad group is submitted i.e., once the start date has arrived.
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 set for the update, this 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 Microsoft Advertising 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}.
- Microsoft Advertising 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 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 set for the update, this setting is not changed.
string
UrlCustomParameters Your custom collection of key and value parameters for URL tracking.

Microsoft Advertising will accept the first 3 CustomParameter objects that you include within the CustomParameters object, and any additional custom parameters will be ignored. Each CustomParameter includes Key and Value elements. For customers in the Custom Parameters Limit Increase Phase 1 pilot (GetCustomerPilotFeatures returns 532), Microsoft Advertising will accept the first 8 custom parameter key and value pairs that you include, and if you include more than 8 custom parameters an error will be returned. During calendar year 2019 the limit will be increased from 3 to 8 for all customers.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed. Set the UrlCustomParameters element to null or empty to retain any existing custom parameters. 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 v13
Namespace: https://bingads.microsoft.com/CampaignManagement/v13

Used By

AddAdGroups
GetAdGroupsByCampaignId
GetAdGroupsByIds
UpdateAdGroups