MozillaWiki

Talkilla/SPA API: Difference between revisions

Page Discussion

Talkilla/SPA API (view source)

Revision as of 08:48, 13 June 2014

4,995 bytes added ,  13 June 2014
no edit summary
(Add ICE capability information)
No edit summary
 
(29 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Note|Talkilla has now been superseded by the [[Loop]] project}}
{{Template:Draft}}
{{Template:Draft}}
__TOC__
__TOC__
Line 19: Line 21:


It is advisable to make the Javascript web worker as lightweight as possible, as this will be continuously running in the background of the browser.
It is advisable to make the Javascript web worker as lightweight as possible, as this will be continuously running in the background of the browser.
==SPA Code Configuration==
An SPA's code should be in one directory, under <code>static/spa/<spa name></code>. The directory structure may be whatever is appropriate. Other Talkilla files may be used, but we do not currently specify an API for these.
Configuration of the SPA is by a single file, <code>static/spa/<spa name>/config.json</code>. The file should contain:
{
  loginURL: "/url/to/login/page.html"
}
The <code>loginURL</code> should point to the URL of the iframe to load for logging into the service provider. Typically this is expected to be hosted on a provider's own site.
As detailed elsewhere, the url of the worker to use for the SPA is detailed in the <code>talkilla.spa-enable</code> message received from the login page and all other SPA loading/controls will come from the worker.


==SPA Installation==
==SPA Installation==
Line 25: Line 41:
Technically, this is similar to the oauth flow. The authentication sequence starts when the user clicks on the Talkilla website a link pointing to the service provider's website. The link includes a callback URL where the user should be redirected once the user's credentials have been verified. A token is added to the callback URL by the service provider's website. This token will be used to start the SPA.
Technically, this is similar to the oauth flow. The authentication sequence starts when the user clicks on the Talkilla website a link pointing to the service provider's website. The link includes a callback URL where the user should be redirected once the user's credentials have been verified. A token is added to the callback URL by the service provider's website. This token will be used to start the SPA.


