AdGroup

AdGroup Data Object

 

Defines an ad group.

Syntax

<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 name="BiddingModel" type="tns:BiddingModel" nillable="true" minOccurs="0"/>
    <xs:element name="ContentMatchBid" type="tns:Bid" nillable="true" minOccurs="0"/>
    <xs:element name="EndDate" type="tns:Date" nillable="true" minOccurs="0"/>
    <xs:element name="ForwardCompatibilityMap" type="q15:ArrayOfKeyValuePairOfstringstring" nillable="true" minOccurs="0" xmlns:q15="http://schemas.datacontract.org/2004/07/System.Collections.Generic"/>
    <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="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 name="UrlCustomParameters" type="q16:CustomParameters" nillable="true" minOccurs="0" xmlns:q16="http://schemas.datacontract.org/2004/07/Microsoft.AdCenter.Advertiser.CampaignManagement.Api.DataContracts.V10"/>
  </xs:sequence>
</xs:complexType>

Elements

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

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 should include a string that contains a space-delimited list of values for example, <AdDistribution>Search Content</AdDistribution>.
AdDistributionRequiredOptional
AdRotationDetermines the ad rotation type.

Note: Ad rotation is applicable for text and mobile ads, but not product ads.
AdRotationOptionalOptional
BiddingModelDetermines whether the ad group bids on keyword matches or site placement matches. The default is Keyword.

If you specify the keyword bidding model, you can set AdDistribution to both Content and Search. If you specify the site placement model, you must set AdDistribution only to Content.

Important: Bing Ads API features for site placements are deprecated and will start returning errors during the first half of calendar year 2016.
BiddingModelOptionalRead-only
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.

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

You can set a content match bid if the AdDistribution element contains Content.
BidOptionalOptional
EndDateThe date that the ads in the ad group will expire. If you do not specify an end date, the ads will not expire.

Note: 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 3/10/2010, the ads in the ad group will expire at 11:59 PM on 3/10/2010. The time is based on the time zone that you specify at the campaign level.

To set no end date when updating an ad group, set the EndDate element to a date equal to or later than January 2, 2050.

To set no end date when adding an ad group, set the EndDate element to null.
DateOptionalOptional
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 arrayRead-onlyRead-only
IdThe system generated identifier of the ad group.longRead-onlyRequired
LanguageThe language of the ads and keywords in the ad group. For possible values, seeCommon Market Values.stringRequiredRead-only
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.stringRequiredOptional
NativeBidAdjustmentThe percent amount by which to adjust your bid for native ads above or below the base ad group or keyword bid.

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

Set this element to zero (0) if you want to use the base ad group or keyword bid instead of specifying any bid adjustment for native ads.

If this element is null you will inherit the NativeBidAdjustment setting of the ad group's Campaign.

When you update an ad group object using the UpdateAdGroups operation, this element will only be set by setting the UpdateNativeBidAdjustment element of the request to true, and otherwise this element will be ignored.
intOptionalOptional
NetworkThe search networks where you want your ads to display. The default is OwnedAndOperatedAndSyndicatedSearch.

You must set Network to null if AdDistribution is set to Content.

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

Note: Product ads will only serve in syndicated search networks for pilot participants. If you are not in pilot, then for product ads your effective network is OwnedAndOperatedOnly, regardless of your ad group's network setting. Your network setting is valid for other ads such as text and mobile ads.
NetworkOptionalOptional
PricingModelYou can specify a pricing model based on cost per click (CPC) or cost per 1000 impressions (CPM).

For CPC, each time the user clicks your ad, the service charges your account a maximum of your bid value plus the incremental bid value if you specify targeting. The actual charge is based on the auction results and may be less than your bid value.

If you specify CPC and enable conversion tracking for the campaign, you can calculate your costs per conversion. This helps you to determine the return on investment for your campaign.

For CPM, the AdDistribution element must be set to Content distribution only, and your account is charged after the service displays your ad 1,000 times. The charge is based on the sum of your winning bids divided by 1,000.

Note: Available for members of the CPM pilot program.
PricingModelRequiredRead-only
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.

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.

You can set a search bid if the AdDistribution element contains Search.

Note This element is equivalent to the BroadMatchBid element of an AdGroup in Bing Ads API version 9. If you had set the PhraseMatchBid or ExactMatchBid elements of the version 9 AdGroup, they are ignored by Bing Ads and not migrated.
BidOptionalOptional
SettingsReserved for future use.Setting arrayOptionalOptional
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.

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

The start date is inclusive. For example, if you set StartDate to 3/5/2010, the ads in the ad group will start at 12:00 AM on 3/5/2010. The time is based on the time zone that you specify at the campaign level.
DateOptionalOptional
StatusThe status of the ad group.AdGroupStatusOptionalOptional
TrackingUrlTemplateThe tracking template to use as a default for all URLs in your ad group.

The following validation rules apply to tracking templates.

  • Tracking templates defined for lower level entities e.g. keyword 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.

    Note: 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}.

  • You can use any dynamic tag supported by Bing Ads. For a list of supported tags, see Dynamic Text Substitution.

  • 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 final 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, keyword, or ad level, then the final URL will be the same.

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

On update, 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.
CustomParametersOptionalOptional

Requirements

CampaignManagementService.svc v10

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

See Also

AddAdGroups
GetAdGroupsByCampaignId
GetAdGroupsByIds
UpdateAdGroups

Community Additions

ADD
Show:
© 2016 Microsoft