Today, for some reason I don’t even remember I opened the Preferences in Safari 6, and I saw this:
The method I’m going to show you after the → is compatible only with WebKit browsers (Chrome, Safari)! And in Firefox with the help of an extension!
1. Can we, are we allowed?
The API can be used through the global
webkitNotifications variable. First of all, let’s test if it’s available, there is no fun in calling methods on an object that doesn’t even exist:
You should place all your API related code inside this condition, this way your code will not be broken for users with incompatible browsers. But, this is not enough, the browser will only accept notifications from user authorized domains, and the authorization request can only be made through user induced events! So onload is out of the question, but we can’t give up yet, my advice is to use a well placed button or other clickable area to catch the user’s attention. We must get that click 😉
Using this method we can request permission. In case the user hasn’t decided yet, the browser will display some kind of prompt to choose if they want to grant permission or not. In some browsers this prompt is not modal, which means we won’t get the result right away. That’s why we have the
callback argument (required in Safari) which is called when the user has decided. If our site has no permission to send notifications, creating them would result in the throwing of security exceptions, which can be caught, but it’s much easier to check permissions, since we have a method just for that.
With this method we can check if the user has decided to grant permission for our site to send notifications or not. There are three possible return values:
PERMISSION_ALLOWED: 0 – permission is granted
PERMISSION_NOT_ALLOWED: 1 – no decision has been made yet, default
PERMISSION_DENIED: 2 – permission is denied
Using all the above we can create our permission request block:
I know some of you may not like
document.write(), but in the example above it’s more than enough to do the job. You may have also noticed that I only handled responses 0 and 1. Most of the case it’s enough, since if the user denied permission (2) we are locked out of the API, and asking again for permission won’t display the prompt either, since modifying this decision can only be made through the browser settings. Of course we can display some message for the user, and ask for revision.
2. Let’s notify!
If all went well, we have our precious permission. Then what are we waiting for?
webkitNotifications.createNotification(icon_url, title, message)
This method creates a notification object instance, the arguments are the url of the icon to be displayed (won’t show in all systems), the primary text, which is the title of the notification, preferebly the name of our application, and finally the secondary text for the body of our message. Important to note, that creating the instance won’t show it right away, we have to make it display! Secondly, the number of displayable notifications are limited on some systems, and if there is no automatic clearing, only the maximum number of visible messages will be shown, leaving the new ones in a queue. Let’s be nice and clean up the mess we make 🙂
show(): Shows the notification
cancel(): Clears the notification, if it’s still visible
We also have four events to handle, namely
With all this knowledge there is only one thing left to do, create a notification:
Ba-dam! That’s all!
It’s pretty easy imho, you can try it out below:
You can find the final code here: https://gist.github.com/3769318#file_final_code.js