Upgraded URLs

Upgraded URLs provide a smarter way for you to manage URLs in AdWords. You can specify which part of your URL specifies the landing page, and which part is used for tracking. This guide introduces you to this feature.

Currently, destination URLs are used to specify which part of your website users land on when they click your ad, and encode additional information for attributing performance back to the ad click. With shared tracking templates, Upgraded URLs allow you to update tracking information to your URLs without triggering editorial review.

Upgraded URLs allow for specifying the tracking and landing page parts of your URL through separate fields:

Final URL: Represents a list of actual landing pages for your ad, keyword, or sitelink. The final URL must be what the user ultimately sees in the browser bar after clicking an ad.
Final mobile URL: Represents a list of possible final mobile URLs for your ad, keyword, or sitelink after all cross domain redirects.
Final App URL: Represents a list of final app URLs that will be used on mobile devices if the user has the specific app installed.
Tracking template: Optional template to specify additional tracking parameters or redirects. We will use this template to assemble the actual destination URL to associate with the ad.
Custom parameters: Optional ValueTrack parameters that you can assign your own IDs to.

Supported entities

The following table summarizes the support for individual fields of Upgraded URLs in various AdWords entities.

AdWords Entity	Final URL	Final mobile URL	Final app URL	Custom parameters	Tracking template
Customer
Campaign
AdGroup
Ad
AdGroupCriterion
FeedItem (Sitelink)

Technical details

Final URL

The final URL represents the actual landing page for your ad, keyword, or sitelink. The final URL must be the URL that the user sees in the browser bar after clicking on your ad--it must not have any off-domain redirects.

The following C# code snippet shows how to create a text ad with final URLs:

// Create the text ad.
TextAd textAd = new TextAd();
textAd.headline = "Luxury Cruise to Mars";
textAd.description1 = "Visit the Red Planet in style.";
textAd.description2 = "Low-gravity fun for everyone!";
textAd.displayUrl = "www.example.com";

// Specify a list of final URLs. This field cannot be set if URL field
// is set. This may be specified at ad, criterion and feed item levels.
textAd.finalUrls = new string[] {
   "http://www.example.com/cruise/space/"
};

// Specify a list of final mobile URLs. This field cannot be set if URL
// field is set, or finalUrls is unset. This may be specified at ad,
// criterion and feed item levels.
textAd.finalMobileUrls = new string[] {
    "http://mobile.example.com/cruise/space/"
};

AdGroupAd textAdGroupAd = new AdGroupAd();
textAdGroupAd.adGroupId = adGroupId;
textAdGroupAd.ad = textAd;

// Create your Ad.
...

Final URLs follow the same override rules as destination URLs. For example, a final URL at the keyword level overrides a final URL at an ad level.

All existing URL validation rules for destination URLs also apply to final URLs. You can have URL tags in final URLs. All tags should either be valid ValueTrack tags, or custom parameters. You can have up to four levels of nesting when specifying URL tags, e.g.:

{ifmobile:{ifsearch:{keyword:cp={_customP}}}}

Most of the time, you'll only need to specify one final URL or final mobile URL. In the rare case where a tracking template might redirect the user to one of several landing pages (e.g., when testing landing pages) that don't go through a common landing page on the advertiser's domain, you can specify these landing pages using multiple final URLs.

Final mobile URLs

You can provide a separate mobile-preferred final URL if you want to send the user to a different landing page on mobile devices. However, if you prefer using ValueTrack parameters, then you can instead use existing ValueTrack parameters: {device} and {ifmobile} instead of using this field.

Final app URLs

If you have ads that link directly into in-app content using deep links, or have click-to-download ads, then you can specify these URLs in the final app URLs field.

Tracking template

You can optionally specify what additional tracking parameters or redirects are needed using the tracking template. When this parameter is specified, it will be used instead of final URLs to assemble the actual destination URL used for your ad. The tracking service can track the click and redirect the user to a landing page. The URL of the landing page should match the final URL. This template can embed the final URL using special ValueTrack parameters like {lpurl}.

To change tracking parameters on any supported entity except an Ad, you only need to update the tracking template. This will trigger no review actions from Google, allowing your ads to continue serving uninterrupted. To change the tracking template of an Ad, you must remove the existing Ad and create a new Ad with the new tracking template.

