Upgraded URLs separate landing page URLs from tracking parameters, allowing you
to manage tracking logic without triggering ad re-reviews when tracking
parameters change.

Upgraded URLs allow you to specify the tracking and landing page parts of your
URL through separate fields:

- **Final URLs (`final_urls`):** 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 URLs (`final_mobile_urls`):** Represents a list of possible final mobile URLs for your ad, keyword, or sitelink after all cross-domain redirects.
- **Final app URLs (`final_app_urls`):** Represents a list of final app URLs that will be used on mobile devices if the user has the specific app installed.
- **Tracking template (`tracking_url_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.
- **Final URL suffix (`final_url_suffix`):** Optional parameters appended directly to the end of your landing page URL to track landing page activity (for example, with parallel tracking).
- **Custom parameters (`url_custom_parameters`):** Optional [ValueTrack](https://support.google.com/google-ads/answer/2375447) parameters to which you can assign your own IDs.

For detailed specifications, see the [`Ad` reference page](https://developers.google.com/google-ads/api/reference/rpc/v26/Ad).

## Field descriptions

The following sections describe the fields of an Upgraded URL.

### Final URLs (`final_urls`)

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.

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](https://developers.google.com/google-ads/api/docs/ads/upgraded-urls/fields#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 (`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](https://support.google.com/google-ads/answer/2375447) parameters, you can
use existing ValueTrack parameters `{device}` and `{ifmobile}` instead of this
field.

### Final app URLs (`final_app_urls`)

If you have ads that link directly into in-app content using [deep
links](https://support.google.com/google-ads/answer/6046977), or have
[click-to-download ads](https://support.google.com/google-ads/answer/2549053), you can
specify these URLs in the final app URLs field.

### Tracking template (`tracking_url_template`)

The tracking template field lets you 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 such as `{lpurl}`.

### Final URL suffix (`final_url_suffix`)

The final URL suffix field lets you specify tracking parameters that will be
appended to the end of your landing page URL. With parallel tracking, users are
sent directly to the final URL while click measurement happens in the
background, so any parameters that the landing page needs must be placed in the
`final_url_suffix` (or directly in the `final_urls`) rather than the tracking
template.

As with tracking templates, a `final_url_suffix` defined on a lower-level
entity (such as a keyword or ad) overrides one defined on a higher-level entity
(such as an ad group, campaign, or customer).

### Custom parameters (`url_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 example,
in identifying ads. Instead of hardcoding an ID in the ad's destination URL,
you can specify the ID for the ad, use a custom parameter for each ad, and then
refer to the custom parameter in the final URL, the tracking template, or both,
as you would for any other ValueTrack parameter.

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

> [!NOTE]
> **Note:** When setting custom parameter values for a [supported
> entity](https://developers.google.com/google-ads/api/docs/ads/upgraded-urls/supported-entities), items on the `url_custom_parameters` list (e.g., that of an [`Ad`](https://developers.google.com/google-ads/api/reference/rpc/v26/Ad) object) must have a unique [`key`](https://developers.google.com/google-ads/api/reference/rpc/v26/CustomParameter). The uniqueness check is case-insensitive, so your list cannot contain an item with `key="promoCode"` and another item with `key="promocode"`. If you have multiple items with the same `key` in the `url_custom_parameters` list, your request will fail with `DistinctError.DUPLICATE_ELEMENT`.

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

## Example

The following JSON snippet shows an example of configuring an `Ad` object with
Upgraded URL fields:

    {
      "finalUrls": ["https://www.example.com/shoes"],
      "finalUrlSuffix": "src=google&promo={_promoCode}",
      "trackingUrlTemplate": "https://www.tracker.com/?u={lpurl}&alloc={_promoCode}",
      "urlCustomParameters": [
        {
          "key": "promoCode",
          "value": "summer15"
        }
      ]
    }