Migration Path For Upgraded URLs

This document describes the migration path that you need to follow to upgrade the current Gemini Ad, Keyword and Sitelink entities to Upgraded URLs (UUs), which is for search-only and not native advertisers.

This is important to understand because non-upgraded URLs entities will become Read-only in September 2018. Gemini will NOT auto-migrate these entities.

If you’re a direct-search advertiser and not an advertiser who uses SEM partners, you should read this document.

Context & History

Gemini added support for Upgraded URLs (UUs) in the v3 Gemini API in July 2017. Bulk support was also made available in both the Gemini UI and Bulk. Official Gemini UI support was provided in early October 2017.

In the past, all tracking information would be stored in landing page URLs, along with the intended destination information, except for references to param1.

With the introduction of v3 Gemini API UUs, you could change the way landing page URLs are structured. Because tracking information is split into Tracking URL templates, the intended destination is placed into the Final URLs.

Adding Tracking URLs at various hierarchical levels allows you to make simple changes that cascade down as needed, and avoid the necessity of changing every object underneath. For example, adding the {device} macro to every landing page URL in an account would require updating every landing page URL. This is not the case with UUs, however. The advantages of using UUs are obvious and explicit.

Migration Timeline

The migration timeline is still tentative and subject to change, but these are some of the key takeaways, shown in the table below:

Migration sequence Timeline
UUs support rolled out in v3 of Gemini API. July 2017
Non-UUs supported v2 API are deprecated. July 2018
Non-upgraded entities become READ-ONLY. Note that non-UUs can still be created and updated in v3. September 2018
All READ-ONLY non-UUs entities stop serving. June 2019
EOL for v2 Gemini API. September 2019
v4 Gemini API will only be UU. To be determined

UI Migration Path

To upgrade your non-upgraded entities for search-only campaigns, do the following:

In the Gemini UI, follow these steps:

  1. Select edit on your Ad or Sitelink entity,
  2. Click the Use final URL link.

display url
  1. Enter your Final URL.

final url
  1. Click URL Options (advanced).

url options advanced
  1. Edit the Custom Params and Tracking Templates.

Important

You cannot simply cut-and-paste your landingUrl into the finalUrl. LandingUrl allows for cross-domain redirects for 3rd party tracking while FinalUrl does not.

Note

In the UI, you won’t be able to upgrade your keywords. Keywords can only be modified via Bulk or the API.

In Bulk, follow these steps:

  1. Download the bulk sheet at ad/keyword/sitelink level.
  2. Copy all landing page Urls to the Final Url column and remove display Url.
  3. Remove the tracking macros from the Final Url and put them in the Tracking Template column, as shown in the table below.

Note

Make sure that you follow either one of the template types, described in Tracking templates.


API attribute Bulk column
finalUrl Final Url
mobileFinalUrl Mobile Final Url
trackingUrl Tracking Template
customParameters Custom Parameters
displayUrlPath1 Display Url Path1
displayUrlPath2 Display Url Path2

In Gemini API, follow these steps:

  1. In the v3 API endpoint, make a PUT call on the entity that you would like to upgrade.
  2. Clear out the existing non-upgraded columns:
  • landingUrl
  • displayUrl
  1. Enter the columns that you wish to upgrade:
  • finalUrl
  • mobileFInalUrl
  • trackingUrl
  • customParameters

Bulk Migration Path

For Bulk, follow these steps:

  1. Download the bulk sheet at the ad, keyword and sitelink level.
  2. Move all landing Urls to the Final Url column and remove display Url.
  3. Remove the tracking macros from the Final Url and put them in the Tracking Template column (shown in the table below).

Note

Make sure that you follow either one of the template types, described in Tracking templates.

API attribute Bulk column
finalUrl Final Url
mobileFinalUrl Mobile Final Url
trackingUrl Tracking Template
customParameters Custom Parameters
displayUrlPath1 Display Url Path1
displayUrlPath2 Display Url Path2

API Migration Path

In the Gemini API, follow these steps:

  1. Modify and update an existing ad, using the v3 endpoint, as described above for the API.
  2. Refer to the steps outlined in Upgraded URLs.
  3. Use this sample ad update request JSON.

Note

Ensure that the landing Url and display attributes are set to NULL.

{

...

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

}

FAQ

Will you lose the quality score, history or ranking after upgrading before or after the migration deadline?

If upgraded, the history is maintained. If you create new keywords, normal rules apply.

Will there be any tool to help advertisers upgrade?

No, not currently. However, if you have existing campaigns in Adwords, you can resync from adwords with Gemini adwords sync. This is one possible solution.