@digitalsamba/embedded-sdk
v0.0.41
Published
Digital Samba Embedded SDK - control easily with JS your iframe integration.
Downloads
868
Readme
Description
Digital Samba Embedded SDK - control easily with JS your iframe integration.
Usage with NPM
Add it to dependency list using your preferred package manager:
npm install @digitalsamba/embedded-sdk
or
yarn install @digitalsamba/embedded-sdk
After installation, use it in your application code using provided import:
const DigitalSambaEmbedded = require('@digitalsamba/embedded-sdk');
// or, using imports
import DigitalSambaEmbedded from '@digitalsamba/embedded-sdk';
This package is written in TypeScript, so type definitions are also available:
import { SendMessageType, ReceiveMessageType /* ...etc */ } from '@digitalsamba/embedded-sdk';
Initialization
Secure context
️Since the embedded app relies on media device capabilities, it needs to be accessed in a secure context (https://
versus http://
).
For local development, most browsers treat http://localhost
and http://127.0.0.1
as secure.
Configuring SDK instance
Library provides alternative initialization styles. Using the class constructor you can configure it and load the frame in one call:
const api = new DigitalSambaEmbedded(InitOptions, InstanceProperties /* optional */);
or you can pre-configure the instance and then load it on-demand:
// notice `createControl` vs constructor call
const api = DigitalSambaEmbedded.createControl(InitOptions);
// ...
// when necessary, load the frame:
api.load(InstanceProperties /* optional */);
InitOptions
InitOptions
has the following fields:
root
- HTMLElement. If specified, target frame will be created within it.frame
- HTMLIFrameElement to be wrapped.url
- full URL to be applied as frame src. Must include protocol andtoken
query param for private rooms;team
- team name stringroom
- room identifier stringtoken
- optional string for authentication, mainly for private rooms
To successfully initialize an instance of the wrapper one of following combinations needs to be used:
root + team + room
- will create a controlled frame insideroot
elementframe + team + room
- will attach to existing frameframe
- will attach to existing frame (assuming you've manually specified correct frame src)root + url
- will create a frame insideroot
element
Remember to always specify allow="camera; microphone; display-capture; autoplay;"
and allowFullscreen="true"
attributes on iframe if you want to wrap around an existing iframe.
InstanceProperties
frameAttributes
- list of attributes to be applied to target iframereportErrors
- boolean, false by default. Whether to report misconfiguration or runtime errors to console
Usage
Once initialized you can listen to events emitted by embedded app and control it by sending commands.
Additional functionality like room permission management and exposed state is also available.
Events
To listen for events, attach listener for any of supported events:
api.on('userJoined', (data) => {
// ...
});
💡 See the events docs for a full list of available events.
Error event can provide useful details:
api.on('appError', (error) => {
console.log(error);
/* outputs {
name: 'not-allowed',
message:
'Recording disabled. You’ll need to edit this room’s properties to record sessions in this room',
data: {
type: 'recording'
}
},
*/
});
For debugging purposes, you can also listen to all events simultaneously
api.on('*', (data) => {
console.log(data);
});
Commands
To send commands, api instance provides handy utilities:
api.toggleVideo();
// ...
api.disableAudio();
💡 Full list of available commands with usage examples can be found on documentation website.
Examples
There are several demos available with example integrations
- Simple Videoroom - simple demo that showcases basic integration, listening to events and running commands
- Initial settings - examples of setting default settings prior to loading the frame
- Managed State demo - shows how to use exposed state in complex scenarios, listening to events, checking for permissions and accessing stored data.