Upgraded URLs - New in v3

Upgraded URLs (UUs) enable you to better define and control the landing page and tracking of your URLs.

Important

This feature is new in the v3 Gemini API. Gemini partners and developers can now take advantage of UUs. Note that v3 supports both UUs and non-UUs.

Overview

An upgraded URL separates a landing page URL into two major components:

  • Final URL: The URL of the landing page that you want to take your customers to.
  • Tracking Template (with or without Custom Parameters): The URL from tracking tools that allows you to track ad performance.

Using this feature, you can create shared tracking templates, making it easier for you to apply tracking changes across your entire account, campaigns and ad groups.

UUs also enable you to specify separate destination urls for your mobile vs non-mobile traffic.

Specification

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

  • Final URL: Represents the web address a user is sent to after clicking on the ad. Cross-domain redirects are not permitted.
  • Mobile Final URL: Represents the web address a user is sent to after clicking an ad when on a mobile device. If mobileFinalUrl is not set, the finalUrl attribute will be used instead for users of mobile devices. Cross-domain redirects are not permitted.
  • Tracking template: An optional tracking template + macros that allows advertisers to gain insights into ad traffic outside of Gemini.
  • Custom parameters: An optional set of advertiser-defined CustomParameters used to substitute values in the trackingTemplate, finalUrl, and mobileFinalUrl.
  • Display URL Path 1: An optional display url that is visible to the user in the ad copy text. This attribute presents the first path component of the display url.
  • Display URL Path 2: An optional display url that is visible to the user in the ad copy text. This attribute presents the second path component of the display url.

Supported Gemini UU Attributes

The following table describes the supported UU attributes per object type.

Object Landing Url Display Url Final Url Mobile Final Url Tracking Template Custom Parameters Display Url Path1 Display Url Path2
Advertiser no no no no yes no no no
Campaign no no no no yes yes no no
AdGroup no no no no yes yes no no
Ad dp dp yes yes yes yes yes yes
Shared Sitelink dp no yes yes yes yes no no
Keyword dp no yes yes yes yes no no

Note

dp stands for deprecated in the above table.

Note

The landing page url is deprecated only for search. The Final url will be eligible in a native context. Native-only ads are not required to use the final URL and may continue to use the landing page url.

Note

For carousel ads, UU on the ad asset level is not supported because they are native-only.

Fields

An object is considered to be using UUs if it has the finalUrl attribute set. If it is using UUs, then the landingUrl and displayUrl values are ignored. If it is not using UUs, the landingUrl and displayUrl attributes are required.

If you’re using UUs, the UU object contains the following fields:

Name Description Type Add Update
finalUrl The web address a user is sent to after clicking on the ad. Cross-domain redirects are not permitted. string (2048) required optional
mobileFinalUrl The web address a user is sent to after clicking an ad when on a mobile device. If mobileFinalUrl is not set, the finalUrl will be used instead for users of mobile devices. Cross-domain redirects are not permitted. string (2048) optional optional
trackingUrl A tracking template + macros that allows advertisers to gain insights into ad traffic outside of Gemini. string (2048) optional optional
customParameters

A set of advertiser-defined CustomParameters used to substitute values in the trackingTemplate, finalUrl, and mobileFinalUrl.

A CustomParameter is a key/value pair:

  • The key is the macro name. Maximum length is 16 characters.
  • The value is the string that is substituted. Maximum length is 200 characters.
Custom parameter. Note that up to 3 custom parameters are allowed. optional optional
displayUrlPath1 The url visible to the user in the ad copy text. This attribute presents the first path component of the display. string (15) optional optional
displayUrlPath2 The url visible to the user in the ad copy text. This attribute presents the second path component of the display url. string (15) optional optional

If you are not using UUs, the following fields are provided:

Name Description Type Add Update
landingUrl The web address a user is sent to after clicking on the ad. The landing URL should include the tracking params provided by the tracking partner that was specified at the campaign level for app installs. string (2048) required optional
displayUrl The url that is visible to user in the ad copy text. The domain of the displayUrl must match the domain of the landingUrl after its cross-domain redirects. string (35) required optional

Tracking Template

You use tracking to gain insights into your ad traffic outside of Gemini. If tracking is not configured, users will go directly to the landing page specified by the final url field when clicking on the ad.

There are two types of tracking templates:

Template Type Example Description
3rd party tracking https://www.3rdpartytracker.com?source=GEMINI&adId={adId}&d={device}&lp={lpurl} You first make a call to the 3rd-party tracking site to record the ad traffic insights, followed by a redirect to the final url specified in the {lpurl} macro.
site-level tracking {lpurl}?source=GEMINI&adId={adId}&d={device} You make a call to the final url specified in the {lpurl} macro. The extra url parameters capture the ad traffic insights that are logged and recorded by the site.

Types of URL Macros

Important

If you’re working with advertiser, campaign and adgroup tracking url templates, you are required to include a final url macro – for example: {lpurl}.

