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

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 URL + macros that allows advertisers to gain insights into ad traffic outside of Yahoo Native.

string (2048)

optional

optional

customParameters

A set of advertiser-defined CustomParameters used to substitute values in the trackingUrl, 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 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 {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 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

{lpurl}

Recommended:

  • {lpurl} if the tracking URL type is site-level tracking, it returns an unescaped final url.

  • {lpurl} if the tracking URL 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]. 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.

tracking hierarchy

Url Parameters

Yahoo Native 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 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.

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, 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 and displayUrlPath2 are optional.

  • displayUrlPath1 is required if displayUrlPath2 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

finalUrl

Final Url

mobileFinalUrl

Mobile Final Url

trackingUrl

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

  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 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

  3. 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

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

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,
...

}