|
|
| (75 intermediate revisions by 11 users not shown) |
| Line 1: |
Line 1: |
| <h2> Client Side API </h2> | | <p style="border:2px solid red;border-radius:5px;background-color:#FFF;box-shadow:5px 5px 10px #888;padding:.5em;text-align:center;text-weight:bold;font-size:120%;">'''For documentation on <b>Using SimplePush in your App</b>, please see [https://developer.mozilla.org/en-US/docs/Web/API/Simple_Push_API the MDN SimplePush Documentation]'''</p> |
| <pre> | |
|
| |
|
| partial interface Navigator {
| | <p style="border:2px solid red;border-radius:5px;background-color:#FFF;box-shadow:5px 5px 10px #888;padding:.5em;text-align:center;text-weight:bold;font-size:120%;">'''For documentation on <b>the Service</b>, please see [http://mozilla-push-service.readthedocs.org/en/latest/ the Mozilla Push Service Documentation]'''</p> |
| PushNotification pushNotification;
| |
| };
| |
|
| |
|
| interface PushNotification : EventTarget {
| | Go here for [[Firefox/Push_Notifications|project page]] |
|
| |
|
| // registers to receive push notifications for a given topic
| | [[Category:Web APIs]] |
| // DOMRequest.result is a PushRegistration in case of success
| |
| DOMRequest register();
| |
| | |
| // registers to stop receiving push notifications for a given topic
| |
| // DOMRequest.result is a PushRegistration in case of success
| |
| DOMRequest unregister(ChannelID channelID);
| |
| | |
| // returns the list of all push registrations for this origin
| |
| PushRegistration[] registrations();
| |
| };
| |
| | |
| interface PushRegistration {
| |
| // this is the URL to which push notifications from the web application
| |
| // must be sent to.
| |
| // application should send this and pushRequestID as a pair to the
| |
| // application server
| |
| DOMString pushEndpoint;
| |
| | |
| // this is the push request id that must be sent to the push server with
| |
| // every push notification update
| |
| DOMString channelID;
| |
| };
| |
| | |
| interface PushEvent : Event {
| |
| // this is topic string used when registering for push notifications
| |
| DOMString channelID;
| |
| | |
| // this is the most current version
| |
| unsigned long long version;
| |
| }
| |
| | |
| </pre>
| |
| | |
| == Client Example ==
| |
| | |
| === App manifest ===
| |
| <pre>
| |
| | |
| {
| |
| ...
| |
| "permissions": {
| |
| ...
| |
| "push": {
| |
| "description": "Check for new mail"
| |
| }
| |
| },
| |
| "messages": [
| |
| {"notification": "/view_to_launch.html"}
| |
| {"notification-register": "/view_to_launch.html"}
| |
| ]
| |
| }
| |
| | |
| </pre>
| |
| | |
| === JavaScript ===
| |
| <pre>
| |
| | |
| // all notifications will be sent to the system message handler.
| |
| // which is up to the U/A to implement
| |
| | |
| // apps can do something like
| |
| // This handler may be triggered *immediately* after mozSetMessageHandler is called
| |
| // so applications should ensure they are ready (UI created, state loaded etc.)
| |
| navigator.mozSetMessageHandler('push-register', {
| |
| handleMessage: function(e) {
| |
| // (re)issue register() calls
| |
| // to register to listen for a notification,
| |
| // you simply call push.register
| |
| navigator.pushNotifications.register();
| |
| }
| |
| });
| |
| | |
| navigator.mozSetMessageHandler('push', {
| |
| handleMessage: function(e) {
| |
| e.channelID == This is the topic that is being observed
| |
| e.version == This is the current version for this topic
| |
| }
| |
| });
| |
| | |
| | |
| // to unregister, you simply call..
| |
| | |
| navigator.pushNotifications.unregister(channelID);
| |
| </pre>
| |
| | |
| == Server API ==
| |
| | |
| === Definitions ===
| |
| ;UserAgent
| |
| :The client acting on behalf of the user and consumer of update notices
| |
| | |
| ;UAID
| |
| :A server generated, globally unique UserAgent ID
| |
| | |
| ;PushServer
| |
| :The server managing interactions between AppServers and the UserAgent
| |
| | |
| ;AppServer
| |
| :The third party publisher of update notices
| |
| | |
| ;Channel
| |
| :The flow of information from AppServer through PushServer to UserAgent
| |
| | |
| ;ChannelID
| |
| :Globally Unique identifier for a Channel
| |
| | |
| UserAgent and AppServer will use a RESTful API to interact with the Push Server.
| |
| | |
| === API ===
| |
| * Requests from UserAgent to PushServer MUST provide a PushServer Generated UserAgentID (UAID) as the "X-UserAgent-ID" header.
| |
| * All requests and responses '''MUST''' include a <tt>digest</tt> field which is a SHA1 checksum of known channelIDs at the sender. This should be calculated from the state of the persistent database. If a mismatch occurs, it is resolved using the Registration Sync Protocol.
| |
| Digest calculation:
| |
| ** <tt>channels</tt> = Sort channelIDs by lexicographically increasing order as '''strings'''
| |
| ** <tt>str</tt> - Join sorted channelIDs using a '''comma''' (,)
| |
| ** <tt>digest</tt> = SHA1(tt)
| |
| '''NOTE:''' Digest inconsistency will occur during /register and /unregister. This should NOT be considered as a state mismatch.
| |
| * UserAgent requests may include a /{network} prefix to indicate a request may be handled by a third party network (e.g. <code>GET http:<i>host</i>/foonet/update</code> will return update requests for elements provided by the "foonet" sub-provider.
| |
| * Calls will return standard HTTP status headers.
| |
| * Calls will return status 200 (unless otherwise noted below).
| |
| * On Errors, calls will return a proper error code, and where permitted, a standard JSON block containing information regarding the error. The contents of this block are not intended for end user display and have yet to be finalized.
| |
| | |
| ==== GET /v1/register/<channelID> ====
| |
| Request a new ChannelID.
| |
| | |
| If the <i>X-UserAgent-ID</i> is not provided, the UserAgent is presumed to be new and a new UAID will be generated for the UserAgent.
| |
| | |
| The PushServer '''SHOULD''':
| |
| * Ensure that the channelID is compliant with any formatting requirements the PushServer may have
| |
| * Ensure that the channelID is unique for the UAID.
| |
| | |
| ===== Arguments =====
| |
| | |
| No additional arguments are required.
| |
| | |
| ===== Returns =====
| |
| { "channelID": "New Channel ID",
| |
| "uaid": "UserAgent ID" (optional)
| |
| }
| |
| | |
| NOTE: The uaid is either the X-UserAgent-ID value echoed back, or a new X-UserAgent-ID value to be used for all subsequent calls if no X-UserAgent-ID was present.
| |
| | |
| ===== Errors =====
| |
| | |
| * Invalid Channel ID
| |
| * Duplicate Channel ID
| |
| | |
| ===== Example =====
| |
| GET http://push.m.o/v1/register
| |
| ---
| |
| {"channelID": "foo1234", "uaid": "bar5678"}
| |
| | |
| ==== DELETE /v1/<ChannelID> ====
| |
| Delete an associated ChannelID. Subsequent calls to this ChannelID will result in a 404 status.
| |
| | |
| NOTE: the X-UserAgent-ID Header must be present and match the one associated with this ChannelID
| |
| | |
| ===== Arguments =====
| |
| There are no arguments for this call.
| |
| | |
| ===== Returns =====
| |
| | |
| On success, this returns the new digest on the server side.
| |
| {"digest": "checksum192"}
| |
| | |
| ===== Errors =====
| |
| | |
| * Not Registered
| |
| * Invalid UAID
| |
| | |
| ===== Example =====
| |
| DELETE http://push.m.o/v1/foo1234
| |
| ---
| |
| {}
| |
| | |
| ==== GET /v1/update ====
| |
| Return a list of known ChannelIDs and current versions.
| |
| | |
| NOTE: the X-UserAgent-ID must be provided and match the value returned by the <code>/register</code> call.
| |
| | |
| ===== Arguments =====
| |
| There are no arguments for this call.
| |
| | |
| ===== Returns =====
| |
| The server should return an object with the following fields:
| |
| | |
| * <tt>updates</tt> - An association of ChannelIDs and versions that have changed since the last time the UA called /update.
| |
| * <tt>expired</tt> - A list of ChannelIDs which have expired. The UA should remove these from its own database, and ask applications to re-register.
| |
| | |
| '''TODO''' Do we need acknowledgement of the /update from the UA. It is possible for the response to be lost in flight.
| |
| | |
| NOTE: If the server is unable to determine previous data for this X-UserAgent-ID, it will return a 410 leading to the Registration Sync Protocol occurring.
| |
| See <code>POST /update</code> for details.
| |
| | |
| ===== Example =====
| |
| | |
| GET http://push.m.o/v1/update
| |
| ---
| |
| {"digest": "hash string", "updates": [{"channelID":"1ced595d7f6c9f60cc5c9395dc6b72aa7e1a69a7","version":"42"},{"channelID":"bf08e25861c900c3ab343670eee1873d0b724eef","version":"1"}], "expired": ["channelID1", "channelID2", ...]}
| |
| | |
| ==== POST /v1/update ====
| |
| ====== Registration Sync Protocol ======
| |
| Refresh the server from the client.
| |
| | |
| This request requires a X-UserAgent-ID header. If the UserAgent attempts to POST information to the server which already has data for that X-UserAgent-ID, the server will deny the request with a 403 error. In that case, the UserAgent should request re-registration for all Channels.
| |
| | |
| The UserAgent '''SHOULD'''
| |
| # Send a list of <channelID, version> pairs capturing its current state to PushServer, along with the UAID.
| |
| # If the PushServer accepts the request, it SHOULD update its records. UserAgent and PushServer are now back in sync. DONE
| |
| # If the PushServer detects a duplicate UAID, it SHOULD respond with an error.
| |
| # In this case, the client should invalidate its current state and ask apps application to re-register using the <tt>push-register</tt> system message. UserAgent and PushServer will now organically sync similar to standard /register calls.
| |
| | |
| ===== Arguments =====
| |
| The POST body is a JSON encoded block:
| |
| <pre>
| |
| {
| |
| "channels": [{"channelID": "channelID1", "version": "version1"}, {"channelID": "channelID2", "version": "version2"}, ...]
| |
| }
| |
| </pre>
| |
| | |
| ===== Returns =====
| |
| | |
| {
| |
| "digest": "..."
| |
| }
| |
| | |
| UserAgent should confirm match
| |
| | |
| ===== Errors =====
| |
| | |
| * ReRegister - The server may response with this for any reason, although usually it'll be due to duplicate UAID.
| |
| | |
| ===== Example =====
| |
| <pre class="_fck_mw_lspace">POST http://push.m.o/v1/update
| |
| {"channels":[{"channelID":"1ced595d7f6c9f60cc5c9395dc6b72aa7e1a69a7","version":"42"},{"channelID":"bf08e25861c900c3ab343670eee1873d0b724eef","version":"1"}]}
| |
| </pre>
| |
| <pre class="_fck_mw_lspace">---
| |
| {"digest": "..."}
| |
| </pre>
| |
| | |
| ==== PUT /v1/update/<ChannelID> ====
| |
| | |
| Update the version of a given channel.
| |
| | |
| Arguments should be passed as standard form data (enctype: multipart/form-data)
| |
| This call does not require a X-UserAgent-ID, as it may be called by the AppServer.
| |
| | |
| ===== Arguments =====
| |
| version=<version>
| |
| | |
| The version is the AppServer specific VersionID to use. This ID is opaque to the PushServer, however it is suggested that:
| |
| * The ID be sequential.
| |
| * The ID be less than 100 characters.
| |
| * The ID should be UTF8 compliant.
| |
| | |
| ===== Returns =====
| |
| In the event of a PushServer catastrophe, the PushServer will be in "Recovery" mode. During this time, unresolvable ChannelIDs will return a 503 error.
| |
| | |
| In non-recovery mode, unresolvable ChannelIDs will return a 404.
| |
| | |
| This call returns an empty JSON object.
| |
| | |
| ===== Example =====
| |
| PUT http://push.m.o/v1/update/foo1234
| |
| version=1.3
| |
| ---
| |
| {}
| |
| | |
| =Flow Diagram=
| |
| [[Image:SimplePushFlow.png|Simple Push flow]] | |