This is also recommended for tracking templates at the Ad, Sitelink and Keyword levels. If the tracking template does not contain a final url macro, the domain of the tracking url template (after all redirects) must be the same as the final url.

The types of final url macros supported by Gemini are described in the table below:

Parameter Result
{lpurl}

Recommended:

  • {lpurl} if the tracking url template type is site-level tracking, it returns an unescaped final url.
  • {lpurl} if the tracking template type is 3rd-party tracking, returns an escaped final url.
   

{lpurl+2}

  • {lpurl+3}
 
   
{unescapedurl}

Advanced:

  • {unescapedurl} returns the final url unescaped.
   

{escapedurl}

  • {escapedurl+2}
  • {escapedurl+3}
Advanced: returns an escaped final url that is escaped n-times. If n is not specified, the final url is escaped once.

The following characters are escaped : ?, =, ”, #, t, ‘, and [space]. If the final url already contains a question mark, Gemini will replace the question mark in your tracking template with an ampersand (&) or a correctly escaped version of &.

Note

Tracking templates are optional. If the object has an empty tracking template, a traversal up the ancestor path is made to find the first non-empty tracking template. If the traversal does not find a tracking template, then the ad will serve with tracking disabled.

The following describes the order of precedence (per object type) for tracking templates.

tracking hierarchy

Url Parameters

Gemini provides support for the following 3 types of url parameters:

Type Example Description
Content-modifying Parameters http://mywebsite.com?item=2345 Used in final Urls. Parameter influences the landing page destination when clicking an ad.
Value-Tracking Parameters http://mywebsite.com?a={adId} Used in tracking templates. Gemini performs value-tracking substitution for a predefined set of supported macros.
Custom-Tracking Parameters (also known as Custom Parameters) http://mywebsite.com?p={_promo} Used in tracking templates. Gemini performs custom-tracking substitution using advertiser-defined macros and values. Custom Parameters can be identified by a [underscore] prefix in the macro name.

Custom Parameters

Custom Parameters are an advanced type of tracking that allows advertiser-defined values to be included in the tracking and final urls.

For example, you could define an advertiser-level tracking template of {lpurl}?ct={_campaign}. Each campaign could have its own custom parameter (i.e., key/value pair) to denote the type of campaign:

  • Campaign A : {_promo}=blackfriday
  • Campaign B : {_promo}=weekyspecial

Individual custom parameters are resolved by traversing up the ancestor path. The value associated with the closest key will be used in the macro substitution.

Note

Gemini uses a unique union of custom parameter names across all levels in the ancestor path, rather than picking one set of custom parameters from only the closest ancestor level.

The following describes the order of precedence (per object type) for custom parameters.

custom-params-hierarchy

Note the following technical requirements:

  • Up to 3 custom parameters are allowed per object
  • If a key is not found, the macro will not get substituted
  • Blank values are allowed -e.g. {_campaign}=””

Display Url

If you’re not using UUs, the displayUrl attribute is the url displayed in the ad copy.

If you are using UUs, the displayUrl attribute is ignored. Instead Gemini dynamically creates the display url from the following components:

<domain of final url> / displayUrlPath1 / displayUrlPath2

Note the following:

  • The domain of the mobile final url will be used if specified and the user is viewing the ad from a mobile device.
  • displayUrlPath1 and displayUrlPath2 are optional.
  • displayUrlPath1 is required if displayUrlPath2 is specified.
  • Gemini may truncate the display url if it doesn’t fit on certain device types. Truncation will occur on path boundaries.

Bulk Interface

UUs attributes are exposed in the bulk interface.

The following table illustrates the API to Bulk column mapping:

API Attribute Bulk Column
finalUrl Final Url
mobileFinalUrl Mobile Final Url
trackingTemplate Tracking Template
customParameters Custom Parameters
displayUrlPath1 Display Url Path1
displayUrlPath2 Display Url Path 2

Note

Tracking template can’t be modified for the advertiser on bulk.

Up to 3 Custom Parameters may be defined in the Custom Parameters column:

  • Key name is preceded by [underscore] ‘_’ and surrounded by [braces] ‘{ }’
  • Key and Value are separated by [equals] ‘=’
  • Key/Value pairs are separated by [space] ‘ ‘

For example:

{_cparam1}=abc {_cparam2}=xyz

Note

The underscore prefix is required for key names in the bulk interface, since the entire macro is specified, but is not required for key names in the API interface because parts of the macro are specified.

For Custom Parameter updates:

  • An empty Custom Parameters column will be ignored.
  • The contents of a non-empty Custom Parameters column will replace all existing Custom Parameters for the given row type.
  • An empty-set value “[]” will erase any existing Custom Parameters.

Migration Path

To adopt UUs, you should use a top-down approach, i.e.

advertiser->
            campaign->
                      adgroup->
                               ad->
                                   keyword

