How To Use Notifications In Your Gadget

This article was written and submitted by an external developer. The Google Desktop Team thanks Benjamin Schirmer for his time and expertise.

• Introduction
• What Are Notifications Anyway?
• Enable Notifications For Your Gadget
• Display Notifications From Your Gadget
• Conclusion
• Author Bio

Introduction

Notifications (or alerts) are a great way to notify users of incoming messages or breaking news. You might have already encountered them in your mail or instant messaging application. Did you know it is possible to use them in Desktop gadgets too? This article will show you how to enable and implement alerts for your gadget.

Figure 1: Notifications Example

What Are Notifications Anyway?

Figure 1 shows an example of a notification. Gadgets can easily display these notifications, however this feature is disabled by default when the user first installs a gadget. Furthermore, there is no way to automatically or programmatically enable the notifications. You, as a developer, need to tell the user that this feature is available for your gadget and provide instructions on how to enable it.

Enable Notifications For Your Gadget

Figure 2: Configure Gadgets Dialog

The first thing you need to do is tell Google Desktop that your gadget wants to use notifications. This is done in the gmanifest file. If you are using the Google Desktop Gadget Designer, you can do this by going to Project->Settings (or pressing F3) and checking the box that says "Uses notifier for displaying alerts". If you do not use the Google Desktop Gadget Designer, you must manually edit the gadget.gmanifest file. Within the <about> tag add the following:

<displayAPI usesNotifier="true"></displayAPI>

Your gadget will now appear in the "Configure gadgets..." dialog, which is where the user enables alerts (Figure 2). Since there is no way to automatically check the "Enable Alerts" box in the "Configure gadgets..." dialog, you should somehow inform your user that he needs to check this box for your gadget. In the GMail Icon gadget, I've added a help dialog which displays this message:

Alerts are configured using Google Desktop.
Go to the Google Desktop sidebar menu (the downward arrow on the top of the bar) and choose "Configure gadgets...".
In the dialog, enable Alerts for the GMail Icon gadget.
Please note that you must close the options dialog before you can open the sidebar menu.

Display Notifications From Your Gadget

After the user has enabled alerts, you can finally show one by adding a new content item with the gddItemDisplayAsNotification option.

var item = new ContentItem();
item.heading = "Notification Example";
item.snippet = "This is an example for a short notification.";
plugin.AddContentItem(item, gddItemDisplayAsNotification);

You can show several notifications at the same time. When multiple notifications are pending, there will be a counter on top of the notification area with arrows that let the user cycle through the notifications. You should keep in mind that too many notifications may annoy the user and lead him to disable them (or uninstall your gadget entirely).

Conclusion

Many users have become accustomed to notifications through their instant messaging or mail applications, and notifications have become a conventional way to inform a user about new events. Most users should already know how to react to and handle them. Using notifications in your gadget is very easy and can help to improve the user experience.

Author Bio

Benjamin Schirmer holds a diploma in engineering from Albstadt-Sigmaringen University and is an enthusiastic gadget programmer. He loves to explore new technologies. In his spare time, he likes watching movies, TV series, and going out with his friends. In the future, he wants to be a Googler himself. You can visit his gadgets page for a list of all his cool Google Desktop gadgets.

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.