WebAPI/PushAPI: Difference between revisions

Jump to navigation Jump to search

WebAPI/PushAPI (view source)

Revision as of 17:28, 18 September 2012

264 bytes added ,  18 September 2012
→‎Client API
No edit summary
Line 26: Line 26:
  }
  }


<tt>requestURL(watoken, PbK)</tt> asks the user if they'd like to allow the app requesting
===requestURL(WAToken, publicKey)===
to send notifications. It requires two arguments, a "watoken" that identifies uniquely the user (or installation) of the app (or a shared watoken, used for broadcast) and the app public key, that will be used to verify the origin of the notification.
asks the user if they'd like to allow the app requesting to send notifications. If the app has been granted permission already and is calling <tt>requestURL()</tt> again, the original values are returned and no user interaction is required.


When the success callback runs, <tt>request.result</tt> will be a "JSON object" with the following structure
==== Arguments ====
<b><tt>WAToken</tt></b><br>
the Web App Token identifies uniquely the user (or installation) of the app (or a shared <tt>WAToken</tt>, used for broadcast). It is generated by <i style="color:red">XXX</i>
 
<b><tt>publicKey</tt></b><br>
used to verify the origin of the notification. This is a cryptographic key generated by the app and should be unique per user.
 
==== Returns ====
<tt>request.result</tt> will be a "JSON object" with the following structure


  dictionary PushURLResult {
  dictionary PushURLResult {
Line 38: Line 46:
   DOMString WAtoken;
   DOMString WAtoken;
  }
  }
<b><tt>status</tt></b><br />
"SUCCESS" on successful registration of <tt>WAToken</tt>, otherwise, "ERROR".
=====SUCCESS parameters =====
<b><tt>url</tt></b><br />
returns the URL the app server may use to send a Push Notification messages to the user.
<b><tt>messageType</tt></b><br />
<tt>registeredWA</tt> response to this message


The <tt>status</tt> property says if the registration of a given WA token is correct or not:
<b><tt>WAToken</tt></b><br />
* a <tt>ERROR</tt> status is sent, then, the <tt>reason</tt> could contain a more explicit message error.
same value as the <tt>WAToken</tt> parameter
* a <tt>SUCCESS</tt> status is sent when it's correct. Then, the field <tt>url</tt> is defined.


The <tt>reason</tt> is only defined if the <tt>status</tt> field (shown above) is <tt>ERROR</tt>. Not mandatory.
=====Error parameters =====
<b><tt>reason</tt></b><br />
Optional value which may contain a more explicit message error.


The <tt>url</tt> property contains the URL which the app server can send messages to this user. It's up to the app to send the URL to the server backend for storage.
<b><tt>WAtoken</tt></b><br />
same value as the <tt>WAToken</tt> parameter


The <tt>messageType</tt> is <tt>registerWA</tt> which is the response to this kind of messages.
===getCurrentURL()===
lets the app ask Firefox if the app has a push URL without bothering the user. The function behaves the same way as <tt>requestURL()</tt> except for the case when <tt>requestURL()</tt> would prompt the user. I.e. if the user has already granted permission, or if the user has permanently denied permission, then <tt>getCurrentURL</tt> behaves the same as <tt>requestURL</tt>. However if the user hasn't yet made a decision, then <tt>getCurrentURL</tt> results in a success event, but with <tt>request.result</tt> set to null.


The <tt>WAtoken</tt> is the app token that was used to register. This can be used by the user agent to identify what URL belongs to a specified token or if there is some error.
==== Arguments ====
There are no arguments for this function


If the app has been granted permission already and is calling <tt>requestURL()</tt> again, we can return the same URL without bothering the user.
==== Returns ====
This function returns the stored values for <tt>requestURL()</tt> or Null if no stored values exist.


<tt>getCurrentURL()</tt> lets the app ask Firefox if the app has a push URL without bothering the user. The function behaves the same way as <tt>requestURL()</tt> except for the case when <tt>requestURL()</tt> would prompt the user. I.e. if the user has already granted permission, or if the user has permanently denied permission, then getCurrentURL behaves the same as requestURL. However if the user hasn't yet made a decision, then getCurrentURL results in a success event, but with request.result set to null.
===revokeURL(url)===
lets the app indicate that it no longer wants to be able to push messages using the indicated URL for this installation.


<tt>revokeURL(url)</tt> lets the app indicate that it no longer wants to be able to push messages using the indicated URL for this installation.
==== Arguments ====
<b><tt>url</tt></b><br />
The URL returned by a previously successful <tt>requestURL()</tt> call.


=== Examples ===
Simple usage would look like this:
Simple usage would look like this:


Jrconlin
Confirmed users
1,018

edits

Retrieved from "https://wiki.allizom.org/Special:MobileDiff/471515"

Navigation menu