SparkAngels

Le coin des développeurs

SparkAngels publie ses APIs pour une meilleure intégration de son service au sein des applications Web.

Intégrez le service "Clic-for-help" dans votre application web grâce à l'API SparkAngels

L'API SparkAngels offre la possibilité d'intégrer la mise en relation SparkAngels au sein même d'une application web en exploitant l'identification existante sur cette application web pour éviter l'échange d'un code d'autorisation de session nécessaire à l'identification des deux parties.

Ainsi, le télé-accompagnement pourra simplement être activé par les boutons "Clic-for-help" et "Clic-to-help".

Pour obtenir un code d'authentification pour déployer l'API SparkAngels vous devez créer un compte et faire la demande dans la page de votre profil.

Les boutons de droite donnent accès aux spécifications, à un démonstrateur de fonctionnement et à une aide qui vous génère le script HTML pour votre implémentation de l'API.

SAPI-2 - The SparkAngels API

Document Revision: 4 - Diffusion: External

Overview

The SparkAngels API is a Web-invocation API that allows to start a SparkAngels session from third-party Web applications.

The overall principle is that the Web application will generate two URLs, one for the Helper, the other for the Helpee. When these URLs are opened by the client browsers, SparkAngels will be installed and started, and will initiate a SparkAngels session between the Helper (the one who views the Helpee's screen) and the Helpee (after he accepts a confirmation dialog).

SAPI-2 Description

The current version of SAPI is: Version 2.

Overall structure of SAPI messages

The SAPI messages are encoded in the URL that invokes the SparkAngels service.

The URL structure is as follows :
http://dnld0.sparkom.com/sparkangels/sangels/sparkangels.jnlp?sapi2=SAPI2_VALUE
where :
SAPI2_VALUE=(UrlEncoded SAPI-2 parameters)where :
SAPI-2 parameters is a sequence of prmXvalueX attributes, separated by the ',' character.
The resulting sequence is UrlEncoded (encoded in application/x-www-form-urlencoded format, using the recommended encoding UTF-8 - In Javascript, the encodeURIComponent method should be used, rather than escape). This ensures that the resulting SAPI2_VALUE can be used as an URL component. Some parameter values are UrlEncoded before inserting them in the sequence.
The "x" (XRef) parameter should only contain '0'-'9', 'A'-'Z', 'a'-'z', '-', '_'.

Recognized Parameters :
a : Authentication - Value is the Authentication Code provided by Sparkom to enable the use of SAPI-2 for a specific Web Application; Mandatory
v : Version - Value must be "2" (user of SparkAngels API Version 2); Mandatory
c : Command - Value must be: 'S'; Mandatory
r : Role - Must be 'r' for Helper or 'e' for Helpee; Mandatory
x : Cross-Reference - Allows the association between the Helper and the Helpee and must be the same in the Helper and Helpee URLs; Mandatory
u : User Name - Allows to convey the UrlEncoded "name" of the helper party. It is the name that will be displayed to the Helpee, in the Confirmation Dialog presented at session startup; Mandatory
s : Startup Service Type - Must be 'l', followed by one or several services (ex. slcp for both Chat and PMAD Control services launched): 'c' for chat or 'p' for pmadctrl or 'v' for pmadview; At least one service must be present, and the 'p' and 'v' services are incompatible.

Sample URLs :
- For the Helper named "John -,Doe" :
http://dnld0.sparkom.com/sparkangels/sangels/sparkangels.jnlp?sapi2=aMyAuthCode%2Cv2%2CcS%2Crr%2CxeZRX8_t43s%2CuJohn%2B-%252CDoe%2Csv
- For the Helpee :
http://dnld0.sparkom.com/sparkangels/sangels/sparkangels.jnlp?sapi2=aMyAuthCode%2Cv2%2CcS%2Cre%2CxeZRX8_t43s%2CuJohn%2B-%252CDoe%2Csv

Sample JavaScript code to create it :
var auth = MyAuthCode;
var role = "r"; // 'r' for Helper, 'e' for Helpee
var xref = ....; // Some random value, containing only '0'-'9', 'A'-'Z', 'a'-'z', '-', '_'
var helperName = encodeURIComponent("John -,Doe");
var serviceType = "v"; // 'c' for Chat, 'v' for Screen Sharing (view), 'p' for Computer Sharing (control)
var sapiValue = "a" + auth + ",v2,cS,r" + role + ",x" + xref + ",u" + helperName + ",s" + serviceType;
var sapiUrl = "http://dnld0.sparkom.com/sparkangels/sangels/sparkangels.jnlp?sapi2=" + encodeURIComponent(sapiValue);

SparkAngels will start on both sides.
The Helpee will get a Confirmation dialog asking if he accept to have his screen viewed by "Helper Name". Following acceptation, the Helper and the Helpee will be in a SparkAngels session, as if they had manually started SparkAngels and exchanged the session confidential code.

xref allocation

The Cross-Reference parameter is what allows the association between the Helper and the Helpee. It is allocated by the Web Application and must be unique within the Web Application, as identified by the AUTHCODE. It needs not be unique in time, but the same xref should not be reallocated within some time interval (at least 1 hour) after the session ends.

Restarting a session

To start a new session between two clients, even if they had been in session before, a SAPI URL must be loaded again by their browsers. Starting SparkAngels from the Desktop or Startup Menu shortcuts will not re-establish the session.

Error Handling

If the MyAuthCode is not recognized, or the SAPI2_VALUE has an invalid structure, an HTTP 404 (file not found) exception is returned.
If there are unrecognized parameters, SparkAngels will start but not setup the session. An error indication may be presented to the user.

Requirements

The SparkAngels application is a "Java Web Start" application, thus the client browser must be able to start a WebStart application automatically. This implies the following requirements :

Java version 5 must be installed and enabled on the client system and browser,
The client browser must recognize the JNLP MIME Type (application/x-java-jnlp-file) and start "javaws" for this MIME Type.

To ensure these requirements, the Web Application may provide detection code similar to SparkAngel's web code, to help the user install Java.

Conditions of use

Must obtain an AUTHCODE from Sparkom
Must not use other AUTHCODEs
Must not impair or prevent SparkAngels installation or operation
Must recognize Sparkom's ownership rights on the SparkAngels software and not misrepresent the software origin
Must not use for unlawful or unethical services
Must respect the user's intent and privacy, and not attempt to start a session without explicit and informed consent by both sides
Must accept SparkAngels CLUF