SitelinkAdExtension Data Object - Campaign Management

Defines an object with one sitelink per ad extension. You can use the sitelink to promote certain products, services, or sections of your website and take potential customers to exactly the information they were searching for. This can increase both click-through-rate and conversions.

You can associate a sitelink ad extension with the account or with campaigns and ad groups in the account. Each entity (account, campaign, or ad group) can be associated with up to 20 sitelink ad extensions.

Syntax

<xs:complexType name="SitelinkAdExtension" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:complexContent mixed="false">
    <xs:extension base="tns:AdExtension">
      <xs:sequence>
        <xs:element minOccurs="0" name="Description1" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="Description2" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="DestinationUrl" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="DisplayText" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="FinalAppUrls" nillable="true" type="tns:ArrayOfAppUrl" />
        <xs:element minOccurs="0" name="FinalMobileUrls" nillable="true" type="q43:ArrayOfstring" xmlns:q43="http://schemas.microsoft.com/2003/10/Serialization/Arrays" />
        <xs:element minOccurs="0" name="FinalUrlSuffix" 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="FinalUrls" nillable="true" type="q44:ArrayOfstring" xmlns:q44="http://schemas.microsoft.com/2003/10/Serialization/Arrays" />
        <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:extension>
  </xs:complexContent>
</xs:complexType>

Elements

Element Description Data Type
Description1 The site link description line 1.

The maximum input length is 35 characters. If any Traditional Chinese characters are included, the limit is 15 characters.

Starting the week of September 18th, the limit will be relaxed such that only the Traditional Chinese characters will be counted double against the character limit. Each Traditional Chinese character will count as two and each English character will count only as one character.

If you specify Description1 then Description2 is required.

Add: Optional
Update: Optional
string
Description2 The site link description line 2.

The maximum input length is 35 characters. If any Traditional Chinese characters are included, the limit is 15 characters.

Starting the week of September 18th, the limit will be relaxed such that only the Traditional Chinese characters will be counted double against the character limit. Each Traditional Chinese character will count as two and each English character will count only as one character.

If you specify Description2 then Description1 is required.

Add: Optional
Update: Optional
string
DestinationUrl 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.The URL of the webpage that users are taken to when they click the site link.

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.

Add: Required
Update: Optional
string
DisplayText The site-link text displayed in the ad.

If you specify Description1 or Description2 then the display text can contain a maximum of 25 characters; otherwise, the display text can contain a maximum of 35 characters. If any Traditional Chinese characters are included, the limits are 11 characters given Description1 or Description2, and 15 characters otherwise.

Starting the week of September 18th, the limit will be relaxed such that only the Traditional Chinese characters will be counted double against the character limit. Each Traditional Chinese character will count as two and each English character will count only as one character.

Add: Required
Update: Optional
string
FinalAppUrls Reserved for future use. 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. Also note that you may not specify FinalMobileUrls if the DevicePreference is set to 30001 (mobile).

Add: Optional
Update: Optional
string array
FinalUrls The 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. Also note that if the extension's TrackingUrlTemplate or UrlCustomParameters elements are set, then at least one final URL is required.

Add: Optional
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
TrackingUrlTemplate The tracking template to use as a default for all FinalUrls and FinalMobileUrls.

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
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. Each CustomParameter includes Key and Value elements.

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.

Add: Optional
Update: Optional
CustomParameters

The SitelinkAdExtension object has Inherited Elements.

Inherited Elements

Inherited Elements from AdExtension

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

Element Description Data Type
DevicePreference Reserved for future use. long
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.

There are currently no forward compatibility changes for the AdExtension object.

Add: Read-only
Update: Read-only
KeyValuePairOfstringstring array
Id The unique Microsoft Advertising identifier of the ad extension.

Add: Read-only and Required
Update: Read-only
long
Scheduling Determines the calendar day and time ranges when the ad extension is eligible to be shown in ads.

Add: Optional
Update: Optional. If you set this element null, any existing scheduling set for the ad extension will remain unchanged. If you set this to any non-null Schedule object, you are effectively replacing existing scheduling settings for the ad extension. To remove all scheduling set this element to an empty Schedule object.
Schedule
Status The status of the ad extension. The value will always be Active because the Campaign Management service does not return deleted ad extensions.

Add: Read-only
Update: Read-only
AdExtensionStatus
Type The type of the ad extension. This value is SitelinkAdExtension when you retrieve a sitelink ad extension.

Add: Read-only
Update: Read-only

For more information about ad extension types, see the Ad Extension Data Object Remarks.
string
Version The number of times the contents of the ad extension has been updated. The version is set to 1 when you add the extension and is incremented each time it's revised.

Add: Read-only
Update: Read-only
int

Requirements

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