The following C# code snippet shows how to set the tracking template at the campaign level:

Campaign campaign = new Campaign();
campaign.id = 12345678;

// Specify a tracking URL for 3rd party tracking provider. You may
// specify one at customer, campaign, ad group, ad, criterion or
// feed item levels.
campaign.trackingUrlTemplate =
    "http://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl}";

// Update your campaign.
...

As with final URLs, a tracking template specified at a lower level entity will override the setting specified at a higher level entity, e.g., a tracking template at the campaign level overrides the setting at the account level.

Custom parameters

Custom parameters enable you to essentially create your own ValueTrack parameters, which may be useful when you want to use your own IDs, for instance, in identifying keywords. Previously, you would have had to hardcode this in the keyword destination URLs. Now, you can specify the ID for the keyword, use a custom parameter for each keyword, and then refer to the custom parameter in the final URL and/or tracking template, as you would for any other ValueTrack parameter.

A sample code snippet that adds custom parameters to a campaign is shown below. It assumes that the tracking URL template is set to

http://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl}

as explained earlier.

Campaign campaign = new Campaign();
campaign.id = 12345678;

// Since the tracking URL has two custom parameters, provide their
// values too. This can be provided at campaign, ad group, ad, criterion
// or feed item levels.
CustomParameter seasonParameter = new CustomParameter();
seasonParameter.key = "season";
seasonParameter.value = "spring";

CustomParameter promoCodeParameter = new CustomParameter();
promoCodeParameter.key = "promocode";
promoCodeParameter.value = "NYC123";

campaign.urlCustomParameters = new CustomParameters();
campaign.urlCustomParameters.parameters =
     new CustomParameter[] { seasonParameter, promoCodeParameter };

// Update your campaign.
...

The name of a custom parameter can contain only alphanumeric characters. When referring to the custom parameter in final URLs and tracking template, you should surround the custom parameter in braces, and prefix an underscore to its name, e.g. {_promoCode}.

As with final URLs, custom parameters at a lower level entity override values specified at higher level entities. You can have up to three custom parameters for an entity. The key and value must not exceed 16 and 200 bytes, respectively.

New ValueTrack parameters

The following ValueTrack parameters may be used with Upgraded URLs:

{ignore}: This parameter can be inserted in a final URL to indicate that the subsequent part of the URL does not alter content. You can use this parameter to reduce the amount of crawl activity on the URL.

For example, if you have a final URL like:
```
http://cars.example.com/sedan{ignore}?promocode=NYC123&udv={device}
```
This tells Google that the content of the page is determined only by http://cars.example.com/sedan and the page need not be re-crawled for any changes in promocode, or different instantiations of {device}.
{lpurl}, {lpurl+2}, {lpurl+3}: These parameters are initialized with the final page URL, escaped as per standard URL specifications. If you need the unescaped URL, you can use {unescapedurl}, {unescapedurl+2}, or {unescapedurl+3} instead. This is supported only in tracking URLs.

You can learn more about Valuetrack parameters from our help center article.

Upgraded URLs and sitelinks

Sitelinks support Upgraded URLs using FeedItem attributes. The relevant placeholders are given below:

Placeholder type	ID	Placeholder field	Data type	ID
SITELINKS	1	FINAL URLS	REPEATED_URL	5
		FINAL MOBILE URLS	REPEATED_URL	6
		TRACKING TEMPLATE	URL	7

The FeedItem's urlCustomParameters property allows you to set custom parameters.

Reports

Tracking templates, final URLs, final mobile URLs, and custom parameters are all available as attributes through various performance reports. In the report, keep in mind that final URLs and final mobile URLs will be rendered as a list of values, separated by a semicolon, as shown in this example:

http://www.example.com/cruise/space/;http://www.example.com/locations/mars/

Similarly, custom parameters will be returned as a set of key-value pairs, separated by semicolons:

{_season}=spring;{_promocode}=NYC123

To get statistics summarized by the effective final URL of each impression, use the FINAL_URL_REPORT.

Prepare for Upgraded URLs

