Support for Upgraded URLs in AdWords Scripts

AdWords scripts now support Upgraded URLs. Upgraded URLs provide a smarter way for you to manage URLs in AdWords by specifying which part of your URL specifies the landing page, and which part is used for tracking. You can learn more about this feature here.

Here is an example of how to create a new text ad that specifies the final URL instead of destination URL:

var adOperation = adGroup.newTextAdBuilder()
.withHeadline("headline of ad")
.withDescription1("first line of ad description")
.withDescription2("second line of ad description")
.withDisplayUrl("www.example.com")
.withFinalUrl("http://www.example.com")
.build();
var ad = adOperation.getResult();
You can retrieve the Upgraded URL fields of an entity using the urls() method for that entity. If you run reports, the Upgraded URL fields are also available through various performance reports.

Migrating to Upgraded URLs

We encourage all advertisers to upgrade to the new system by July 1, 2015. This involves two parts:
  1. Update your scripts to handle Upgraded URL fields.
  2. Migrate the existing entities in your accounts to Upgraded URLs.
Upgrade scripts

For any new entities that you create using AdWords scripts, we recommend that you set the final URLs instead of destination URLs.

When dealing with existing entities, keep in mind that you may encounter both upgraded and non-upgraded entities in your accounts. If your script reads destination URLs, then make sure it checks both the destination URL and final URL fields of any entity it retrieves. If your script updates destination URLs, use either setFinalUrl() or setDestinationUrl(), depending on whether the entity has been upgraded or not. AdWords scripts will raise an error if you attempt to set both final URL and destination URL for an entity.

Migrate existing entities

You should migrate existing entities to use Upgraded URLs by 1 July, 2015. Refer to our migration guide for upgrading your existing entities to the new URL framework. If you wish to use the Basic upgrade option, you can use the bulk upload feature. If you choose to use the Advanced upgrade option, then you can use Scripts.

If you choose not to upgrade now, and your destination URL does not contain a different domain than the display URL, your destination URL will be updated automatically starting on 1 July 2015. If your destination URL does contain a different domain than the display URL, you will need to manually upgrade the URL or the ad will stop serving shortly after the July 1 deadline.

If you have questions or feedback about these features, let us know on our forum.