Upgraded URLs¶
Abstract¶
Upgraded URLs (UUs) enable you to better define and control the landing page and tracking of your URLs. UUs are new in the Yahoo Native v3 API and provide support for both UUs and non-UUs.
Some Caveats¶
If you read an ad, keyword or sitelink with the v1 or v2 API that has already been upgraded, a landingURL
field will be generated at read-time. If you update the Landing URL via v1 or v2, the entity will auto-downgrade back to non-UU.
Consider the following expected behavior when working with UUs:
If you use the Yahoo Native v3 API, and include a mix of UU and non-UU attributes, the system will throw an error.
If you use the Yahoo Native v3 API and update an entity with only UU or non-UU attributes (and the entity is in the opposite state), the system will upgrade or downgrade based on the pieces sent.
An attribute set to null or an empty string
("")
will be treated as if it was not included.
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 URL: An optional tracking URL + macros that allows advertisers to gain insights into ad traffic outside of Yahoo Native.
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 Yahoo Native 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 |
---|---|---|---|---|
|
The web address a user is sent to after clicking on the ad. Cross-domain redirects are not permitted. |
string (2048) |
required |
optional |
|
The web address a user is sent to after clicking an ad when on a mobile device. If |
string (2048) |
optional |
optional |
|
A tracking URL + macros that allows advertisers to gain insights into ad traffic outside of Yahoo Native. |
string (2048) |
optional |
optional |
|
A set of advertiser-defined CustomParameters used to substitute values in the A CustomParameter is a key/value pair:
|
Custom parameter. Note that up to 3 custom parameters are allowed. |
optional |
optional |
|
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 |
|
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 |
---|---|---|---|---|
|
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 |
|
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 Yahoo Native. 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 URLs:
Tracking URL 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 |
site-level tracking |
|
You make a call to the final url specified in the |
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 URLs at the Ad, Sitelink and Keyword levels. If the tracking template does not contain a final url macro, the domain of the tracking URL (after all redirects) must be the same as the final url.
The types of final url macros supported by Yahoo Native are described in the table below:
Parameter |
Result |
---|---|
|
Recommended:
|
|
|
|
Advanced:
|
|
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]. Currently, Yahoo Native does not support replacing the question mark in your tracking URL with an ampersand (&).
Note
Tracking URLs are optional. If the object has an empty tracking URL, a traversal up the ancestor path is made to find the first non-empty tracking URL. If the traversal does not find a tracking URL, then the ad will serve with tracking disabled.
The following describes the order of precedence (per object type) for tracking URL.

Url Parameters¶
Yahoo Native provides support for the following 3 types of url parameters:
Type |
Example |
Description |
---|---|---|
Content-modifying Parameters |
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 URL. Yahoo Native 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 URLs. Yahoo Native 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 URL 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
Yahoo Native 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.

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, Yahoo Native 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
anddisplayUrlPath2
are optional.displayUrlPath1
is required ifdisplayUrlPath2
is specified.Yahoo Native 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 |
---|---|
|
Final Url |
|
Mobile Final Url |
|
Tracking Template |
|
Custom Parameters |
|
Display Url Path1 |
|
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 URLs 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:
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.
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.
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:
Expand the Final URL: Replace Custom Parameters using their corresponding values.
Expand the Tracking URL:
Replace Custom Parameters using their corresponding values.
If the tracking 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 URL, 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
Pick the serving URL: If the tracking URL is empty, the expanded final URL from step 1 is used. Otherwise, the system uses the expanded tracking URL from step 2.
Note
Shared Sitelinks are an exception to this rule: If the tracking URL (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¶

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 URL 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 |
---|---|---|---|---|
|
The status of the object. Valid input values are:
The |
enum |
required |
optional |
|
The editorial status of the object. Valid values are:
The |
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,
...
}