Simple Push

この記事はまだ日本語に翻訳されていません。MDN の翻訳はボランティアによって行われています。是非 MDN に登録し、私たちの力になって下さい。

This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for the proper prefixes to use in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the spec changes.

The Simple Push API, also known as the Push Notification API, provides apps the ability to be woken up to receive notifications. Apps can request a URI they can share with their servers, that the server can use to send version numbers back to the app. This could be used as a sync mechanism, or even to fetch the latest data from third party servers.

The SimplePush API extends window.navigator with a push property which is a PushManager object, and adds some new events you can receive to monitor the push status.

Example

In this example we go through the whole setup of the push API. Follow these steps:

  1. Add the push permission to the app's manifest file.
  2. Call push.register() to request an endpoint.
  3. Send the endpoint to your server.
  4. Add a message handler for push notifications inside your app.
  5. Send a notification from your server using the endpoint.

Modify manifest file

You need to change two things in your manifest file:

  1. messages field - Add push and push-register messages.
  2. permissions field - Add that your app wants to receive push notifications.
"messages": [
   { "push": "/index.html"},
   { "push-register": "/index.html"}
],
"permissions": {
  "push": {
    "description": "Required for being updated with new goals in soccer matches",  
  }
}

Call PushManager.register to request an endpoint

This code should be called when you decide it is time to ask for an endpoint. For example, when the user has logged in, or when she decides to start watching a soccer match.

if (navigator.push) {
  var req = navigator.push.register();
  
  req.onsuccess = function(e) {
    var endpoint = req.result;
      console.log("New endpoint: " + endpoint );
    }

   req.onerror = function(e) {
     console.error("Error getting a new endpoint: " + JSON.stringify(e));
   }
} else {
  // No push on the DOM
}

Send endpoint to your server

Once you have your endpoint, you need to send it to your application server. There is not just one way, because you can do with it what you like, for example sending an email, sending it by POST, PUT, or even GET. We recommend that you store the endpoint with some user data from the application, such as a cookie, a username, or whatever you use to identify your endpoint-user pair.

But if you are sending to your server, we recommend that you follow these good practices:

  1. Send it by XMLHttpRequest.
  2. Always use HTTPS. Otherwise if someone intercepts your endpoint, they could start sending notifications to your app.
  3. Use something to match the user (or application installation) to the endpoint, like a cookie.

Add the push message handler

Once you have set up your endpoint, you are ready to have the app start listening for push messages. This could be registered on the main index.html file or in your main.js script, but could be in a specific push-message.html file with only the script there. That could be useful if you receive a push message and your app is closed, because it will load just a small part of your HTML/JavaScript code, and you can decide if the app needs to be fully open or do something in the background.

if (window.navigator.mozSetMessageHandler) {
  window.navigator.mozSetMessageHandler('push', function(e) {
    console.log('My endpoint is ' + e.pushEndpoint);
    console.log('My new version is ' +  e.version);
    //Remember that you can handle here if you have more than
    //one pushEndpoint
    if (e.pushEndpoint === emailEndpoint) {
      emailHandler(e.version);
    } else if (e.pushEndpoint === imEndpoint) {
      imHandler(e.version);
    }
  });
} else {
  // No message handler
}

Add the push-register message handler

Please, be sure to add this handler and check that it works. If you do not re-register your endpoints when this comes, you WILL NOT BE ABLE to receive more push notifications

The push-register message is sent to all apps when the device changes its UAID (because the push server has changed or it went down and need recovery or other circumstances) and it means that you MUST re-register again for all your endpoints, because your previous ones are not valid anymore.

if (window.navigator.mozSetMessageHandler) {
  window.navigator.mozSetMessageHandler('push-register', function(e) {
    console.log('push-register received, I need to register my endpoint(s) again!');

    var req = navigator.push.register();
    req.onsuccess = function(e) {
      var endpoint = req.result;
      console.log("New endpoint: " + endpoint );
      localStorage.endpoint = endpoint;
    }

    req.onerror = function(e) {
      console.error("Error getting a new endpoint: " + JSON.stringify(e));
    }
  });
} else {
  // No message handler
}

Send a notification

Once you have the endpoint on your server, to send a notification is as easy as sending an HTTP PUT request to the endpoint with the body version=<version>. Imagine an endpoint with URL:

https://as.push.tefdigital.com/v1/notify/abcdef01234567890abcdefabcdef01234567890abcdef

and version 5:

version=5

With curl:

curl -X PUT -d "version=5" https://as.push.tefdigital.com/v1/notify/abcdef01234567890abcdefabcdef01234567890abcdef

If the server is running correctly, you will get a response with a 200 Status (OK) and a {} as a body. If not, a valid JSON explaining the error is sent.

Remember that version should be integer numbers, and incremental. Applications will not get new notifications if the new version is lower than that stored on the server and/or device.

Unregister an endpoint

Once you finish using an endpoint and you do not want to receive more notifications, we kindly ask you to PushManager.unregister the old endpoint. This will clean up the amount of data the device sends to the Push Server, and also will lower the battery usage by not sending notifications for apps that will not use them.

Specifications

Specification Status Comment
Push API Working Draft Non standard

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support Not supported Not supported Not supported Not supported Not supported
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support Not supported Not supported

18.0 (18) moz

(From FirefoxOS 1.1)

Not supported Not supported Not supported

Gecko implementation note

This API is currently available on Firefox OS only for any installed applications.

See also

Document Tags and Contributors

最終更新者: rafael.nery,