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.

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:

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

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:

Types of URL Macros¶

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:

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 (&).

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:

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.

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

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

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.

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.

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.

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

}