Registering with Apple

You are required to register in the Certificates, Identifiers & Profiles section of your developer account to send push notifications. Registration requires an Apple developer license. For more details on registering with Apple, see Developer Account Help.

When registering, include the following information:

• Identifier. This is your unique reverse-domain string, such as web.com.example.domain (the string must start with web.). This is also known as the Website Push ID.

• Website Push ID Description. This is the name used throughout the Provisioning Portal to refer to your website. Use it for your own benefit to label your Website Push IDs into a more human-readable format.

The registration process looks like the form in Figure 2-1.

After you have successfully entered this information, the certificate you use to sign your credentials and to push notifications becomes available to download.

Building the Push Package

When a user is asked for permission to receive push notifications, Safari asks your web server for a package. The package contains data that is used by the notification UI, such as your website name and icon, as well as a cryptographic signature. The signature verifies that your notification hasn’t been intercepted by a man-in-the-middle attack and that it is indeed coming from a trusted source: you.

You create the push package by first populating a folder with a specific set of files. The push package contains a website JSON dictionary, a set of icons (referred to as an iconset), a manifest, and a signature. Listing 2-1 exemplifies the complete push package file structure.

Listing 2-1  File structure of a push package

BayAirlines.pushpackage/

    icon.iconset/

        icon_16x16.png

        icon_16x16@2x.png

        icon_32x32.png

        icon_32x32@2x.png

        icon_128x128.png

        icon_128x128@2x.png

    manifest.json

    signature

    website.json

After the required files are in place, compress the folder into a ZIP archive to create the finalized push package. The push package is a static file that should live on your server. Return the push package from your web server in the location you specify in Downloading Your Website Package.

{

    "websiteName": "Bay Airlines",

    "websitePushID": "web.com.example.domain",

    "allowedDomains": ["http://domain.example.com"],

    "urlFormatString": "http://domain.example.com/%@/?flight=%@",

    "authenticationToken": "19f8d7a6e9fb8a7f6d9330dabe",

    "webServiceURL": "https://example.com/push"

}

{

    "website.json": {

        "hashType": "sha512",

        "hashValue": "4309a0cf6ee37909423fb4f5f762eb530d4a7cfe9e1d30b9c85b602afb9296a508f5df00c6f63439e4dcc4484aae4cd77d1f632678ece0ef1b62ca6c9cbdebb3"

    },

    "icon.iconset/icon_16x16.png": {

        "hashType": "sha512",

        "hashValue": "8bb462e25ca79cca241355f5ae97ffab352acf7d2a0390f6547f1d0a55ade59e01e725bea70778ad2822b1ec137a8c0547197727ae2e9fed620b0d3ddea6803b"

    },

    ...

}

Requesting Permission

There are two important JavaScript functions to keep in mind when dealing with push notifications. The first is a lightweight function that checks the user’s permission level without talking to the server. The second contacts with the server and displays the permission dialog to the user, as shown in Figure 2-2.

To check the permission level a user has set for your website, call window.safari.pushNotification.permission() with your Website Push ID as an argument. This synchronous call returns a permission object for the given identifier by looking in the user’s preferences. This function does not contact your server.

The permission object contains the keys as described in Table 2-2.

To request permission to send the user push notifications, call window.safari.pushNotification.requestPermission(). Requesting permission is an asynchronous call.

window.safari.pushNotification.requestPermission(url, websitePushID, userInfo, callback);

A description of each argument is as follows:

• url—The URL of the web service, which must start with https. The web server does not need to be the same domain as the website requesting permission.

• websitePushID—The Website Push ID, which must start with web..

• userInfo—An object to pass to the server. Include any data in this object that helps you identify the user requesting permission.

• callback—A callback function, which is invoked upon completion. The callback must accept a permission object with the same structure as described in Table 2-2.

Listing 2-3  Handling permissions for website push notifications

var p = document.getElementById("foo");

