WebAPI/SimplePush: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(fix)
 
(116 intermediate revisions by 12 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&#160;: 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(DOMString topic);
 
  // registers to stop receiving push notifications for a given topic
  // DOMRequest.result is a PushRegistration in case of success
  DOMRequest unregister(DOMString topic);
 
  // returns the list of all push registrations for this origin
  PushRegistration[] registered();
 
  // event MUST be of type PushEvent
  attribute EventHandler onmessage;
};
 
interface PushRegistration {
 
  // this is the string that was used when calling register()
  DOMString topic;
 
  // 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 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.
// which is up to the U/A to implement
 
// apps can do something like
navigator.pushNotification.onmessage = function(e) {
  e.topic == This is the topic that is being observed
  e.version == This is the current version for this topic
});
 
 
// to register to listen for a notification,
// you simply call push.register and pass a
// topic of interest:
 
var req = navigator.pushNotifications.register("topic");
 
 
// success callback
req.onsuccess(e) = function() {
  // post to application server
  e.target.result.pushEndpoint
  e.target.result.pushRequestID
}
 
req.onerror() = function(e) {}
 
// to unregister, you simply call..
 
req = navigator.pushNotifications.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.
 
Successful calls will return HTTP Status 200 with new content or 204 with no update change
 
Unless otherwise noted the following HTTP error codes:
:401
Authorization failure
 
:404
pushRequestID not found
 
:500
Server error.
 
=== Registering with Push Server ===
 
POST <i>pushEndpoint</i>/register/[<network>/]<pushRequestID>
 
* pushRequestID
** 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 = "telefonica"
 
Example:
<pre>
  POST http://push.mozilla.org/register/telefonica/<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 ===
 
DELETE <i>pushEndpoint</i>/register/[<network>/]<pushRequestID>
 
* pushRequestID
** The value of pushRequestID must be the result returned to the client as a result of calling register().
 
Example:
<pre>
  DELETE http://push.mozilla.org/register/telephonica/<pushRequestID>
</pre>
 
If the request succeeds, the server responds with a 200 OK HTTP status code and the following JSON:
 
<pre>
// tbd
{
  "result": {}
}
</pre>
 
=== Client check for updates ===
 
GET <i>pushEndpoint</i>/update/[<network>/]<pushRequestID>?version=<lastPulledVersion>
 
* pushRequestID
** The value of pushRequestID must be the result returned to the client as a result of calling register().
 
* network
** Optional network specifier.
 
Example:
<pre>GET <i>pushEndpoint</i>/update/telephonica/<pushRequestID>?version=12345</pre>
 
Returns:
 
:200 Success
<pre>{
  "result": {"update": <newVersionNumber>}
}</pre>
 
:204 Success (No content, no change in version.)
<pre>{
  "result": {}
}</pre>
 
=== Notify Push Server of a new version ===
 
PUT <i>pushEndpoint</i>/update/<network>/<pushRequestID>?version=<version>
 
These query parameters are required with each update:
 
* pushRequestID
** 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>
  PUT http://push.mozilla.org/update/<pushRequestID>?version=<version>
</pre>
 
If the request succeeds, the server responds with a 200 OK HTTP status code and the following JSON:
<pre>
{
  "result": {}
}
</pre>

Latest revision as of 00:03, 12 November 2015

For documentation on Using SimplePush in your App, please see the MDN SimplePush Documentation

For documentation on the Service, please see the Mozilla Push Service Documentation

Go here for project page

Retrieved from "https://wiki.mozilla.org/index.php?title=WebAPI/SimplePush&oldid=1105291"