Upgraded URLs

Upgraded URLs provide greater control and specificity over how you define the landing page and tracking parts of your URLs.

This guide covers the following topics related to Upgraded URLs:

Overview

Previously, destination URLs specified which part of your website users land on when they click your ad. They also encoded additional information for attributing performance back to the ad click. Changes to the destination URL triggered an editorial review for the ad, preventing it from running until the review was complete.

Upgraded URLs introduce shared tracking templates, that separate landing page and tracking portions of the URL, allowing updates to tracking information without triggering an editorial review of the ad.

Specification

Upgraded URLs allow you to specify 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 to which you can assign your own IDs.

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 Checkmark
Campaign Checkmark Checkmark
AdGroup Checkmark Checkmark
Ad Checkmark Checkmark Checkmark Checkmark Checkmark
AdGroupCriterion Checkmark Checkmark Checkmark Checkmark Checkmark
FeedItem (Sitelink) Checkmark Checkmark Checkmark Checkmark Checkmark

Immutability of Ad objects

Ad objects are immutable. Therefore, any attempt to update the final URL or tracking template of an Ad via a SET operation will be silently ignored.

If you want to change attributes of an Ad, you must remove the existing Ad and create a new Ad with the modified attributes.

Field descriptions

The sections below describe the fields that comprise an Upgraded URL.

Final URL

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

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

// Create the expanded text ad.
ExpandedTextAd expandedTextAd = new ExpandedTextAd();
expandedTextAd.headlinePart1 = "Luxury Cruise to Mars";
expandedTextAd.headlinePart2 = "Best Space Cruise Line";
expandedTextAd.description = "Low gravity fun for everyone!";

// 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.
expandedTextAd.finalUrls = new string[] {
    "http://www.example.com/cruise/"
};

// 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.
expandedTextAd.finalMobileUrls = new string[] {
    "http://mobile.example.com/cruise/"
};

AdGroupAd expandedTextAdGroupAd = new AdGroupAd();
expandedTextAdGroupAd.adGroupId = adGroupId;
expandedTextAdGroupAd.ad = expandedTextAd;

// 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 the ad level.

All existing 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:

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

Most of the time, you 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 that don't go through a common landing page on the advertiser's domain (for example, when testing landing pages), you can specify these landing pages using multiple final URLs.

Final mobile URLs

If you want to send users to a different landing page on mobile devices you can provide a separate mobile-preferred final URL. However, if you prefer using ValueTrack parameters, you can use existing ValueTrack parameters {device} and {ifmobile} instead of 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, you can specify these URLs in the final app URLs field.

Tracking template

The tracking template field allows you to specify any additional tracking parameters or redirects. When this parameter is specified, it will be used, instead of final URLs, to assemble the actual destination URL for your ad. The tracking service tracks the click and redirects 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 ValueTrack parameters like {lpurl}.

To change tracking parameters on any supported entity except an Ad, you only need to update the tracking template. This allows your ads to continue serving uninterrupted, without triggering a new review of the ad. 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 overrides the setting specified on a higher level entity. For example, a tracking template at the campaign level overrides the setting at the account level.

Custom parameters

Custom parameters allow you to create your own parameters, similar to ValueTrack parameters. This can be useful when you want to use your own IDs, for instance, in identifying keywords. Previously, you'd have 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.

In the code example below, the tracking URL template is set to the following:

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

This code example adds custom parameters to a campaign:

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, for example, {_promoCode}.

As with final URLs, custom parameters in a lower level entity override values for 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.

ValueTrack parameters for Upgraded URLs

The following ValueTrack parameters can 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} instead. This is supported only in tracking URLs.

For more details on these parameters, see

Sitelinks support Upgraded URLs using FeedItem attributes. The table below shows the relevant placeholders:

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. Keep in mind that final URLs and final mobile URLs are rendered in the report as a list of values separated by a semicolon, as shown below:

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

Similarly, custom parameters are 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.

Updating Upgraded URLs

Changes to Upgraded URL attributes may trigger an editorial review, preventing your ads from serving until the review is complete, depending on the entity type:

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 Advanced Operations folder of each client library contains a code example for adding an expanded text ad with Upgraded URLs.

Serving URL expansion rules

When using Upgraded URLs, the serving URL for an ad or ad extension is constructed by combining various fields according to a set of rules. This section examines these rules in more detail.

Hierarchy of AdWords entities

When resolving Upgraded URL fields, the following hierarchy (highest to lowest) is used by AdWords servers:

Customer
    Campaign
        Ad Group
            Ads
                Ad Group Criteria
                    FeedItems (including sitelinks)

Which final URL is used?

The final URL is used by default when building the serving URL. If an entity is served on a mobile network and has a valid final mobile URL, then that is used instead of the final URL. Final app URL is currently supported only for mobile re-engagements ads.

