Digital Samba Embedded
  • Introduction
  • SDK
    • DigitalSambaEmbedded class
    • Methods
      • addCustomTile()
      • removeCustomTile()
      • addFrameEventListener()
      • addImageToWhiteboard()
      • addTileAction()
      • addUICallback()
      • allowBroadcast()
      • allowScreenshare()
      • changeBrandingOptions()
      • changeLayoutMode()
      • changeRole()
      • changeToolbarPosition()
      • closeLibraryFile()
      • closeWhiteboard()
      • createWhiteboard()
      • configureCaptions()
      • configureVirtualBackground()
      • disableAudio()
      • disableVideo()
      • disableVirtualBackground()
      • disallowBroadcast()
      • disallowScreenshare()
      • enableAudio()
      • enableVideo()
      • enableVirtualBackground()
      • endSession()
      • featureEnabled()
      • hideCaptions()
      • hideToolbar()
      • leaveSession()
      • listUsers()
      • load()
      • lowerHand()
      • muteFrame()
      • maximizeLocalTile()
      • maximizeUser()
      • minimizeLocalTile()
      • minimizeContent()
      • minimizeUser()
      • off()
      • on()
      • once()
      • openLibraryFile()
      • openWhiteboard()
      • pinUser()
      • raiseHand()
      • removeFrameEventListener()
      • removeTileAction()
      • removeUICallback()
      • removeUser()
      • requestMute()
      • requestToggleAudio()
      • requestUnmute()
      • showCaptions()
      • showToolbar()
      • startRecording()
      • startScreenshare()
      • stopRecording()
      • stopScreenshare()
      • toggleAudio()
      • toggleCaptions()
      • toggleMuteFrame()
      • toggleToolbar()
      • toggleVideo()
      • toggleWhiteboard()
      • toggleLibraryFile()
      • unmuteFrame()
      • unpinUser()
    • Events
      • activeSpeakerChanged
      • appError
      • appLanguageChanged
      • audioDisabled
      • audioEnabled
      • captionsDisabled
      • captionsEnabled
      • captionsFontSizeChanged
      • captionsSpokenLanguageChanged
      • chatMessageReceived
      • featureSetUpdated
      • frameLoaded
      • handRaised
      • handLowered
      • layoutModeChanged
      • mediaDeviceChanged
      • permissionsChanged
      • recordingFailed
      • recordingStarted
      • recordingStopped
      • roleChanged
      • roomStateUpdated
      • screenshareStarted
      • screenshareStopped
      • sessionEnded
      • speakerStoppedTalking
      • userJoined
      • userLeft
      • usersUpdated
      • videoDisabled
      • videoEnabled
      • virtualBackgroundChanged
      • virtualBackgroundDisabled
    • Properties
      • features
      • localUser
      • permissionManager
      • roomState
  • REST API
    • Rate limiting
    • Pagination
    • Default room settings
      • List
      • Edit
    • Rooms
      • Create
      • Edit
      • List
      • Delete
        • All resources
        • Concrete resource
      • Files
      • Chat
        • List
        • Export
      • Questions & Answers
        • List
        • Export
      • Transcription
        • List
        • Export
        • Start
        • Stop
    • Sessions
      • List
      • End
      • Delete resources
        • All resources
        • Concrete resource
      • Transcripts
      • Summary (AI)
    • Participants
      • List
    • Roles and permissions
      • Permissions
      • Create
      • Edit
      • List
      • Delete
    • Live usage
      • Rooms
      • Participants
    • Statistics
      • Current period
      • Team
      • Room
    • Tokens
      • Properties
      • Create
    • Recordings
      • List
      • Download
      • Start
      • Stop
      • Delete
      • Archive
      • Unarchive
    • Polls
      • Create
      • Edit
      • List
      • Delete
      • Export
      • Results
    • Content Library
      • Create
      • Edit
      • List
      • Delete
      • Folders
        • Create
        • Edit
        • List
        • Delete
      • Files
        • Upload
        • Webapps
        • Whiteboards
        • Edit
        • List
        • Delete
    • Telephony
      • Participant Join
      • Participant Leave
    • Webhooks
      • Payload structure
      • Create
      • Edit
      • List
      • Delete
    • Scribe / Postman docs
  • Dashboard docs
  • LTI docs
