@screenmeet/js-sdk v1.0.9
ScreenMeet JS SDK
Installation
You can install ScreenMeet with your favorite JavaScript package manager software or by cloning the repo from github.
NPM:
npm install @screenmeet/js-sdk
Yarn
yarn add @screenmeet/js-sdk
Git:
git clone https://github.com/screenmeet/screenmeet-js-sdk.git
API Reference
You can view the full API reference here:
https://screenmeet.github.io/screenmeet-js-sdk/classes/app_screenmeet.screenmeet.html
Initialization
The current version of the ScreenMeet JS SDK is intended to be used as part of a front-end (browser)
application. Some classes can still be used via a back-end, such as the ScreenMeetAPI
. However,
back-end authentication methods to acquire a session token are not available in this version.
This support will be added in a future version of the SDK.
Adding ScreenMeet directly via browser:
- Copy
build/bundle.js
into your project / CDN. - Add a script tag to the page to your referencing the bundle file. Optionally, you could also
use the git CDN to include the ScreenMeet SDK bundle file
https://cdn.jsdelivr.net/gh/screenmeet/screenmeet-js-sdk@master/build/bundle.js
- we would only recommend doing this in a dev environment.
<!-- when hosting the file yourself -->
<script src="/screenmeet-js-sdk/build/bundle.js"></script>
<!-- directly from CDN: -->
<script src="https://cdn.jsdelivr.net/gh/screenmeet/screenmeet-js-sdk@master/build/bundle.js"></script>
Including ScreenMeet in a React Application:
import {ScreenMeet} from "@screenmeet/js-sdk";
Including ScreenMeet in a Webpack / JS bundle build:
let {ScreenMeet} = require("@screenmeet/js-sdk");
Authentication
Callback file
Included in the project is a file called examples/oauth_cb.html
- this file acts as a cross-domain authentication
callback receiver to authenticate users via supported identity providers. This file has to be hosted on the same domain
as your front-end applicaiton for authentication to work properly. A URL referencing this file will be required when
invoking authentication.
Authenticating with a supported provider
The ScreenMeet SDK will manage end-user authenticaiton for you for supported identity providers. In a future release, additional authenticaiton options will be provided if you would like to use your own identity provider for authentication. Simply invoke ScreenMeetMain.signin(provider, cburl, instance) to invoke an oauth sign-in to the chosen provider.
Example
let cburl = document.location.origin + '/oauth_cb.html'; //oauth callback file
let provider = 'sfdc'; //provider
let instance = 'https://login.salesforce.com/' //provider instance (if supported)
try {
let result = await this.ScreenMeetMain.signin(provider, cburl,instance);
console.log('Login result', result);
} catch (er) {
console.log('login failed');
console.error(er);
}
Session Creation and listing
Configuring the ScreenMeet Object
ScreenMeet sessions can be created in 2 ways: standalone or related to an object. Stand-alone mode can be used to create adchoc sessions where the user just wants to create a ScreenMeet session without it belonging to some other entity such as a Case. When using related mode, some metadata about the object will be stored along with the ScreenMeet session, sessions related to that object can then be queries easily by its global unique key.
Adhoc mode
//this example assumes the user is already authenticated
let sm_global_opts = {
"mode": "adhoc",
"persistAuth": true,
"trackSessionState": true, //will poll for session states for all widgets
"cbdeployments": true //whether to fetch cobrowse configuration data if using this product
};
let smAdhoc = new ScreenMeet(sm_global_opts);
//creating an adhoc session
let mySession = await smAdhoc.createAdhocSession("cobrowse", "My cobrwose session");
Object mode
//this example assumes the user is already authenticated
let sm_related_opts = {
"mode": "object", //the mode parameter must be "object"
"persistAuth": true,
"trackSessionState": true, //will poll for session states for all widgets
"cbdeployments": true //whether to fetch cobrowse configuration data if using this product
};
let smForObject = new ScreenMeet(sm_related_opts);
let parentObject = {
'id' : "sfj48wtej9i",
'app ' : "spiffycrmapp",
'type' : "case", //object type
'name' : "Case 12345", //name of object - goes into label field
'sync' : false //whether eager back-end sync should happen (not yet supported)
};
//create a globally unique key for your object
let objectKey = "spiffycrm.joesdevinstance.case.sfj48wtej9i";
//creating an adhoc session
let myRelatedSession = await smForObject.createRelatedSession( "cobrowse", "Cobrowse for case sfj48wtej9i", {"record" : true}, parentObject, objectKey);
Fetching Sessions
There are two methods available for fetching sessions from the API. Fetching sessions for an Adhoc mode instance will return ALL sessions belonging to the authenticated user. This includes any object-related sessions. Fetching sessions for a related object will only return the sessions which match the objectKey used to create those sessions.
When sessions the retreived, the updated
event will also fire on the ScreenMeet object, passing the retreived session
list as the 1st parameter.
//Fetching adhoc (all user sessions) via a promise - will return up to 20 sessions - pagination is available
// (see api reference):
let mySessions = await smAdhoc.listUserSessions();
//Fetching related sessions for an object. Takes the object key as a parameter and returns a promise
let myCaseRelatedSessions = await smForObject.listRelatedObjectSessions(objectKey);
//Getting sessions via event handler:
//bind the "updated" event - will fire whenever the session list is updated via a list operation or automatic polling
smForObject.on("updated", (sessions) => { console.log(sessions ) });
smForObject.listRelatedObjectSessions(objectKey); //force the list refresh
Automatic state polling
If the trackSessionState
option is true when you created your ScreenMeet object, then ScreenMeet
will automatically poll the ScreenMeet back-end for the session state. When a session changes state
from new
to active
a sessionstatechanged
event will be emitted from the ScreenMeet Object.
An updated
event will also be emitted.
Examples
Basic HTML example (should be run via web server, not via file://)
https://github.com/screenmeet/screenmeet-js-sdk/tree/master/example
React App Example: