Talkilla/SPA API: Difference between revisions

← Older edit

Talkilla/SPA API (view source)

Revision as of 08:48, 13 June 2014

3,960 bytes added , 13 June 2014

no edit summary

Standard8

canmove, Confirmed users, Bureaucrats and Sysops emeriti

3,627

edits

@@ Line 1: / Line 1: @@
+{{Note|Talkilla has now been superseded by the [[Loop]] project}}
 {{Template:Draft}}
 __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.
+==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==
@@ 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.
-==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.
@@ Line 48: / Line 64: @@
 '''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.
@@ Line 62: / Line 78: @@
 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.
+=== Capabilities ===
+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 ==
@@ Line 79: / Line 105: @@
 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.
+* <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 call id for a single call sequence.
+* <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.
@@ Line 123: / Line 149: @@
   {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>}}
+* 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 ===