You can update existing entities to use Upgraded URLs by clearing out their destination URL fields and setting the appropriate Upgraded URL fields in their place. However, this approach won't work with ads since you cannot update the destination URL of an ad once it is created. Instead, you'll need to use the upgradeUrl method of AdGroupAdService to upgrade ads. The upgradeUrl method will upgrade your ads in place without losing their historical stats.

AdGroupAdService adGroupAdService = (AdGroupAdService) user.GetService(
    AdWordsService.v201506.AdGroupAdService);

AdUrlUpgrade upgrade = new AdUrlUpgrade() {
  adId = adId,
  finalUrl = "http://example.com",
};
try {
  adGroupAdService.upgradeUrl(new AdUrlUpgrade[] { upgrade });
} catch (Exception ex) {
  throw new System.ApplicationException("Failed to upgrade ad.", ex);
}

Keep in mind that changing the URL on an ad, keyword, or sitelink will trigger an editorial review.

When working with both old and new settings, keep in mind that:

Custom parameters and new ValueTrack parameters will not work with legacy destination URLs. They only work with Upgraded URL fields.
Tracking templates will not affect legacy destination URLs, they only work with Upgraded URL fields.
Tracking templates at the account, campaign, or ad group level should have {lpurl} or an equivalent tag.
You cannot mix both old and new settings at the same level. You can, however, mix settings across a hierarchy of objects; and settings at a lower level will override the settings at a higher level. For example, if your ads in an ad group have final URLs but your keywords have destination URLs, then the destination URLs of the keywords will take precedence over the final URLs.

Check out Migrate to Upgraded URLs for more details.

Updating upgraded URLs

Depending on the type of entity, changes to upgraded URL attributes may trigger an editorial review that will prevent your ads from serving until the review is complete.

AdWords Entity	Final URL	Final mobile URL	Final app URL	Custom parameters	Tracking template
Customer	N/A	N/A	N/A	N/A	Serving
Campaign	N/A	N/A	N/A	Serving	Serving
AdGroup	N/A	N/A	N/A	Serving	Serving
Criterion	Stopped	Stopped	Stopped	Stopped	Stopped
FeedItem	Stopped	Stopped	Stopped	Stopped	Stopped
Ad	Stopped	Stopped	Stopped	Stopped	Stopped

Code examples

The AdvancedOperations folder of each client library contains a code example that shows how to set up Upgraded URLs.

