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="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:annotation>
        <xs:appinfo>
          <DefaultValue EmitDefaultValue="false" xmlns="http://schemas.microsoft.com/2003/10/Serialization/" />
        </xs:appinfo>
      </xs:annotation>
    </xs:element>
    <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 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
AudienceAdsBidAdjustment 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 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.

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

For possible values, see the Language column of 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
Network The search networks where you want your ads to display.

Possible values are OwnedAndOperatedAndSyndicatedSearch, OwnedAndOperatedOnly, and SyndicatedSearchOnly.

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 specified on update, this Bing Ads setting is not changed.
Network
PrivacyStatus Reserved. AdGroupPrivacyStatus
Settings The ad group settings for criterion type group targets.

The target setting 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.

The contract specifies a list; however, currently a maximum of one TargetSetting object is supported. Within the TargetSetting you can have multiple TargetSettingDetail objects i.e., one per CriterionTypeGroup.

Add: Optional. If this element is nil, the default bid option for all criterion type groups is effectively "bid only".
Update: Optional. If no value is specified on update, this Bing Ads 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 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 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 v12
Namespace: https://bingads.microsoft.com/CampaignManagement/v12

Used By

AddAdGroups
GetAdGroupsByCampaignId
GetAdGroupsByIds
UpdateAdGroups