==SPA initialization==
==SPA Initialization==
When Talkilla starts within SocialAPI, as part of its initialization, it will start a web worker (https://developer.mozilla.org/en-US/docs/Web/Guide/Performance/Using_web_workers ) for each installed SPA.  
When Talkilla starts within SocialAPI, as part of its initialization, it will start a web worker (https://developer.mozilla.org/en-US/docs/Web/Guide/Performance/Using_web_workers ) for each installed SPA.  


Line 48: Line 64:
'''The capabilities, addresses and settingURL are not implemented yes'''.
'''The capabilities, addresses and settingURL are not implemented yes'''.


The (optional) capabilities array here is a set of capabilities supported by the SPA for the connected user service.
The (optional) capabilities array here is a set of capabilities supported by the SPA for the connected user service. See the list below for the options.


The settingURL is the address of a webpage that the user can load by clicking in the UI.
The settingURL is the address of a webpage that the user can load by clicking in the UI.
Line 63: Line 79:
Note: Needing to re-authentify the user to connect is an error. Having to login on the service provider's website shouldn't be required each time the browser is restarted.
Note: Needing to re-authentify the user to connect is an error. Having to login on the service provider's website shouldn't be required each time the browser is restarted.


==Receiving a call==
=== Capabilities ===
  postMessage({topic: "offer", data: {peer: "+16501231234", offer: {type:"offer", sdp:"v=0\r\no=Mozilla-SIPUA..."}}});
 
These are the possible capabilities an SPA can advertise:
 
* <code>call</code>: The SPA can make calls
* <code>hold</code>: The SPA supports hold and resume for calls
* <code>move</code>: The SPA supports call move to other devices
* <code>spachannel</code>: The SPA does not support the data channel and routes text messages and file transfers via its server.
* <code>pstn-call</code>: The SPA supports calls to a PSTN network
 
== Call Handling ==
 
Messages that handle calls, can go two ways from the Worker to the SPA and vice-versa.
 
To send a message to Talkilla (e.g. incoming call):
 
  postMessage({topic: <topic>, data: <data>})
 
Receiving a message from Talkilla (e.g. call offer), listen for message of structure:
 
{topic: topic, data: <data>}
 
=== Call Handling Data Structures ===
 
These are the data structures associated with calls
 
* <code><peer></code> is a string which is the id of the peer that the call is with. e.g. <code>0123456798</code> or <code>foo@example.com</code>
 
* <code><call id></code> contains the integer call id for a single call sequence.
** This is used to ensure that messages from one call with a peer don't affect other calls/actions with the same peer.
** Currently, sending a new call id for a call with a peer does not force a new call to be started.
 
* <code><session desc></code> is a serialized object equivalent of [http://www.w3.org/TR/webrtc/#rtcsessiondescription-class RTCSessionDescription]
** Type will be <code>offer</code> for an incoming call offer, and <code>answer</code> for a response to an offer.
 
{ type: "answer", sdp: "v=0\r\no=Mozilla-SIPUA..."}
 
* <code><ice candidate></code> is a serialized object equivalent of [http://www.w3.org/TR/webrtc/#rtcicecandidate-type RTCIceCandidate] e.g.
 
{candidate: "candidate string", sdpMid: "media stream id", sdpMLineIndex: 2}
 
=== Call Flows ===
 
==== Users Receives a Call ====
 
Send from the SPA to Talkilla:
 
{topic: "offer", data: {peer: <peer>, offer: <session desc>, callid: <call id>}}
 
When the user answers, Talkilla will post the following to the SPA:
 
{topic: "answer", data: {peer: <peer>, answer: <session desc>, callid: <call id>}
 
==== User Places a Call ====
 
Talkilla sends to the SPA:
 
{topic: "offer", data: {peer: <peer>, offer: <session desc>, callid: <call id>}}


Talkilla will either reply with an 'answer' message:
When the other end answers, the SPA will send to Talkilla:
event.data contains
{topic: "answer", data: {peer: "+16501231234", answer: {type:"answer", sdp:"v=0\r\no=Mozilla-SIPUA..."}}}


or reject the call: (not implemented yet)
  {topic: "answer", data: {peer: <peer>, answer: <session desc>, callid: <call id>}
event.data contains
  {topic: "reject", data: {peer: "+16501231234"}}


==Placing a call==
Talkilla will time out call offers after 30 seconds, at this time a call hangup is sent (see below).
event.data contains
{topic: "offer", data: {peer: "+33615827492", offer: {type:"offer", sdp:"v=0\r\no=Mozilla-SIPUA..."}}}


The SPA can reply with an "answer" or "reject" message.
==== Ending a Call ====
postMessage({topic: "answer", data: {peer: "webrtc@mailinator.com", answer: {type:"answer", sdp:"v=0\r\no=Mozilla-SIPUA..."}}});


"reject" is not implemented yet.
Either Talkilla or SPA can send a message:


==Ending a call==
  {topic: "hangup", data: {peer: <peer>, callid: <call id>}}
Either the SPA or Talkilla can send a 'hangup' message:
From the SPA:
  postMessage({topic: "hangup", data: {peer: "+16501231234"}});
From Talkilla: event.data contains
{topic: "hangup", data: {peer: "+16501231234"}}


== Handling ICE Candidates ==
==== User Initiates a Call Move ====
 
''This API only applies when the SPA advertises "move" in its capabilities''
 
Talkilla send the message:
 
{topic: "move", data: {peer: <peer>, callid: <call id>}}
 
When the SPA has accepted the move request:
 
{topic: "move-accept", data: {peer: <peer>, callid: <call id>}}
 
==== Call Hold ====
 
''This API only applies when the SPA advertises "hold" in its capabilities''
 
Either Talkilla or SPA can send a message:
 
{topic: "hold", data: {peer: <peer>, callid: <call id>}}
 
==== Receiving Call Resume from a Peer ====
 
''This API only applies when the SPA advertises "hold" in its capabilities''
 
The SPA can send a message:
 
{topic: "resume", data: {peer: <peer>, callid: <call id>, media: {
  video: <boolean> }
}}
 
Note: The media parameter is a temporary option until Firefox supports session re-negotiation. On receiving a resume message, Talkilla will only enable the video tracks if the video parameter is true.
 
==== Text Messages ====
 
''This part of the API only applies when the SPA advertises "spachannel" in its capabilities''
 
===== Sending a text message =====
This message can be sent either way.
 
{topic: "message", data: {peer: <peer>, type: "chat:message", message: <string>}}
 
* Peer is the peer the message is being sent to
* username is the user the peer was from
 
===== Typing notifications =====
 
{topic: "message", data: {peer: <peer>, type: "chat:typing", message: {}}
 
* Peer is the peer the message is being sent to
* username is the user the peer was from
* message is an empty object, it is not used - this may go away in the future.
 
==== File Transfer ====
 
''This part of the API only applies when the SPA advertises "spachannel" in its capabilities''
 
===== Starting a new file =====
This message can be sent either way.
 
{topic: "message", data: {peer: <peer>, type: "file:new",
  message: {filename: <string>, size: <integer>, id: <integer>, type:<string>}}
 
* Peer is the peer the message is being sent to
* filename is the filename string
* size is the size of the file
* type is the mime type of the file (if known).
* id is the identifier for this specific file transfer (e.g. will be different for different transfers of the same filename).
 
===== Sending a file chunk =====
 
{topic: "message", data: {peer: <peer>, type: "file:chunk", message: {id: <integer>, chunk: <chunk>}}
 
* Peer is the peer the message is being sent to
* id is the identifier for this specific file transfer
* chunk is the binary string for the file chunk
 
=== Handling ICE Candidates ===
Firefox is capable of [http://tools.ietf.org/html/draft-rescorla-mmusic-ice-trickle-00 Trickle ICE]. After an initial call offer or answer, there may be additional ICE candidates. Hence these may be sent from either side.
Firefox is capable of [http://tools.ietf.org/html/draft-rescorla-mmusic-ice-trickle-00 Trickle ICE]. After an initial call offer or answer, there may be additional ICE candidates. Hence these may be sent from either side.


From the SPA:
ICE candidates may be sent from either Talkilla to the SPA or vice-versa depending on which part of the call they are coming from:
postMessage({topic: "ice:candidate", data: {peer: "+16501231234", candidate: <candidate>}});


From Talkilla: event.data contains:
{topic: "ice:candidate", data: {peer: <peer>, candidate: <ice candidate>}}
  {topic: "ice:candidate", data: {peer: "+16501231234", candidate: <candidate>}});


<code><candidate></code> is an object containing parameters with values matching the [http://dev.w3.org/2011/webrtc/editor/webrtc.html#rtcicecandidate-type RTCIceCandidate] e.g.
When the ICE candidate list is complete, a message with a <code>null</code> data value will be passed:


  {candidate: "candidate string", sdpMid: "media stream id", sdpMLineIndex: 2}
  {topic: "ice:candidate", data: {peer: <peer>, candidate: null}}


=Data Channel API Documentation=
=Data Channel API Documentation=
This is still being defined
This is still being defined
Standard8
canmove, Confirmed users, Bureaucrats and Sysops emeriti
3,627

edits

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