|
|
| (94 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.
| |
| * 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 /register ====
| |
| Request a new ChannelID.
| |
| | |
| If the <i>X-UserAgent-ID</i> is not provided, the UserAgent is presumed to be new and a new UserAgentID will be generated for the UserAgent.
| |
| | |
| ===== Arguments =====
| |
| | |
| No additional arguments are required.
| |
| | |
| ===== Returns =====
| |
| { "channelID": "New Channel ID",
| |
| "uaid": "UserAgent ID"
| |
| }
| |
| | |
| 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.
| |
| | |
| ===== Example =====
| |
| GET http://push.m.o/register
| |
| ---
| |
| {"channelID": "foo1234", "uaid": "bar5678"}
| |
| | |
| ==== DELETE /<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 =====
| |
| | |
| This returns an empty JSON object
| |
| {}
| |
| ===== Example =====
| |
| DELETE http://push.m.o/unregister/foo1234
| |
| ---
| |
| {}
| |
| | |
| ==== GET /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 =====
| |
| This will return a hash containing a list of hashes defining the known, associated Channels and versions.
| |
| | |
| NOTE: If the server is unable to determine previous data for this X-UserAgent-ID, it will return a 410.
| |
| See <code>POST /update</code> for details.
| |
| ===== Example =====
| |
| | |
| GET http://push.m.o/update
| |
| ---
| |
| {"channels":[{"channelID":"1ced595d7f6c9f60cc5c9395dc6b72aa7e1a69a7","version":"42"},{"channelID":"bf08e25861c900c3ab343670eee1873d0b724eef","version":"1"}]}
| |
| | |
| <h4> POST /update </h4>
| |
| <p>Refresh the server from the client.
| |
| </p><p>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.
| |
| </p>
| |
| <ol><li> Server state <b>MUST</b> be considered the canonical state, <i>unless</i> the server has NO state.
| |
| </li><li> On an /update call, the server <b>MUST</b> <i>atomically</i> update its state.
| |
| </li></ol>
| |
| <h5> Arguments </h5>
| |
| <p>The POST body is a JSON encoded block which matches the form and structure of the GET /update/ request.
| |
| </p>
| |
| <h5> Returns </h5>
| |
| <p>This will return an empty object.
| |
| </p>
| |
| <h5> Example </h5>
| |
| <pre class="_fck_mw_lspace">POST http://push.m.o/update
| |
| {"channels":[{"channelID":"1ced595d7f6c9f60cc5c9395dc6b72aa7e1a69a7","version":"42"},{"channelID":"bf08e25861c900c3ab343670eee1873d0b724eef","version":"1"}]}
| |
| </pre>
| |
| <pre class="_fck_mw_lspace">---
| |
| {}
| |
| </pre>
| |
| | |
| ==== PUT /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 =====
| |
| | |
| This call returns an empty JSON object.
| |
| | |
| ===== Example =====
| |
| PUT http://push.m.o/update/foo1234
| |
| version=1.3
| |
| ---
| |
| {}
| |