ExpandedTextAd Data Object - Campaign Management

Defines an expanded text ad.

This ad format works seamlessly on mobile, tablet and desktop devices so you can focus more on crafting your longer ad copy and optimizing your ad text to better engage your customers before they click your ad.

The combination of the FinalUrls, Path1, Path2, Text, TextPart2, TitlePart1, TitlePart2 and TitlePart3 elements make the expanded text ad unique.

Syntax

<xs:complexType name="ExpandedTextAd" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:complexContent mixed="false">
    <xs:extension base="tns:Ad">
      <xs:sequence>
        <xs:element minOccurs="0" name="Domain" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="Path1" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="Path2" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="Text" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="TextPart2" nillable="true" type="xs:string">
          <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="TitlePart1" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="TitlePart2" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="TitlePart3" nillable="true" type="xs:string">
          <xs:annotation>
            <xs:appinfo>
              <DefaultValue EmitDefaultValue="false" xmlns="http://schemas.microsoft.com/2003/10/Serialization/" />
            </xs:appinfo>
          </xs:annotation>
        </xs:element>
      </xs:sequence>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>

Elements

Element Description Data Type
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
string
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. http://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 http://www.contoso.com, Path1 is set to subdirectory1, and Path2 is set to subdirectory2, then the URL displayed will be http://www.contoso.com/subdirectory1/subdirectory2.

The path can contain a countdown function. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers.

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.

Add: Optional
Update: Optional
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. http://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 http://www.contoso.com, Path1 is set to subdirectory1, and Path2 is set to subdirectory2, then the URL displayed will be http://www.contoso.com/subdirectory1/subdirectory2.

You can only specify Path2 if Path1 is also set.

The path can contain a countdown function. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers.

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.

Add: Optional
Update: Optional
string
Text The first part of the ad description.

The 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 text can contain a countdown function. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers.

The maximum input length is 1,000 characters if you include dynamic text strings. No more than 90 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 both text parts exceed 180 characters after dynamic text substitution occurs.

For languages with double-width characters e.g. Traditional Chinese the maximum input length is 500 characters if you include dynamic text strings. No more than 45 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 both text parts exceed 90 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.

Add: Required
Update: Optional
string
TextPart2 The second part of the ad description.

The 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 text can contain a countdown function. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers.

The maximum input length is 1,000 characters if you include dynamic text strings. No more than 90 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 both text parts exceed 180 characters after dynamic text substitution occurs.

For languages with double-width characters e.g. Traditional Chinese the maximum input length is 500 characters if you include dynamic text strings. No more than 45 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 both text parts exceed 90 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.

Add: Optional
Update: Optional
string
TitlePart1 The first part of the ad title. The three title parts will be automatically separated by a space, vertical bar, and space (" | ") when the ad is shown. Each part of the title 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 title can contain a countdown function. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers.

The maximum input length is 1,000 characters if you include dynamic text strings. No more than 30 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 all three title parts exceed 90 characters after dynamic text substitution occurs.

For languages with double-width characters e.g. Traditional Chinese the maximum input length is 500 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 all three title parts exceed 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 title cannot contain the newline (\n) character.

Add: Required
Update: Optional
string
TitlePart2 The second part of the ad title. The three title parts will be automatically separated by a space, vertical bar, and space (" | ") when the ad is shown. Each part of the title 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 title can contain a countdown function. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers.

The maximum input length is 1,000 characters if you include dynamic text strings. No more than 30 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 all three title parts exceed 90 characters after dynamic text substitution occurs.

For languages with double-width characters e.g. Traditional Chinese the maximum input length is 500 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 all three title parts exceed 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 title cannot contain the newline (\n) character.

Add: Required
Update: Optional
string
TitlePart3 The third part of the ad title. The three title parts will be automatically separated by a space, vertical bar, and space (" | ") when the ad is shown. Each part of the title 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 title can contain a countdown function. Regardless of the total length of all unsubstituted countdown parameters, the final displayed countdown will always use 8 characters out of the total characters available. For more details see Countdown Customizers.

The maximum input length is 1,000 characters if you include dynamic text strings. No more than 30 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 all three title parts exceed 90 characters after dynamic text substitution occurs.

For languages with double-width characters e.g. Traditional Chinese the maximum input length is 500 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 all three title parts exceed 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 title cannot contain the newline (\n) character.

Add: Optional
Update: Optional
string

The ExpandedTextAd object has Inherited Elements.

Inherited Elements

Inherited Elements from Ad

The ExpandedTextAd object derives from the Ad object, and inherits the following elements. The descriptions below are specific to ExpandedTextAd, and might not apply to other objects that inherit the same elements from the Ad object.

Element Description Data Type
AdFormatPreference The Ad Format Preference is used to indicate whether or not you prefer the ad copy to be shown to users as a search or audience ad. Search ads tend to be written as a call to action, whereas audience ads should be written in more of an informational style. While you have the option to use expanded text ads as audience ads, designating an ad as Audience ads preferred format allows you to optimize its messaging for native delivery.

IMPORTANT: You must define at least one expanded text ad per ad group that does not prefer audience ads, otherwise the ad copy of all expanded text ads will be eligible for both search and audience ads.

Possible values are AudienceAd and All. If set to All, the ad will be eligible for both search and audience ad formats. If set to AudienceAd, the ad will only be eligible for the audience ad format.

Add: Optional. If you do not set this element, by default the ad format preference will be set to All.
Update: Optional. If no value is set for the update, this setting is not changed.
string
DevicePreference This element is not applicable for expanded text ads. 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 This element is not applicable for expanded text ads. 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.

This feature is only available for customers in the Final URL Suffix Phase 2 pilot (GetCustomerPilotFeatures returns 566). If you are not in the pilot this property will be ignored and no 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 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 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
string
Type The type of the ad. This value is ExpandedText when you retrieve an expanded text 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 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 2 pilot (GetCustomerPilotFeatures returns 565), 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 v12
Namespace: https://bingads.microsoft.com/CampaignManagement/v12