Doing so will ensure all objects that have finalUrls (e.g., ads, keywords, shared sitelinks) will have well-established tracking templates and custom parameters in their ancestors before being served. If you don’t take this approach, you may introduce gaps and inaccuracies in your tracking reports.

Upgrade Account to Work as UU

To fully upgrade your account to work as a UU account, you need to update all entities to support UUs.

For example:

If you have existing ads, you may choose one of two options. Either (a) create new ads in the Upgraded URL format or (b) add the new fields required to the existing ad. We recommend setting the landingUrl to an empty string “” and then populating the ``finalUrls` and custom parameters with whatever values they have.

If you choose option (a), you will need to use a migration tool if you want to port the existing quality score, for instance.

A before example would look like this, with the inclusion of the landingUrl:

{

...
"landingUrl": "https://www.mywebsite.com/c/10366?source=YAHOO&kw={keyword}&mt={matchtype}&camp={campaignid}&p1={_param1}&p2={_param2}&p3={_param3}",
    "finalUrl": null,
    "mobileFinalUrl": null,
    "trackingUrl": null,
    "customParameters": null,
        "displayUrl": "www.mywebsite.com/promo",
    "displayUrlPath1": null,
    "displayUrlPath2": null,
...

}

An after example would look like this, with the landingUrl as an empty string:

{

...

"landingUrl": "",
    "finalUrl": "https://www.mywebsite.com/c/10366",
    "mobileFinalUrl": "https://m.mywebsite.com/c/10366",
    "trackingUrl": "{lpurl}?source=YAHOO&kw={keyword}&mt={matchtype}&camp={campaignid}&p1={_param1}&p2={_param2}&p3={_param3}",
    "customParameters": [
         {
                 "key": "param1",
                 "value": "abc"
         },
         {
                 "key": "param2",
                 "value": "xyz"
         }
    ],
    "displayUrlPath1": "promo",
    "displayUrlPath2": null,
...

}

How To Calculate & Expand URLs Served at Click Time

You use substitution logic for calculating the URL that is served at click time, as described in the following steps.

To calculate the URL served at click time:

  1. Begin by specifying the Final URL you wish to use: When the ad serves on mobile devices, Mobile Final URL will be used. Otherwise, Final URL will be used.
  2. Define the Tracking Template to use: The lowest in the hierarchy of shared sitelinks (lowest) > KWDU (Keyword Destination URL) > ad > ad group > campaign > account (highest) will be used.
  3. Determine the Custom Parameters to use: The lowest in the hierarchy of shared sitelinks (lowest) > KWDU > ad > ad group > campaign > account (highest) will be used.

Note

Calculating URLs served at click time is for search-only, and search on native campaigns.

Follow these steps to expand the URL served at click time:

  1. Expand the Final URL: Replace Custom Parameters using their corresponding values.
  2. Expand the Tracking Template:
    • Replace Custom Parameters using their corresponding values.
    • If the tracking template URL contains {lpurl} or one of its variants, it’s replaced with the expanded Final URL from step 1.
      • 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
  3. Pick the serving URL: If the tracking template URL is empty, the expanded final URL from step 1 is used. Otherwise, the system uses the expanded tracking template URL from step 2.

Note

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

Example Scenario

example-scenario

Editorial Review

Ads, Keywords, and Shared Sitelinks will continue to undergo editorial review checks - irrespective if you’re using UU or not.

Advertiser, Campaigns, and AdGroups that are UU-enabled are also candidates to undergo editorial checks. This is required under certain conditions to validate that the tracking template adheres to Yahoo’s policies.

A new state of REJECTED is exposed in the status field. In addition, a new field named editorialStatus is exposed in the Advertiser, Campaign and AdGroup objects.

Name Description Type Add Update
status

The status of the object. Valid input values are:

  • ACTIVE
  • PAUSED
  • DELETED
  • REJECTED

The status field is reserved for mutable entity state and user transitions. Note that the REJECTED value here is set by the system editorial review.

enum required optional
editorialStatus

The editorial status of the object. Valid values are:

  • NOT_REVIEWED
  • PENDING_REVIEW
  • APPROVED
  • REJECTED

The editorialStatus field is reserved for read-only system editorial review transitions.

enum n/a (Read-only) n/a (Read-only)

An Example JSON

The following is a JSON snippet of UU attributes that resides in an Ad object:

{

...

    "finalUrl": "https://www.mywebsite.com/c/10366",
    "mobileFinalUrl": "https://m.mywebsite.com/c/10366",
    "trackingUrl": "{lpurl}?source=YAHOO&kw={keyword}&mt={matchtype}&camp={campaignid}&p1={_param1}&p2={_param2}&p3={_param3}",
    "customParameters": [
         {
                 "key": "param1",
                 "value": "abc"
         },
         {
                 "key": "param2",
                 "value": "xyz"
         }
    ],
    "displayUrlPath1": "promo",
    "displayUrlPath2": null,
...

}