Powered by GitBook
On this page
  1. SDK

DigitalSambaEmbedded class

PreviousSDKNextMethods

Last updated 1 month ago

This is the main class of the . Your journey always starts by initializing this class and then calling its to control your integration. There are also various to subscribe to with callbacks.

There are two approaches to initializing:

  • Using the constructor which will load immediately the specified room based on the and the optional .

    //instanceProperties is an optional param
    const sambaFrame = new DigitalSambaEmbedded(initOptions, instanceProperties);
  • Using the createControl factory method. Later you can load the room by calling the method. That way creation of the DigitalSambaEmbedded class is decoupled from the actual loading of the room which gives you more control during initialization.

    // notice `createControl` vs constructor call
    const sambaFrame = DigitalSambaEmbedded.createControl(initOptions);
    
    // ...
    // when necessary, load the room in the frame
    // instanceProperties is optional
    sambaFrame.load(instanceProperties);

InitOptions - look also at the

  • root - HTMLElement. If specified, target frame will be created as a child tag of root. Otherwise the created iframe will be appended to the body tag of the page

  • frame - HTMLIFrameElement to be wrapped. This is useful if you want the room to be loaded in an iframe element which already exists. If frame is not specified, then an iframe element will be created automatically by the SDK

  • url - full room URL to be applied as the iframe src attribute. Must include https protocol. https://[teamNameHere].digitalsamba.com/[roomNameHere]

  • team - team name (string) - used if you do not want to specify the url manually

  • room - room name (string) - used if you do not want to specify the url manually

  • token - optional JWT string for authentication, mainly for private rooms

  • templateParams- an optional JSON object configuring custom URL template parameters when opening an embedded content from the content library. These template parameters are very useful to provide per user authentication or identification when embedding external websites.

    {
       "GEOGEBRA_TOKEN": "..............."
    }

    Parameters are specified with curly braces in the embedded URLs - e.g. https://www.anexternalwebsite.com/?gt={GEOGEBRA_TOKEN} Note {USERNAME} is supported as a default built-in param and you don't need to configure it. The name with which the user entered the room will automatically replace the template. https://www.anexternalwebsite.com/?name={USERNAME}

  • roomSettings - an optional JSON object configuring the initial room settings. Read also about the possible and how to configure custom array.

    {
      //Configures if user's video device will be enabled on entering the room
      videoEnabled: boolean,
      
      //Configures if user's audio device will be enabled on entering the room
      audioEnabled: boolean,
      
      //Configures initial video and audio devices to use on entering the room
      mediaDevices: {
        videoinput: 'id of camera',
        audioinput: 'id of microphone',
        audiooutput: 'id of speaker device'
      },
      
      //Language for the user. Use language code - e.g. en, de-DE, es-ES
      appLanguage: string,
      
      //Name of the user on entering the room
      username: string,
      
      //Custom initials (max 2 letters) for the user tile
      initials: string,
      
      //If 'auto' or 'tiled' layout mode will be used
      layoutMode: string,
      
      //If the toolbar will be visible or not
      showToolbar: boolean,
      
      //If the captions panel will be visible or not
      showCaptions: boolean,
      
      //The virtual background
      virtualBackground: VirtualBackgroundOptions,
      
      /*
        Allows you to customize the virtual backgrounds available 
        to users in your application. You can provide your own collection
        of backgrounds and optionally replace the default backgrounds
      */
      virtualBackgrounds: [
        Read below how to configure it
      ],
      
      // Replace default backgrounds with custom ones (optional)
      replaceVirtualBackgrounds: false,
      
      //If the frame will be muted on join for the local user
      muteFrame: boolean,
      
      //If a confirmation modal will be shown when you remove (kick) another user
      requireRemoveUserConfirmation: boolean
    }
  • url - will create a frame as a child of the body tag and load the room url

  • url + root - will create a frame as a child of root element and load the room url

  • url + frame - will load the room url in the provided existing frame

  • team + room - will create a frame as a child of the body tag and load the specified room

  • team + room + root - will create a frame inside root element and load the specified room

  • team + room + frame - will load the specified room in the provided existing frame

  • frame - will attach to the specified existing frame (assuming you've manually set correct room url as the iframe src)

Virtual Backgrounds Configuration

The Digital Samba SDK allows you to customize the virtual backgrounds available to users in your application. You can provide your own collection of backgrounds and optionally replace the default backgrounds provided by the SDK.

Custom Backgrounds Collection

You can provide a custom collection of virtual backgrounds during SDK initialization:

const sambaFrame = DigitalSambaEmbedded.createControl({ 
  url: roomUrl,
  // Other configuration options...
  roomSettings: {

    // Custom backgrounds collection (optional)
    virtualBackgrounds: [
      {
        id: 'custom-bg-1',    // Unique identifier
        type: 'image',        // Type: 'blur', 'image', or 'video'
        value: 'https://example.com/custom-bg-1.jpg', // URL or blur strength
        thumbnail: 'https://example.com/custom-bg-1-thumb.jpg', // Optional for images, required for videos
        label: 'Custom Background 1' // Display name
      }
    ],
  
    // Replace default backgrounds with custom ones (optional)
    replaceVirtualBackgrounds: false
  }
});

sambaFrame.load();

Background Item Properties

Property
Type
Description
Required

id

string

Unique identifier for the background.

Yes

type

string

Type of background: 'blur', 'image', or 'video'.

Yes

value

string

For blur: 'balanced' or 'strong'. For image/video: URL to the resource.

Yes

thumbnail

string

URL to a thumbnail image. Optional for images, required for videos.

No for images, Yes for videos

label

string

Display name for the background.

No

Replacing Default Backgrounds

By default, the SDK provides a set of predefined backgrounds. You can choose to replace them with your custom collection by setting replaceVirtualBackgrounds to true:

const sambaFrame = DigitalSambaEmbedded.createControl({
  url: roomUrl,
  // Other configuration options...
  roomSettings: {
     virtualBackgrounds: [
       // Your custom backgrounds...
     ],
     replaceVirtualBackgrounds: true
  }
});

sambaFrame.load();

If replaceVirtualBackgrounds is set to true but no virtualBackgrounds are provided, the default backgrounds will be preserved and an error will be emitted.

The SDK validates all virtual background items to ensure they meet the required format. If validation fails, an error event will be emitted and the invalid backgrounds will be ignored.

  • frameAttributes - list of attributes to be applied to the target iframe

  • reportErrors - boolean, false by default. Whether to report misconfiguration or runtime errors to the browser console

Code examples of the possible initOptions combinations:

//SDK will create a frame as a child of the body tag and load the room url
import DigitalSambaEmbedded from '@digitalsamba/embedded-sdk';
const roomUrl = 'https://[TEAM_NAME_HERE].digitalsamba.com/[ROOM_NAME_HERE]';
const sambaFrame = DigitalSambaEmbedded.createControl({ 
    url: roomUrl,
    //Optional room settings
    /*roomSettings: {
        username: 'John Smith'
        layoutMode: 'auto',
        virtualBackground: { blur: 'balanced' },
        .....................
    },*/
    //token: TOKEN_HERE_IF_YOU_ARE_USING_IT
});
sambaFrame.load();
//SDK will create a frame as a child of the parent element and load the room url
import DigitalSambaEmbedded from '@digitalsamba/embedded-sdk';
const parentElement = document.querySelector('USE_CSS_SELECTOR_HERE');
const roomUrl = 'https://[TEAM_NAME_HERE].digitalsamba.com/[ROOM_NAME_HERE]';
const sambaFrame = DigitalSambaEmbedded.createControl({ 
    url: roomUrl, 
    root: parentElement,
    //token: TOKEN_HERE_IF_YOU_ARE_USING_IT
});
sambaFrame.load();
//SDK will load the room url in the specified existing iframe
import DigitalSambaEmbedded from '@digitalsamba/embedded-sdk';
const existingIFrame = document.querySelector('USE_CSS_SELECTOR_HERE');
const roomUrl = 'https://[TEAM_NAME_HERE].digitalsamba.com/[ROOM_NAME_HERE]';
const sambaFrame = DigitalSambaEmbedded.createControl({ 
    url: roomUrl, 
    frame: existingIFrame,
    //token: TOKEN_HERE_IF_YOU_ARE_USING_IT
});
sambaFrame.load();
//SDK will create a frame as a child of the body tag and load the specified room
import DigitalSambaEmbedded from '@digitalsamba/embedded-sdk';
const teamName = 'TEAM_NAME_HERE';
const roomName = 'ROOM_NAME_HERE';
const sambaFrame = DigitalSambaEmbedded.createControl({ 
    team: teamName, 
    room: roomName,
    //token: TOKEN_HERE_IF_YOU_ARE_USING_IT
});
sambaFrame.load();
//SDK will create a frame as a child of the parent element and load the room
import DigitalSambaEmbedded from '@digitalsamba/embedded-sdk';
const parentElement = document.querySelector('USE_CSS_SELECTOR_HERE');
const teamName = 'TEAM_NAME_HERE';
const roomName = 'ROOM_NAME_HERE';
const sambaFrame = DigitalSambaEmbedded.createControl({ 
     team: teamName, 
     room: roomName,
     root: parentElement,
     //token: TOKEN_HERE_IF_YOU_ARE_USING_IT
});
sambaFrame.load();
//SDK will load the room in the specified existing frame
import DigitalSambaEmbedded from '@digitalsamba/embedded-sdk';
const existingIFrame = document.querySelector('USE_CSS_SELECTOR_HERE');
const teamName = 'TEAM_NAME_HERE';
const roomName = 'ROOM_NAME_HERE';
const sambaFrame = DigitalSambaEmbedded.createControl({ 
     team: teamName, 
     room: roomName,
     frame: existingIFrame,
     //token: TOKEN_HERE_IF_YOU_ARE_USING_IT
});
sambaFrame.load();
//SDK will attach to the specified existing frame
//Assuming you've manually preset correct room url as the iframe src
import DigitalSambaEmbedded from '@digitalsamba/embedded-sdk';
const existingIFrame = document.querySelector('USE_CSS_SELECTOR_HERE');
const sambaFrame = DigitalSambaEmbedded.createControl({ 
     frame: existingIFrame,
     //token: TOKEN_HERE_IF_YOU_ARE_USING_IT
});
sambaFrame.load();

Sample usage of the optional instanceProperties to set a red border and also report errors:

import DigitalSambaEmbedded from '@digitalsamba/embedded-sdk';
const roomUrl = 'https://[TEAM_NAME_HERE].digitalsamba.com/[ROOM_NAME_HERE]';
const sambaFrame = DigitalSambaEmbedded.createControl({ url: roomUrl });

//SDK will put a 5px solid red border around the iframe
const instanceProps = { 
   frameAttributes: {style: "border: 5px solid red"}, 
   reportErrors: true 
};
sambaFrame.load(instanceProps);

The following combinations of fields are valid for initOptions ( and roomSettings can be used with any of them):

InstanceProperties - look also at the

Note that you can use any initOptions combination from the .

token
SDK
methods
events
load
token
VirtualBackgroundOptions
InitOptions
InstanceProperties
code examples
virtualBackgrounds
code example
previous examples