ResponsiveSearchAd Data Object - Campaign Management
A responsive ad format for text ads in the Search network.
Note
Duplicate responsive search ads are allowed in the same ad group.
Responsive search ads allow you to set between 3-15 unique ad headlines (a.k.a. "titles") and 2-4 ad descriptions within a single ad. From there, Bing will select the most relevant headline and description combination for each given query and corresponding search user. By allowing Bing AI to select the most relevant headline and description for each query, we ensure that the right message lands for each of your potential customers, at the right time, across all possible intent signals.
The responsive ads shown to users appear identical to expanded text ads i.e., up to 3 headlines (title parts via expanded text ads) and 2 descriptions (text parts via expanded text ads). To maximize impressions across all ad formats the descriptions might not always be shown in your ad.
When you create responsive search ads the Descriptions and Headlines lists are stored as text assets that can be shared by any responsive search ad within the account. For example if "Seamless Integration" is a text asset, you will observe that it has the same asset identifier across all ads that link to "Seamless Integration" in the same Microsoft Advertising account. The asset identifiers are not included in the AddAds or UpdateAds response. With the Campaign Management service the only way to get the asset identifiers is by retrieving the ads you created. You can get the asset identifiers for descriptions and headlines by retrieving the ads in a subsequent service call e.g., via GetAdsByAdGroupId. With the Bulk service the asset identifiers are included in the bulk upload result file.
Note
Responsive search ads can only be created in Search campaigns where the AdGroupType is set to "SearchStandard". If the AdGroupType is set to "SearchDynamic", then the ad group does not support responsive search ads.
Syntax
<xs:complexType name="ResponsiveSearchAd" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:complexContent mixed="false">
<xs:extension base="tns:Ad">
<xs:sequence>
<xs:element minOccurs="0" name="Descriptions" nillable="true" type="tns:ArrayOfAssetLink" />
<xs:element minOccurs="0" name="Domain" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="Headlines" nillable="true" type="tns:ArrayOfAssetLink" />
<xs:element minOccurs="0" name="Path1" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="Path2" nillable="true" type="xs:string" />
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
Elements
The ResponsiveSearchAd object has the following elements: Descriptions, Domain, Headlines, Path1, Path2.
| Element | Description | Data Type |
|---|---|---|
| Descriptions | The list of descriptions that Bing can use to optimize the ad layout. To maximize impressions across all ad formats the descriptions might not always be shown in your ad. Unless you pin one of the descriptions to a specific position, Bing will optimize the ad layout dynamically with the best headlines and descriptions for the user's search query. From a data model perspective the desriptions and headlines are each stored as text assets i.e., one TextAsset per AssetLink. The same asset can be used by multiple ads. For example if "Seamless Integration" is a text asset, it will have the same asset identifier across all ads in the same Microsoft Advertising account. You must set between 2-4 descriptions. Each description's Text must contain at least one word. For efficient use of resources we recommend that you use dynamic text strings such as {keyword} instead of creating new ad copy for each keyword. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters. The maximum input length of each description's Text is 1,000 characters including dynamic text strings, and of those 1,000 no more than 90 final characters are allowed after substitution. The ad will fail to display or default text will be used if the length exceeds 90 characters after dynamic text substitution occurs. For languages with double-width characters e.g. Traditional Chinese the maximum input length is 500 characters including dynamic text strings, and of those 500 no more than 45 final characters are allowed after substitution. The ad will fail to display or default text will be used if the length exceeds 45 characters after dynamic text substitution occurs. The double-width characters are determined by the characters you use instead of the character set of the campaign or ad group language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The Text cannot contain the newline (\n) character. The text can contain IF functions. Add: Required Update: Optional. To retain all of the existing asset links, set or leave this element nil. If you set this element, any descriptions that were previously linked to this ad will be replaced. |
AssetLink array |
| Domain | The URL that will be displayed instead of the final URL. The final URL will still be used for the landing page URL. Reserved for limited pilot usage e.g. pharmaceutical customers. The domain portion of the URL in combination with the path 1 and path 2 strings cannot exceed 67 characters. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted. |
string |
| Headlines | The list of ad titles that Bing can use to optimize the ad layout. Unless you pin one of the headlines to a specific position, Bing will optimize the ad layout dynamically with the best headlines and descriptions for the user's search query. From a data model perspective the desriptions and headlines are each stored as text assets i.e., one TextAsset per AssetLink. The same asset can be used by multiple ads. For example if "Seamless Integration" is a text asset, it will have the same asset identifier across all ads in the same Microsoft Advertising account. You must set between 3-15 headlines. Each headline's Text must contain at least one word. For efficient use of resources we recommend that you use dynamic text strings such as {keyword} instead of creating new ad copy for each keyword. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters. The maximum input length of each headline's Text is 1,000 characters including dynamic text strings, and of those 1,000 no more than 30 final characters are allowed after substitution. The ad will fail to display or default text will be used if the length exceeds 30 characters after dynamic text substitution occurs. For languages with double-width characters e.g. Traditional Chinese the maximum input length is 500 characters including dynamic text strings, and of those 500 no more than 15 final characters are allowed after substitution. The ad will fail to display or default text will be used if the length exceeds 15 characters after dynamic text substitution occurs. The double-width characters are determined by the characters you use instead of the character set of the campaign or ad group language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The Text cannot contain the newline (\n) character. The text can contain IF functions. Add: Required Update: Optional. To retain all of the existing asset links, set or leave this element nil. If you set this element, any headlines that were previously linked to this ad will be replaced. |
AssetLink array |
| Path1 | The first part of the optional path that will be appended to the domain portion of your display URL. The domain portion of your display URL e.g. https://www.contoso.com will be generated from the domain of your Final URL (FinalUrls element). Then if you have specified a value for Path1 it will be appended to the display URL. If you have also specified a value for Path2, then it will also be appended to the display URL after Path1. For example if your FinalUrls contains https://www.contoso.com, Path1 is set to subdirectory1, and Path2 is set to subdirectory2, then the URL displayed will be https://www.contoso.com/subdirectory1/subdirectory2. The path can contain dynamic parameters such as {MatchType}. For a list of supported parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use?. The maximum input length is 1,000 characters if you include dynamic text strings. No more than 15 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of the final URL domain and the paths combined exceed 67 characters. For languages with double-width characters e.g. Traditional Chinese the maximum input length is 1,000 characters if you include dynamic text strings. No more than 7 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of the final URL domain and the paths combined exceed 33 characters. The double-width characters are determined by the characters you use instead of the character set of the campaign or ad group language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The path cannot contain the forward slash (/) or newline (\n) characters. If the path includes a space, it will be replaced with an underscore (_) when the ad is shown. The path can contain IF functions. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted. |
string |
| Path2 | The second part of the optional path that will be appended to the domain portion of your display URL. The domain portion of your display URL e.g. https://www.contoso.com will be generated from the domain of your Final URL (FinalUrls element). Then if you have specified a value for Path1 it will be appended to the display URL. If you have also specified a value for Path2, then it will also be appended to the display URL after Path1. For example if your FinalUrls contains https://www.contoso.com, Path1 is set to subdirectory1, and Path2 is set to subdirectory2, then the URL displayed will be https://www.contoso.com/subdirectory1/subdirectory2. You can only specify Path2 if Path1 is also set. The path can contain dynamic parameters such as {MatchType}. For a list of supported parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use?. The maximum input length is 1,000 characters if you include dynamic text strings. No more than 15 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of the final URL domain and the paths combined exceed 67 characters. For languages with double-width characters e.g. Traditional Chinese the maximum input length is 1,000 characters if you include dynamic text strings. No more than 7 final (not dynamic text) characters can be input. The ad will fail to display or the default text will be used if the length of the final URL domain and the paths combined exceed 33 characters. The double-width characters are determined by the characters you use instead of the character set of the campaign or ad group language settings. Double-width characters include Korean, Japanese and Chinese languages characters as well as Emojis. The path cannot contain the forward slash (/) or newline (\n) characters. If the path includes a space, it will be replaced with an underscore (_) when the ad is shown. The path can contain IF functions. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted. |
string |
The ResponsiveSearchAd object has Inherited Elements.
Inherited Elements
Inherited Elements from Ad
The ResponsiveSearchAd object derives from the Ad object, and inherits the following elements: AdFormatPreference, DevicePreference, EditorialStatus, FinalAppUrls, FinalMobileUrls, FinalUrls, FinalUrlSuffix, ForwardCompatibilityMap, Id, Status, TrackingUrlTemplate, Type, UrlCustomParameters. The descriptions below are specific to ResponsiveSearchAd, and might not apply to other objects that inherit the same elements from the Ad object.
| Element | Description | Data Type |
|---|---|---|
| AdFormatPreference | Not supported for this ad type. | string |
| DevicePreference | Not supported for this ad type. | long |
| EditorialStatus | The editorial review status of the ad, which indicates whether the ad is pending review, has been approved, or has been disapproved. Add: Read-only Update: Read-only |
AdEditorialStatus |
| FinalAppUrls | Not supported for this ad type. | AppUrl array |
| FinalMobileUrls | The mobile landing page URL. The following validation rules apply to Final URLs and Final Mobile URLs. - The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - You may specify up to 10 items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 for potential forward compatibility. - Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}. - Final URLs must each be a well-formed URL starting with either http:// or https://. - If you specify FinalMobileUrls, you must also specify FinalUrls. - You may not specify FinalMobileUrls if the device preference is set to mobile. This URL is used only if the keyword does not specify a final mobile URL. Add: Optional Update: Optional |
string array |
| FinalUrls | The landing page URL. The domain portion of the URL in combination with the path 1 and path 2 strings cannot exceed 67 characters. The following validation rules apply to Final URLs and Final Mobile URLs. - The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit. - You may specify up to 10 items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 for potential forward compatibility. - Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}. - Final URLs must each be a well-formed URL starting with either http:// or https://. - If you specify FinalMobileUrls, you must also specify FinalUrls. - You may not specify FinalMobileUrls if the device preference is set to mobile. Also note that if this ad's TrackingUrlTemplate or UrlCustomParameters element are set, then at least one final URL is required. This URL is used only if the keyword does not specify a final URL. Add: Required Update: Optional |
string array |
| 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. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted. |
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 unique Microsoft Advertising identifier of the ad. Add: Read-only Update: Required and Read-Only |
long |
| Status | The status of the ad. You can set the ad status to Active or Paused. Add: Optional Update: Optional |
AdStatus |
| TrackingUrlTemplate | The tracking template to use as a default for all landing page URLs. 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 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 https://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. If you set this element to an empty string (""), the previous setting will be deleted. |
string |
| Type | The type of the ad. This value is ResponsiveSearch when you retrieve a responsive search ad. For more information about ad types, see the Ad Data Object Remarks. Add: Read-only Update: Read-only |
AdType |
| UrlCustomParameters | Your custom collection of key and value parameters for URL tracking. Microsoft Advertising will accept the first 8 CustomParameter objects that you include within the CustomParameters object, and if you include more than 8 custom parameters an error will be returned. Each CustomParameter includes Key and Value elements. 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
CreateResponsiveSearchAdRecommendation
RefineResponsiveSearchAdRecommendation