|
|
| (131 intermediate revisions by 12 users not shown) |
| Line 1: |
Line 1: |
| == Client Side API == | | <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> |
| Push push;
| |
| };
| |
|
| |
|
| interface Push {
| | Go here for [[Firefox/Push_Notifications|project page]] |
|
| |
|
| // registers to receive push notifications for a given topic
| | [[Category:Web APIs]] |
| DOMRequest register(DOMString topic);
| |
| | |
| // registers to stop receiving push notifications for a given topic
| |
| DOMRequest unregister(DOMString topic);
| |
| | |
| // XXXX should be something like [{topic, pushEndpoint, pushRequestID}]
| |
| XXXX registered();
| |
| | |
| };
| |
| | |
| | |
| interface PushRequestEvent : Event {
| |
| | |
| // this is the URL to which push notifications from the web application
| |
| // must be sent to
| |
| DOMString pushEndpoint;
| |
| | |
| // this is the push request id that must be sent to the push server with
| |
| // every push notification update
| |
| DOMString pushRequestID;
| |
| }
| |
| | |
| interface PushEvent : Event {
| |
| | |
| // this is topic string used when registering for push notifications
| |
| DOMString topic;
| |
| | |
| // this is the most current version
| |
| unsigned long long version;
| |
| }
| |
| | |
| </pre>
| |
| | |
| | |
| | |
| == Client Example ==
| |
| <pre>
| |
| | |
| // all notifications will be sent to the system message handler.
| |
| | |
| navigator.mozSetMessageHandler("push", function(e) {
| |
| | |
| e.target.result.topic == This is the topic that is being observed
| |
| e.target.result.version == This is the current version for this topic
| |
| | |
| });
| |
| | |
| | |
| // to register to listen for a notification,
| |
| // you simply call push.register and pass an
| |
| // topic of interest:
| |
| | |
| var req = navigator.push.register("topic");
| |
| | |
| | |
| // success callback
| |
| req.onsuccess(e) = function() {
| |
| | |
| e.target.result.pushEndpoint
| |
| e.target.result.pushRequestID
| |
| }
| |
| | |
| req.onerror() = function(e) {}
| |
| | |
| // to unregister, you simply call..
| |
| | |
| req = navigator.push.unregister("topic");
| |
| req.onsuccess() = function() {}
| |
| req.onerror() = function() {}
| |
| | |
| </pre>
| |
| | |
| | |
| == Server API ==
| |
| | |
| We will use a RESTful API to interact with the Push Server.
| |
| | |
| The Push Server URL is returned to the client as a result of calling register(). The <i>pushEndpoint</i> is the URL to the Push Server.
| |
| | |
| === Registering with Push Server ===
| |
| | |
| <i>pushEndpoint</i>/register
| |
| | |
| These query parameters are required with each registration:
| |
| | |
| * API Key
| |
| ** TBD
| |
| ** <i>key</i> is the query parameter name
| |
| * pushRequestID
| |
| ** <i>pushRequestID</i> is the query parameter name.
| |
| ** The value of pushRequestID must be the result returned to the client as a result of calling register().
| |
| | |
| These query parameters are optional with each registration:
| |
| | |
| * Network Association
| |
| ** <i>network</i>
| |
| ** This may be a identification string that represents where the the client can also be reached at.
| |
| ** We need some way to say this client can be notified on another network (via UDP instead of a long poll)
| |
| ** For example "&network=telefica"
| |
| | |
| Example:
| |
| <pre>
| |
| GET http://push.mozilla.org/register?key=<apikey>&pushRequestID=<pushRequestID>
| |
| </pre>
| |
| | |
| If the request succeeds, the server responds with a 200 OK HTTP status code and the following JSON:
| |
| | |
| <pre>
| |
| // tbd
| |
| {
| |
| "result": {}
| |
| }
| |
| </pre>
| |
| | |
| === Un-registering with Push Server ===
| |
| | |
| <i>pushEndpoint</i>/unregister
| |
| | |
| These query parameters are required with each un-registration:
| |
| | |
| * API Key
| |
| ** TBD
| |
| ** <i>key</i> is the query parameter name
| |
| * pushRequestID
| |
| ** <i>pushRequestID</i> is the query parameter name.
| |
| ** The value of pushRequestID must be the result returned to the client as a result of calling register().
| |
| | |
| Example:
| |
| <pre>
| |
| GET http://push.mozilla.org/unregister?key=<apikey>&pushRequestID=<pushRequestID>
| |
| </pre>
| |
| | |
| If the request succeeds, the server responds with a 200 OK HTTP status code and the following JSON:
| |
| | |
| <pre>
| |
| // tbd
| |
| {
| |
| "result": {}
| |
| }
| |
| </pre>
| |
| | |
| === Notify Push Server of a new version ===
| |
| | |
| <i>pushEndpoint</i>/update
| |
| | |
| These query parameters are required with each un-registration:
| |
| | |
| * API Key
| |
| ** TBD
| |
| ** <i>key</i> is the query parameter name
| |
| * pushRequestID
| |
| ** <i>pushRequestID</i> is the query parameter name.
| |
| ** The value of pushRequestID must be the result returned to the client as a result of calling register().
| |
| * Version
| |
| ** <i>version</i> is the query parameter name.
| |
| ** The value of version is the most current version number of the object referenced by pushRequestID
| |
| | |
| Example:
| |
| <pre>
| |
| GET http://push.mozilla.org/unregister?key=<apikey>&pushRequestID=<pushRequestID>&version=<version>
| |
| </pre>
| |
| | |
| If the request succeeds, the server responds with a 200 OK HTTP status code and the following JSON:
| |
| | |
| <pre>
| |
| // tbd
| |
| {
| |
| "result": {}
| |
| }
| |
| </pre>
| |
| | |
| == Simple event flow ==
| |
| <pre>
| |
| | |
| | |
| +---------------+ +-----------------+ +------------------+
| |
| | Browser | | Push Server | | App Server |
| |
| +------+--------+ +--------+--------+ +---------+--------+
| |
| | register() | |
| |
| +---------------------------------->| |
| |
| | | |
| |
| | ok | |
| |
| |<---------------------------------+| |
| |
| | | |
| |
| | register successful | |
| |
| |+------------------------------------------------------------------->|
| |
| | | |
| |
| | | Update |
| |
| | | <-------------------------------+
| |
| | | Update |
| |
| | | <-------------------------------+
| |
| | update | |
| |
| |<----------------------------------+ |
| |
| | | |
| |
| | | |
| |
| | | |
| |
| | | |
| |
| | | |
| |
| | | |
| |
| | | |
| |
| | | |
| |
| | | |
| |
| </pre>
| |