MozillaWiki

Talkilla/SPA API: Difference between revisions

Page Discussion

Talkilla/SPA API (view source)

Revision as of 08:48, 13 June 2014

5,209 bytes added ,  13 June 2014
no edit summary
No edit summary
 
(34 intermediate revisions by 3 users 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.  


When the SPA has finished loading (including all its dependencies; if any), it sends to Talkilla a message announcing it is ready to receive the user's credentials:
When the SPA is loaded, Talkilla will send a message containing the credentials to connect the SPA to its provider:
 
postMessage({topic: "ready", data: {capabilities: ["call"]}});
 
The capabilities array lists all the features supported by the SPA. "call" means the SPA is able to place calls and receive incoming calls.
Other capabilities (still work in progress) include: "presence", "addressbook", ...
 
Talkilla will reply with a message containing the credentials:
event.data will be:
event.data will be:
  {topic: "credentials", data: {token: auth_string}}
  {topic: "connect", data: <credentials>}
where auth_string is the string added to the callback URL by the service provider's website when redirecting the user to the Talkilla website after successfully authenticating the user.
where 'credentials' is an arbitrary object containing the user's credentials for this SPA/Provider.


At this point, the SPA can start connecting to the service provider's servers.
At this point, the SPA can start connecting to the service provider's servers.
If the SPA connected successfully and is ready to receive calls, it will send to Talkilla a 'logged-in' message:
If the SPA connected successfully and is ready to receive calls, it will send to Talkilla a 'connected' message:


  postMessage({
  postMessage({
   topic: "logged-in",
   topic: "connected",
   data: {
   data: {
     addresses: [{type: "pstn", value: "+33698234520"},
     addresses: [{type: "pstn", value: "+33698234520"},
Line 53: Line 62:
  });
  });


The (optional) capabilities array here is a subset of the capabilities announced with the 'ready' message. This is useful is the features supported depend on the plan the user has subscribed with the service provider.
'''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. 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 68: 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>}}
 
When the other end answers, the SPA will send to Talkilla:
 
{topic: "answer", data: {peer: <peer>, answer: <session desc>, callid: <call id>}
 
Talkilla will time out call offers after 30 seconds, at this time a call hangup is sent (see below).
 
==== Ending a Call ====
 
Either Talkilla or SPA can send a message:
 
{topic: "hangup", data: {peer: <peer>, callid: <call id>}}
 
==== 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>}}


Talkilla will either reply with an 'answer' message:
* Peer is the peer the message is being sent to
event.data contains
* id is the identifier for this specific file transfer
{topic: "answer", data: {peer: "+16501231234", answer: {type:"answer", sdp:"v=0\r\no=Mozilla-SIPUA..."}}}
* chunk is the binary string for the file chunk


or reject the call: (not implemented yet)
=== Handling ICE Candidates ===
event.data contains
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.
{topic: "reject", data: {peer: "+16501231234"}}


==Placing a call==
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:
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.
  {topic: "ice:candidate", data: {peer: <peer>, candidate: <ice candidate>}}
  postMessage({topic: "answer", data: {peer: "webrtc@mailinator.com", answer: {type:"answer", sdp:"v=0\r\no=Mozilla-SIPUA..."}}});


"reject" is not implemented yet.
When the ICE candidate list is complete, a message with a <code>null</code> data value will be passed:


==Ending a call==
  {topic: "ice:candidate", data: {peer: <peer>, candidate: null}}
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"}}


=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/729801...988782"