TextAd Data Object - Campaign Management

Defines a text ad.

Important

Standard Text Ads have been deprecated in favor of Expanded Text Ads (EXTAs). Support for adding and updating standard text ads (STAs) ended on July 31, 2017. Now, advertisers can get and delete, but can no longer add new STAs or update existing standard text ads. One exception to the rule, is that you can still update the STA status e.g. from Active to Paused. Otherwise attempts to add or update STAs will result in the CampaignServiceAdTypeInvalid error.

It is important to note that all your existing STAs will continue to serve alongside EXTAs for the foreseeable future. While there is no date on when STAs will stop serving, you can expect an update to all of our customers well in advance once we make the decision to sunset serving STAs.

Syntax

<xs:complexType name="TextAd" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:complexContent mixed="false">
    <xs:extension base="tns:Ad">
      <xs:sequence>
        <xs:element minOccurs="0" name="DestinationUrl" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="DisplayUrl" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="Text" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="Title" nillable="true" type="xs:string" />
      </xs:sequence>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>

Elements

Element Description Data Type
DestinationUrl The URL of the webpage to take the user to when they click the ad.

The URL 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 URL can contain a maximum of 1,024 characters. If the URL does not specify a protocol, the system uses the HTTP protocol when a user clicks the ad. If the URL specifies the HTTP protocol when you add an ad, the service will remove the http:// protocol string (the HTTP protocol string does not count against the 1,024 character limit); however, the service will not remove an HTTPS protocol string (https://) from the URL.

Important: If you are currently using Destination URLs, you must eventually replace them with Final URLs. For more information, see URL Tracking with Upgraded URLs.

This URL is used only if the keyword does not specify a destination URL.

Add: Not supported
Update: Not supported
string
DisplayUrl The URL to display in the ad.

The subdirectory of the display URL can contain dynamic text strings such as {keyword}; however, the URL hostname cannot contain dynamic text. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters.

The maximum input length of the URL is 200 characters, and can contain dynamic text strings. The ad will fail to display or default text will be used if the length exceeds 35 characters after dynamic text substitution occurs.

Add: Not supported
Update: Not supported
string
Text The ad copy. The copy must contain at least one word. The ad's copy and title combined must total at least three words.

The text can contain dynamic text strings such as {keyword}. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters.

The maximum input length of the copy is 300 characters, and can contain dynamic text strings. The ad will fail to display or default text will be used if the length exceeds 71 characters after dynamic text substitution occurs. Note that for ad groups that use Traditional Chinese, the text is limited to 38 characters after substitution.

The text cannot contain the newline (\n) character.

Add: Not supported
Update: Not supported
string
Title The title of the ad. The title must contain at least one word. The ad's copy and title combined must total at least three words.

The title can contain dynamic text strings such as {keyword}. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters.

The maximum input length of the title is 80 characters, and can contain dynamic text strings. The ad will fail to display or default text will be used if the length exceeds 25 characters after dynamic text substitution occurs. Note that for ad groups that use Traditional Chinese, the title is limited to 15 characters after substitution.

The title cannot contain the newline (\n) character.

Add: Not supported
Update: Not supported
string

The TextAd object has Inherited Elements.

Inherited Elements

Inherited Elements from Ad

The TextAd object derives from the Ad object, and inherits the following elements. The descriptions below are specific to TextAd, 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 search 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 text ad per ad group that does not prefer audience ads, otherwise the ad copy of all 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: Not supported
Update: Not supported
string
DevicePreference This element determines whether the preference is for text ads to be displayed on mobile devices or all devices.

To specify a preference for mobile devices, set this element to 30001.

To specify all devices, set this element to 0 (zero) or leave the element nil. By default, this element will be nil. You must define at least one text ad per ad group that is not mobile preferred, otherwise the ad will be eligible for all devices.

Add: Not supported
Update: Not supported
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: Not supported
Update: Not supported
AdEditorialStatus
FinalAppUrls Not supported for text ads. AppUrl array
FinalMobileUrls The mobile landing page URL.

This URL is used only if the keyword does not specify a final mobile 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. Also note that for TextAd objects you may not specify FinalMobileUrls if the DevicePreference is set to 30001 (mobile).

Add: Not supported
Update: Not supported
string array
FinalUrls The landing page URL.

This URL is used only if the keyword does not specify a final 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. Also note that if this ad's TrackingUrlTemplate or UrlCustomParameters element are set, then at least one final URL is required.

Add: Not supported
Update: Not supported
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: Not supported
Update: Not supported
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 for the ad.

Add: Not supported
Update: Required and Read-only
long
Status The status of the ad.

You can set the ad status to Active or Paused.

Add: Not supported
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: Not supported
Update: Not supported
string
Type The type of the ad. This value is Text when you retrieve a text ad. For more information about ad types, see the Ad Data Object Remarks.

Add: Not supported
Update: Not supported
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: Not supported
Update: Not supported
CustomParameters

Requirements

Service: CampaignManagementService.svc v13
Namespace: https://bingads.microsoft.com/CampaignManagement/v13