How the system expands the serving URL

Here are the steps the system goes through when expanding the serving URL:

  1. Determine which final URL to use.

    It starts by determining which final URL to use. This varies depending on the entity involved.

    Entity Which final URL to use?
    FeedItems (sitelinks) Always use own final URL.
    Ad X served on keyword Y If the keyword has own final URL, use it. Otherwise use the ad’s final URL.
  2. Determine which tracking URL template to use.

    The tracking URL for an entity is determined by traversing its object hierarchy, and choosing the value from the entity lowest in the hierarchy. If no tracking URL template values can be found in the hierarchy, the tracking URL template’s value is set to empty.

    For example, if an ad has tracking URL template values defined only at its parent ad group and account levels, the value from the parent ad group is used.

  3. Determine which custom param values to use.

    The value for a given custom param is resolved by traversing the object hierarchy, and choosing the value from the entity lowest in the hierarchy. If no value is defined for the custom param, an empty string is used as its value.

    For example, when determining the value for a particular custom param at the ad level, if that custom param has values defined at its parent ad group and at the account level, the value from the parent ad group is used.

  4. Expand the final URL.

    The system expands the final URL by performing the following three steps:

    1. Expand the custom param values.

      The system parses the final URL and substitutes the values for each custom parameter in the URL, using the values determined in step 3 above.

    2. Expand the ValueTrack tags in the URL.

      The system parses the final URL, and substitutes values for any ValueTrack tags present in the URL.

    3. Strip the {ignore} tag.

      Any {ignore} ValueTrack parameter in the expanded final URL is removed.

  5. Expand the tracking template.

    If there's an empty value for the tracking template (as determined above in step 2), this step is skipped. Otherwise, the tracking URL template is expanded as follows:

    1. Expand the custom param values.

      The system parses the tracking template URL, and substitutes the values for each custom parameter in the URL using the values determined in step 3.

    2. Expand the ValueTrack tags in the URL.

      The system parses the tracking template URL, and substitutes values for any ValueTrack tags present in the URL.

    3. Substitute {lpurl} parameter in tracking template.

      If the tracking template URL contains {lpurl} or one of its variants, it's replaced with the expanded final URL from step 4.

      • If {lpurl} is inserted at the beginning of the tracking template, then it is not escaped. If it is elsewhere in the tracking template, it escapes the characters ?, =, ", #, \t, ', and [space].
      • {unescapedlpurl} is always unescaped
      • {escapedlpurl} is always escaped
      • {lpurl+2} is always escaped twice
      • {lpurl+3} is always escaped three times
  6. Pick the serving URL.

    If your tracking template URL is empty, the expanded final URL from step 4 is used. Otherwise, the system uses the expanded tracking template URL from step 5.

    Sitelinks are an exception to this rule: If the tracking URL template (determined in step 2) does not contain the {lpurl} parameter, then the sitelink’s final URL is used as the serving URL.

Example scenarios

Consider an account with the following structure:

Account
    Campaign 1
        Ad Group 1
            Ad 1
            Keyword 1 (shoes)
            Keyword 2 (hats)
        Ad Group 2
            Ad 2
            Ad 3
            Keyword 3 (watches)
    FeedItem 1 (sitelink 1)

Assume the following Upgraded URL fields are defined on these entities:

Entity name Tracking URL template Final URL Custom Parameters
Account http://www.cid1-tracking.com/?{_myid}&u={lpurl}
Campaign 1 _mycampaign=cam1
Ad Group 1 http://www.ag1-tracking.com/?{_mycampaign}&u={lpurl}&{_myid} _myid=ag1id
Ad Group 2 myid=ag2id
Ad 1 http://www.creative1-final.com/?{keyword}{ignore}&{_myid}&{_mycampaign}
Ad 2 http://www.creative2-final.com/?{keyword}{ignore}&{_myid} _myid=ad2id
Ad 3 http://www.ad3-tracking.com/?{_mycampaign}
Keyword 1 final URL: http://www.kw-final.com/?{keyword}{ignore}&{_mycampaign}

final mobile URL: http://m.kw-final-mobile.com/?{keyword}{ignore}&{_myid}
_myid=k1Id
Keyword 2
Keyword 3
FeedItem 1 final URL: http://www.sitelink-final.com/?{keyword}{ignore}&{_mycampaign}

final mobile URL: http://m.sitelink-final-mobile.com/?{keyword}{ignore}&{_myid}

The following values are used for expanding the ValueTrack parameter {keyword}:

  • Keyword 1: shoes
  • Keyword 2: hats
  • Keyword 3: watches

The following sections show how various parameters get resolved for each of these entities.

Enviar comentarios sobre…

¿Necesitas ayuda? Visita nuestra página de asistencia.