Library	AddTextAdWithUpgradedUrls example
Java	AddTextAdWithUpgradedUrls.java
Perl	add_text_ad_with_upgraded_urls.pl
PHP	AddTextAdWithUpgradedUrls.php
Python	add_text_ad_with_upgraded_urls.py
Ruby	add_text_ad_with_upgraded_urls.rb
.NET (C#)	AddTextAdWithUpgradedUrls.cs
.NET (VB)	AddTextAdWithUpgradedUrls.vb

Migrate to Upgraded URLs

The rest of this guide explains how to update your destination URLs to Upgraded URLs using the AdWords API.

Download entities

To migrate your account to use Upgraded URLs, start by retrieving these entities:

AdGroupAdService service =
    (AdGroupAdService) user.GetService(AdWordsService.v201506.AdGroupAdService);

AdGroupAdPage page = service.query("Select AdGroupId, Id, Url where " +
    "Status in [ENABLED, PAUSED]");

Criteria

AdGroupCriterionService service = (AdGroupCriterionService) user.GetService(
    AdWordsService.v201506.AdGroupCriterionService);

AdGroupCriterionPage page = service .query("Select AdGroupId, Id, " +
    "DestinationUrl where Status in [ENABLED, PAUSED]");

Sitelinks

CampaignExtensionSettingService service = (CampaignExtensionSettingService)
    user.GetService(AdWordsService.v201506.CampaignExtensionSettingService);

CampaignExtensionSettingPage page = service.query(
    "Select CampaignId, Extensions where ExtensionType=SITELINK");

Migration is easier if you group by campaign or ad group; refer to our code examples to see how to filter downloads.

URL types

All destination URLs in AdWords broadly fall into one of two types:

	Type 1	Type 2
Description	You don't use any form of tracking in your URLs.	You use tracking parameters or a tracking server to monitor ad performance; or you redirect to another domain.
Example URLs	http://example.com/shoes http://example.com/dresses?color=red	http://example.com/shoes?color=red&kwid;=12345&ad;={creative} http://tracker.example.com/redir?kwid=12345&ad;={creative}&url;=http%3A%2F%2Fwww.example.com%2Fshoes%3Fcolor%3Dred

Migration strategies

We present three migration strategies that cover both destination URL types.

	Strategy 1	Strategy 2	Strategy 3
Summary	Copy destination URL to final URL.	Destination URL is split into tracking and landing page parts. Tracking part is copied to tracking URL template, and landing page URL is copied to final URL.	Destination URL is split into tracking and landing page parts. Common parameters are identified and used to set shared tracking template and custom parameters. Landing page URL is copied to final URL.
Applicable to	Type 1, Type 2	Type 2	Type 2

Benefits during the upgrade
Ad performance statistics retained
No policy review triggered for ads, keywords or sitelinks
Features available after the upgrade
Reduced website load when new ads or keywords are under review
Centralized URL tracking management
Future changes to your shared tracking templates won't reset your ad performance data or interrupt your ad serving
New ValueTrack and custom parameters can be added during the upgrade process	Yes (with review)	Yes (with review)	Yes (with review)

We now discuss each strategy in greater detail.

Strategy 1: Direct copy

This migration strategy is recommended for Type 1 entities. In this approach, we upgrade the entities by copying the destination URL to the final URL, and clearing the destination URL.

Since ad destination URLs cannot be updated once they are created, you need to use the following migration method when updating ads:

List<AdUrlUpgrade> operations = new List<AdUrlUpgrade>();
foreach (AdGroupAd adGroupAd in page.entries) {
  AdUrlUpgrade upgradeUrl = new AdUrlUpgrade();
  upgradeUrl.adId = adGroupAd.ad.id;
  upgradeUrl.finalUrl = adGroupAd.ad.url;
  operations.Add(upgradeUrl);
}
service.upgradeUrl(operations.ToArray());

This way, your ads are upgraded in-place and your ad stats aren't reset.

Criteria

foreach (AdGroupCriterion adGroupCriterion in page.entries) {
  if (adGroupCriterion is BiddableAdGroupCriterion) {
    BiddableAdGroupCriterion biddableAdGroupCriterion =
       (BiddableAdGroupCriterion) adGroupCriterion;
    biddableAdGroupCriterion.finalUrls = new UrlList() {
      urls = new string[] {
        biddableAdGroupCriterion.destinationUrl
      }
    };
    biddableAdGroupCriterion.destinationUrl = null;

    AdGroupCriterionOperation operation = new AdGroupCriterionOperation() {
      @operator = Operator.SET,
      operand = biddableAdGroupCriterion
    };
    operations.Add(operation);
  }
}
service.mutate(operations.ToArray());

Sitelinks

List<CampaignExtensionSettingOperation> operations =
    new List<CampaignExtensionSettingOperation>();
foreach (CampaignExtensionSetting campaignExtensionSetting in page.entries) {
  foreach (ExtensionFeedItem feedItem in
      campaignExtensionSetting.extensionSetting.extensions) {
    if (feedItem is SitelinkFeedItem) {
      SitelinkFeedItem sitelinkFeedItem = (SitelinkFeedItem) feedItem;

      sitelinkFeedItem.sitelinkFinalUrls = new string[] {
        sitelinkFeedItem.sitelinkUrl
      };
      sitelinkFeedItem.sitelinkUrl = null;
    }
  }
  CampaignExtensionSettingOperation operation =
      new CampaignExtensionSettingOperation() {
    operand = campaignExtensionSetting,
    @operator = Operator.SET
  };
  operations.Add(operation);
}
service.mutate(operations.ToArray());

Strategy 2: Use tracking URL template

This migration strategy can be used to upgrade Type 2 entities. It migrates to Upgraded URLs without taking advantage of shared tracking templates or custom ValueTrack parameters. This approach is preferred when tracking parameters remain static throughout the life of the campaign.

Analyze URLs

First, split the destination URL into its tracking template and landing page parts. Insert {lpurl} in the tracking template where the original landing page URL once appeared within the original destination URL.

Destination URL	Tracking template	Landing page
http://example.com/shoes?color=red&kwid;=12345&ad;={creative}	{lpurl}&kwid;=12345&ad;={creative}	http://example.com/shoes?color=red
http://tracker.example.com/redir?kwid=12345&ad;={creative}&url;= http%3A%2F%2Fwww.example.com%2Fshoes%3Fcolor%3Dred	http://tracker.example.com/redir?kwid=12345&ad;={creative}&url;={lpurl}	http://example.com/shoes?color=red

Update entities

Now you can upgrade these entities just like in Strategy 1. You need to additionally set your entity's tracking template to the newly evaluated tracking URL template:

List operations = new List();
foreach (AdGroupAd adGroupAd in page.entries) {
  AdUrlUpgrade upgradeUrl = new AdUrlUpgrade();
  upgradeUrl.adId = adGroupAd.ad.id;
  upgradeUrl.finalUrl = landingPageUrl;

  upgradeUrl.trackingUrlTemplate = trackingUrlTemplate;
  operations.Add(upgradeUrl);
}
service.upgradeUrl(operations.ToArray());

Criteria

foreach (AdGroupCriterion adGroupCriterion in page.entries) {
  if (adGroupCriterion is BiddableAdGroupCriterion) {
    BiddableAdGroupCriterion biddableAdGroupCriterion =
       (BiddableAdGroupCriterion) adGroupCriterion;
    biddableAdGroupCriterion.finalUrls = new UrlList() {
      urls = new string[] {
        landingPageUrl
      }
    };
    biddableAdGroupCriterion.destinationUrl = null;

    biddableAdGroupCriterion.trackingUrlTemplate = trackingUrlTemplate;

    AdGroupCriterionOperation operation = new AdGroupCriterionOperation() {
      @operator = Operator.SET,
      operand = biddableAdGroupCriterion
    };
    operations.Add(operation);
  }
}
service.mutate(operations.ToArray());

Sitelinks

List operations =
    new List();
foreach (CampaignExtensionSetting campaignExtensionSetting in page.entries) {
  foreach (ExtensionFeedItem feedItem in
      campaignExtensionSetting.extensionSetting.extensions) {
    if (feedItem is SitelinkFeedItem) {
      SitelinkFeedItem sitelinkFeedItem = (SitelinkFeedItem) feedItem;

      sitelinkFeedItem.sitelinkFinalUrls = new string[] {
        landingPageUrl
      };
      sitelinkFeedItem.sitelinkUrl = null;
      sitelinkFeedItem.sitelinkTrackingUrlTemplate = trackingUrlTemplate;
    }
  }
  CampaignExtensionSettingOperation operation =
      new CampaignExtensionSettingOperation() {
    operand = campaignExtensionSetting,
    @operator = Operator.SET
  };
  operations.Add(operation);
}
service.mutate(operations.ToArray());

Strategy 3: Use shared tracking template

This strategy can be used to migrate Type 2 entities. It makes use of shared tracking templates and custom ValueTrack parameters. This approach is preferred if you use one or more third-party tracking servers, or your tracking parameters change regularly.

Analyze URLs

First, split your destination URL into its tracking template and landing page parts.

Destination URL	Tracking template	Landing page
http://example.com/shoes?color=red& kwid=12345&ad;={creative}	{lpurl}&kwid;=12345&ad;={creative}	http://example.com/shoes?color=red
http://tracker.example.com/redir? kwid=12345&ad;={creative} &url;=http%3A%2F%2Fwww.example.com%2F shoes%3Fcolor%3Dred	http://tracker.example.com/redir? kwid=12345&ad;={creative}&url;={lpurl}	http://example.com/shoes?color=red

Next, try to identify the reusable tracking URL and tracking parameters in your tracking template. Depending on your account's structure, look for reusable values at either the ad group, campaign, or account level.

Tracking template	Tracking URL	Tracking params
{lpurl}&kwid;=12345&ad;={creative}		kwid= ad=
http://tracker.example.com/redir?kwid=12345&ad;={creative}&url;={lpurl}	http://tracker.example.com/redir	kwid= ad= url=

Define custom parameters to hold values for each of the tracking parameters you identified. (Note the prepended underscore.)

Custom parameter	Value
_kwid	12345
_ad	{creative}

Modify your tracking template to use the new custom parameters.

Destination URL	Tracking template	Custom parameters	Parameter values	Landing page
http://example.com/shoes? color=red&kwid;=12345&ad;={creative}	{lpurl}&kwid;={_kwid}&ad;={_ad}	_kwid	12345	http://example.com/shoes? color=red
	{lpurl}&kwid;={_kwid}&ad;={_ad}	_ad	{creative}	http://example.com/shoes? color=red
http://tracker.example.com/redir? kwid=12345&ad;={creative}&url;=http%3A%2F%2F www.example.com%2Fshoes%3Fcolor%3Dred	http://tracker.example.com/redir? kwid={_kwid}&ad;={_ad}&url;={lpurl}	_kwid	12345	http://example.com/shoes? color=red
		_ad	{creative}	http://example.com/shoes? color=red

Identify shared level

You have to identify the hierarchical level at which each of the shared entities can be placed. For instance, the tracking URL template may be shared at a campaign or account level, whereas a custom parameter might make sense at a keyword level. The code snippet in this guide assumes that both the tracking URL template and custom parameters can be shared at the campaign level.

Update entities

Once you've identified the shareable parts of your destination URLs and their position in the hierarchy, you can set the parameters in your account:

Campaign

CampaignService service =
    (CampaignService) user.GetService(AdWordsService.v201506.CampaignService);

Campaign campaign = new Campaign();
campaign.id = 12345678;

// Specify a tracking URL for 3rd party tracking provider. You can
// specify one at customer, campaign, ad group, ad, criterion or
// feed item levels.
campaign.trackingUrlTemplate =
    "http://tracker.example.com/?kwid={_kwid}&ad={_ad}&url={lpurl}";

// Since your tracking URL has two custom parameters, provide their
// values too. This can be provided at campaign, ad group, ad, criterion
// or feed item levels.
CustomParameter seasonParameter = new CustomParameter();
seasonParameter.key = "kwid";
seasonParameter.value = "12345";

CustomParameter promoCodeParameter = new CustomParameter();
promoCodeParameter.key = "ad";
promoCodeParameter.value = "{creative}";

campaign.urlCustomParameters = new CustomParameters();
campaign.urlCustomParameters.parameters =
     new CustomParameter[] { seasonParameter, promoCodeParameter };

// Create the operation.
CampaignOperation operation = new CampaignOperation();
operation.@operator = Operator.SET;
operation.operand = campaign;

CampaignReturnValue retVal = service.mutate(new CampaignOperation[] { operation });

Since AdWords cannot infer the full destination URL of the ad from its tracking URL template and final URL fields alone, the upgradeUrl method cannot be used in this case. Instead, we need to delete the old ad and create a new one. This will trigger an ad review for the new ad, and its stats will start at zero. The stats of the deleted ad will still be available.

List operations = new List();

foreach (AdGroupAd adGroupAd in page.entries) {
  // Delete the existing ad.
  AdGroupAd adToDelete = new AdGroupAd() {
    adGroupId = adGroupAd.adGroupId,
    ad = new Ad() {
      id = adGroupAd.ad.id
    }
  };

  AdGroupAdOperation removeOperation = new AdGroupAdOperation() {
    operand = adToDelete,
    @operator = Operator.REMOVE
  };
  operations.Add(removeOperation);

  // Make a copy of the ad.
  AdGroupAd adToAdd = new AdGroupAd() {
    adGroupId = adGroupAd.adGroupId,
    ad = adGroupAd.ad
  };

  // Clear the ID to tell AdWords that this is a new ad.
  adToAdd.ad.idSpecified = false;

  // Set the final URL to the newly evaluated landing page URL.
  adToAdd.ad.finalUrls = new string[] {
    landingPageUrl
  };

  // Clear the destination URL.
  adToAdd.ad.url = null;

  AdGroupAdOperation addOperation = new AdGroupAdOperation() {
    operand = adToAdd,
    @operator = Operator.ADD
  };
  operations.Add(addOperation);
}

service.mutate(operations.ToArray());

Criteria

foreach (AdGroupCriterion adGroupCriterion in page.entries) {
  if (adGroupCriterion is BiddableAdGroupCriterion) {
    BiddableAdGroupCriterion biddableAdGroupCriterion =
       (BiddableAdGroupCriterion) adGroupCriterion;
    biddableAdGroupCriterion.finalUrls = new UrlList() {
      urls = new string[] {
        landingPageUrl
      }
    };
    biddableAdGroupCriterion.destinationUrl = null;

    AdGroupCriterionOperation operation = new AdGroupCriterionOperation() {
      @operator = Operator.SET,
      operand = biddableAdGroupCriterion
    };
    operations.Add(operation);
  }
}
service.mutate(operations.ToArray());

Sitelinks

List operations =
    new List();
foreach (CampaignExtensionSetting campaignExtensionSetting in page.entries) {
  foreach (ExtensionFeedItem feedItem in
      campaignExtensionSetting.extensionSetting.extensions) {
    if (feedItem is SitelinkFeedItem) {
      SitelinkFeedItem sitelinkFeedItem = (SitelinkFeedItem) feedItem;

      sitelinkFeedItem.sitelinkFinalUrls = new string[] {
        landingPageUrl
      };
      sitelinkFeedItem.sitelinkUrl = null;
    }
  }
  CampaignExtensionSettingOperation operation =
      new CampaignExtensionSettingOperation() {
    operand = campaignExtensionSetting,
    @operator = Operator.SET
  };
  operations.Add(operation);
}
service.mutate(operations.ToArray());

Mobile URLs

You can provide a separate mobile-preferred final URL if you want to send the user to a different landing page on mobile devices. This is done by setting the entity's finalMobileUrls field. You can also continue to use the existing ValueTrack parameters: {device} and {ifmobile}.

Partial upgrade

You can upgrade part of an account without affecting the remainder. Upgraded URL fields have no effect on an entity if its final URL is not specified. For example, if you specified a tracking URL template at a campaign level, but didn't upgrade the destination URLs for ads within an ad group, then those ads won't be affected by the tracking URL template at the campaign level.

Multiple tracking URLs

If you have more than one tracking server, you can use {lpurl}, {lpurl+2}, and {lpurl+3} to construct your destination URL. Additionally, you can have up to four levels of nesting when specifying the URL tags, e.g.:

{ifmobile:{ifsearch:{keyword:cp={_customP}}}}

Reporting

Once you've upgraded your URLs, you need to update your code to use the Upgraded URL columns instead of destination URL column when retrieving reports. See this section for more details.

Your ad serving stats will remain unaffected in all cases except when using Strategy 3. When using this strategy, you have to delete your old ads and create new copies. This will trigger an ad review for the new ad, and its stats will reset to zero. However, old stats will still be available for the deleted ad.

Migration code examples

Refer to the following code examples in our client libraries to help you through the migration process.

Library	Basic Operation example	UpgradeAdUrl example
Java	basicoperations	UpgradeAdUrl.java
Perl	basic_operations	upgrade_ad_url.pl
PHP	BasicOperations	UpgradeAdUrl.php
Python	basic_operations	upgrade_ad_url.py
Ruby	basic_operations	upgrade_ad_url.rb
.NET (C#)	BasicOperations	UpgradeAdUrl.cs
.NET (VB)	BasicOperations	UpgradeAdUrl.vb

Upgraded URLs

Supported entities

Technical details

Final URL

Final mobile URLs

Final app URLs

Tracking template

Custom parameters

New ValueTrack parameters

Upgraded URLs and sitelinks

Reports

Prepare for Upgraded URLs

Updating upgraded URLs

Code examples

Migrate to Upgraded URLs

Download entities

Ads

Criteria

Sitelinks

URL types

Migration strategies

Strategy 1: Direct copy

Ads

Criteria

Sitelinks

Strategy 2: Use tracking URL template

Analyze URLs

Update entities

Ads

Criteria

Sitelinks

Strategy 3: Use shared tracking template

Analyze URLs

Identify shared level

Update entities

Campaign

Ads

Criteria

Sitelinks

Mobile URLs

Partial upgrade

Multiple tracking URLs

Reporting

Migration code examples

Send feedback about...