p.onclick = function() {

    // Ensure that the user can receive Safari Push Notifications.

    if ('safari' in window && 'pushNotification' in window.safari) {

        var permissionData = window.safari.pushNotification.permission('web.com.example.domain');

        checkRemotePermission(permissionData);

    }

};

var checkRemotePermission = function (permissionData) {

    if (permissionData.permission === 'default') {

        // This is a new web service URL and its validity is unknown.

        window.safari.pushNotification.requestPermission(

            'https://domain.example.com', // The web service URL.

            'web.com.example.domain',     // The Website Push ID.

            {}, // Data that you choose to send to your server to help you identify the user.

            checkRemotePermission         // The callback function.

        );

    }

    else if (permissionData.permission === 'denied') {

        // The user said no.

    }

    else if (permissionData.permission === 'granted') {

        // The web service URL is a valid push provider, and the user said yes.

        // permissionData.deviceToken is now available to use.

    }

};

Configuring Your Web Service Endpoints

When a webpage requests permission to display push notifications, an HTTP request for your credentials is sent to your web server. Similarly, when a user changes their website push notification settings in Safari or System Preferences, an HTTP request is sent to your web server. You need to configure a RESTful web service on your server to respond to these requests accordingly. The web service does not need to be hosted on the same server(s) or domain(s) that serve your webpages.

To properly implement the web service, craft your endpoints as specified in the following sections using the URL fragments listed in Table 2-3.

webServiceURL/version/pushPackages/websitePushID

webServiceURL/version/devices/deviceToken/registrations/websitePushID

webServiceURL/version/devices/deviceToken/registrations/websitePushID

webServiceURL/version/log

Pushing Notifications

You send push notifications to clients in the same way that iOS and OS X apps push notifications to APNs. As a push notification provider, you communicate with APNs over a binary interface. This a high-speed, high-capacity interface uses a streaming TCP socket design with binary content. The binary interface is asynchronous.

The binary interface of the production environment is available through gateway.push.apple.com, port 2195. Do not connect to the development environment to send Safari Push Notifications. You may establish multiple parallel connections to the same gateway or to multiple gateway instances.

For each interface, use TLS (or SSL) to establish a secured communications channel. The SSL certificate required for these connections is the same one that’s provisioned when you registered your Website Push ID in your developer account. To establish a trusted provider identity, present this certificate to APNs at connection time.

A JSON dictionary like the one in Listing 2-4 produces a notification that looks like the one in Figure 2-3. The JSON object must strictly conform to RFC 4627.

Listing 2-4  A JSON dictionary showing a sample notification payload

{

    "aps": {

        "alert": {

            "title": "Flight A998 Now Boarding",

            "body": "Boarding has begun for Flight A998.",

            "action": "View"

        },

        "url-args": ["boarding", "A998"]

    }

}

The outermost dictionary, which is identified by the aps key, should contain another dictionary named alert. The alert dictionary may contain only the keys listed in Table 2-4. Custom keys are not supported.

The url-args key specifies an array of values that are paired with the placeholders inside the urlFormatString value of your website.json file. The url-args key must be included. The number of elements in the array must match the number of placeholders in the urlFormatString value and the order of the placeholders in the URL format string determines the order of the values supplied by the url-args array. The number of placeholders may be zero, in which case the array should be empty. However, it is common practice to always include at least one argument so that the user is directed to a web page specific to the notification received.

For a low-level breakdown of notification packets, as well as a code listing of how to send a notification over a binary interface, read Provider Communication with Apple Push Notification Service in Local and Remote Notification Programming Guide.

Troubleshooting

If something goes wrong in downloading your push package or delivery of your push notifications, the logging endpoint on your web service as described in Logging Errors will be contacted with an error message describing the error. Table 2-5 lists the possible errors and steps you can take to fix them.

Also check Web Inspector for errors that might occur in your JavaScript. To learn how to use Web Inspector, read Safari Web Inspector Guide.