Notification Programming Guide for Websites Contents About Notifications for Websites 4 At a Glance 5 Users Control Their Notifications 5 Safari Push Notifications Are Deployed from Your Server 5 Local Notifications Are Invoked with JavaScript 5 See Also 5 Understanding the User Experience 7 Local Versus Website Push Notifications 7 Opting In to Notifications 9 Users Can Change Their Notification Preferences 10 Configuring Safari Push Notifications 12 Registering with Apple 12 Certificate Revocation 13 Building the Push Package 14 The Website JSON Dictionary 15 The Iconset 16 The Manifest 16 The Signature 16 Requesting Permission 17 Configuring Your Web Service Endpoints 20 Downloading Your Website Package 20 Registering or Updating Device Permission Policy 20 Forgetting Device Permission Policy 21 Logging Errors 21 Pushing Notifications 22 Troubleshooting 24 Configuring Local Notifications 26 Requesting Permission 26 Creating and Interacting with Local Notifications 27 Document Revision History 31 2013-08-20 | Copyright © 2013 Apple Inc. All Rights Reserved. Apple Confidential Information. 2 Figures, Tables, and Listings About Notifications for Websites 4 Figure I-1 Notifications in Notification Center 4 Understanding the User Experience 7 Figure 1-1 A banner showing a local notification 7 Figure 1-2 A local notification in Notification Center 7 Figure 1-3 A banner showing a push notification sent from a web server 8 Figure 1-4 A push notification in Notification Center 8 Figure 1-5 Requesting to display local notifications 9 Figure 1-6 Requesting to display push notifications 9 Figure 1-7 Controlling which websites have authorization to send notifications 10 Figure 1-8 Adjusting the appearance of notifications 11 Configuring Safari Push Notifications 12 Figure 2-1 Register as a push provider with Apple 13 Figure 2-2 The user controls their notification permissions 17 Figure 2-3 The resulting push notification 23 Table 2-1 Allowed keys in the website.json file 15 Table 2-2 The permission object structure 18 Table 2-3 A web service’s endpoint URL fragments 20 Table 2-4 Alert dictionary structure 23 Table 2-5 Logging endpoint error messages 24 Listing 2-1 File structure of a push package 14 Listing 2-2 A sample valid website.json file 15 Listing 2-3 Handling permissions for website push notifications 19 Listing 2-4 A JSON dictionary showing a sample notification payload 22 Configuring Local Notifications 26 Figure 3-1 A dialog box prompting for permission 27 Figure 3-2 A notification banner 27 Figure 3-3 A notification in Notification Center 28 Table 3-1 Available notification events 28 Listing 3-1 Implementing local notification support 29 2013-08-20 | Copyright © 2013 Apple Inc. All Rights Reserved. Apple Confidential Information. 3 About Notifications for Websites Important: This is a preliminary document for an API or technology in development. Although this document has been reviewed for technical accuracy, it is not final. This Apple confidential information is for use only by registered members of the applicable Apple Developer program. Apple is supplying this confidential information to help you plan for the adoption of the technologies and programming interfaces described herein. This information is subject to change, and software implemented according to this document should be tested with final operating system software and final documentation. Newer versions of this document may be provided with future seeds of the API or technology. Notifications are concise, unobtrusive messages that appear in the top-right corner of the screen, alerting Mac users about a new message or a completed task. As a web developer, you can configure your website to send notifications to Mac users, even if you don’t have a native Cocoa app. Figure I-1 Notifications in Notification Center There are two kinds of notifications for websites: ● Safari Push Notifications, which is an Apple-exclusive technology and triggered remotely using Apple Push Notification service (APNs). ● Local Notifications, which are specified by a W3C standard and triggered locally using JavaScript. 2013-08-20 | Copyright © 2013 Apple Inc. All Rights Reserved. Apple Confidential Information. 4 About Notifications for Websites At a Glance Note: This document pertains to OS X only. Notifications for websites do not appear on iOS. At a Glance This document explains the key concepts of notifications for websites and how to implement them in your ecosystem. Users Control Their Notifications Review the preferences available to users to better understand how to implement your notification service. Relevant Chapter: “Understanding the User Experience” (page 7) Safari Push Notifications Are Deployed from Your Server In OS X v10.9 and later, you can send push notifications to your website users. Safari doesn’t need to be open for the notification to appear, and your visitors have control over their notification settings on a per-website basis. Relevant Chapter: “Configuring Safari Push Notifications” (page 12) Local Notifications Are Invoked with JavaScript In OS X v10.8 and later, you can tap into Notification Center through a JavaScript API. After visitors grant permission to receive local notifications, you can trigger notifications to appear as long as the webpage remains in an open tab. Relevant Chapter: “Configuring Local Notifications” (page 26) See Also ● WWDC 2013: Implementing OS X Push Notifications for Websites shows best practices for implementing push notifications for websites. ● Local and Push Notification Programming Guide describes how to send push notifications to iOS and OS X apps. 2013-08-20 | Copyright © 2013 Apple Inc. All Rights Reserved. Apple Confidential Information. 5 About Notifications for Websites See Also ● WebKit DOM Programming Topics describes other JavaScript APIs available to WebKit browsers. ● Safari Web Content Guide describes how to create websites for Safari. 2013-08-20 | Copyright © 2013 Apple Inc. All Rights Reserved. Apple Confidential Information. 6 Understanding the User Experience To best serve notifications to your users, you must first understand how OS X displays notifications. In this chapter, you learn the difference between local notifications and push notifications for websites, how users grant permission for websites to display notifications, and how users manage their notification preferences. Local Versus Website Push Notifications Starting in OS X v10.8, Safari users can allow websites to display banners and alerts in Notification Center. Through a JavaScript API, you can create notifications that appear and behave like notifications from native Cocoa apps, as shown in Figure 1-1 and Figure 1-2. Figure 1-1 A banner showing a local notification Figure 1-2 A local notification in Notification Center Because local notifications are controlled entirely by JavaScript, the user must have your website open in a Safari window (or tab) for your notification to appear. Safari can be minimized or hidden, or your website could be loaded in an inactive tab, but it must be open to run the JavaScript that creates the notification. 2013-08-20 | Copyright © 2013 Apple Inc. All Rights Reserved. Apple Confidential Information. 7 Understanding the User Experience Local Versus Website Push Notifications Local notifications display the Safari icon, and appear under the Safari section in Notification Center. The Safari section in Notification Center is where local notifications from all websites appear. The notification title, domain, and body are shown. Because local notifications appear as coming from Safari, rather than from your website directly, the user’s notification preferences for Safari are applied. Push notifications are similar to local notifications. They exhibit the same appearance, except that they have their own icon and section in Notification Center, as shown in Figure 1-3 and Figure 1-4. Figure 1-3 A banner showing a push notification sent from a web server Figure 1-4 A push notification in Notification Center Unlike local notifications, push notifications don’t display the website domain, because the icon makes it clear which website it represents. More importantly, push notifications can be received even when Safari is closed. 2013-08-20 | Copyright © 2013 Apple Inc. All Rights Reserved. Apple Confidential Information. 8 Understanding the User Experience Opting In to Notifications Note: If you already have an OS X app, you should push notifications through your app. To avoid sending duplicate notifications to users who accept notifications from both your app and website, you need to add extra logic in your server-side scripts. See “Configuring Your Web Service Endpoints” (page 20). Opting In to Notifications Users must opt in to receive notifications. The opt-in process only occurs once per domain. The presentation of asking for permission is identical for all website notifications. In fact, the permission policy that a user chooses for push notifications applies to local notifications. Compare the appearance of requesting both kinds of notifications in Figure 1-5 and Figure 1-6. Figure 1-5 Requesting to display local notifications Figure 1-6 Requesting to display push notifications As you can see, the permission sheets for local and push notifications look very similar. The request appears only once; after a user sets the permission level, the preference is saved. 2013-08-20 | Copyright © 2013 Apple Inc. All Rights Reserved. Apple Confidential Information. 9 Understanding the User Experience Users Can Change Their Notification Preferences Remember: Allowing or denying a request for push notifications sets the same permission level for local notifications as well. Users Can Change Their Notification Preferences Users can adjust their notification preferences in Safari preferences and System Preferences. In Safari preferences, users can choose to allow or deny notifications from websites on a per-domain basis by selecting Notifications, as shown in Figure 1-7. In the Notifications pane, users can grant permission for some websites to send notifications while denying permission to others. Figure 1-7 Controlling which websites have authorization to send notifications 2013-08-20 | Copyright © 2013 Apple Inc.