Some of you out there in Widget-land may have noticed that we taught a few of the Widgets we build a neat new trick – how to update themselves without the end user ever having to leave his/her desktop. We’ve wanted this feature for some time, and so have other Widget authors. In fact, some of our more proactive authors got tired of waiting around for us and went ahead and implemented Widget update for their own Widgets all by themselves!

Today we’re happy to announce that all Widgets can now take advantage of the new Widget update feature that we began testing and rolling out with the release of Yahoo! Widgets 4. For those of you who haven’t seen this in action, it’s pretty straightforward.

First, the user receives a notification that an update is available:

The user is instructed to view the Dock to see the available updates:

Upon clicking the button, the user is presented with a confirmation dialog:

And voilà! Upon clicking “Install,” the updated Widget is running on the user’s desktop.

We think this is a great feature for Widget authors, because it lets them offer their users a seamless update experience that’s well integrated with the platform. It’s also something that Widget users should love, because in addition to being a huge time-saver, it provides a consistent update interface across all Widgets and it helps us to better ensure your security; only Widgets that have passed the Yahoo! Widget Gallery security checks are eligible for auto-updates.

We’ve been testing this functionality with our own Widgets for a couple months, and we’re now ready to activate update notifications for all Widgets that are set up for it starting today.

A sidenote: we’re the first desktop Widget platform to roll out built-in universal Widget update check! Woohoo!

Developers: here’s how to configure your Widget to use auto-updates.

1.) Insert a unique identifier into your metadata.

Here’s your chance to use widget.xml in your Widget. This metadata file contains the string that uniquely identifies your Widget on our servers (as well as being the place to store the Widget’s name, author, copyright information, default dock image path, and so on). To guarantee a unique value from the get-go, we recommend that your identifier be a UUID, which can be easily generated using the UUID Vault Widget.

If you already have Widgets built that have a unique identifier that isn’t a UUID, don’t worry. We will accept any valid unique identifier (which can only contain alphanumeric characters, periods, hyphens, underscores, and/or exclamation points) as long as it’s truly unique and we have no duplicate already in our system.

An example metadata file with the unique identifier looks like this:

<?xml version="1.0" encoding="utf-8"?>

<metadata>
  <name>The Greatest Widget In The Universe</name>
  <version>1.5</version>
  <identifier>7F6C7DCD-29FC-4475-9408-B762F2048A65</identifier>
  <image usage="dock" src="Images/Dock/Icon.png"/>
  <author name="John Doe" organization="Awesome Stuff, Inc."
  href="http://www.example.com"/>
  <copyright>(c) 2007 Awesome Stuff, Inc.</copyright>
  <description>This Widget fights hunger, advocates for world peace,
  and brings you fresh coffee every morning with a smile.
  </description>
  <platform minVersion="4.0.5" />
</metadata>

2.) Be certain that your version numbers are incremented and in the correct format

Our update check mechanism is dependent upon the format we use for all of our own Widgets as well as Konfabulator itself. For now you’ll need to match this format, which is n.n for major versions and n.n.n for minor versions. Some examples of valid version numbers:

1.0
1.0.2
2.5
3.7.2

You cannot use version numbers such as 1.0a or 3.0b2.

When adding the version tag to your widget.xml file, have only the version number in it. Don’t add characters that aren’t numbers like “ver 3.5″ or “v1.0b”.

<version>1.5</version>

If you currently have a Widget in the Gallery whose version number contains non-numeric characters, you’ll have to change the version number in the Widget’s widget.xml file to the correct format before auto-updates will work.

It’s easy to forget to increment the version number in your metadata, so make sure you do that; otherwise your users won’t receive an update notification!

3.) Submit the Widget to the Gallery!

Once you’ve finished the first two steps, simply submit your updated Widget to the Gallery! We’ll automatically pick up the version number and identifier out of widget.xml during the review of your Widget.

And that’s it, really. In the future, we’re going to offer more granular controls for authors of properly configured Widgets (i.e. have valid unique identifier and version) to manage update notifications, including the ability to opt-out. But for now, if you don’t want to use the auto-update mechanism, simply don’t include the unique identifier in your widget.xml file.