Make a Video Call with Web SDK

Web SDK Integration Architecture

The Web SDK is a fast and effective way to include a live video chat in a web application. It consists of a JavaScript library that adds a floating widget to your web page, allowing chats and video calls out of the box. In addition, you can customize the user experience, or even leverage your own chat widget in place of the one supplied, by using the functions and parameters provided by the library. The SDK can be included as an NPM module or it can be embedded directly in a web page.

The following diagram represents the most common integration layout of the Web SDK and the section following the diagram elaborates on the flow:

πŸ“˜

Note:

The access token used by the SDK is obtained on the server side. This implementation ensures that the apiKey is not shared publicly, and the access token is bound to the user session on the integrated website.

Using the apiKey on the client side is strongly discouraged and should be absolutely avoided in production.

1. Authenticate User

The user accesses the integrated website by leveraging an authentication method of choice. User authentication is done externally from Kaleyra Video.

2. Obtain Access Token

A back-end service calls the API Generate Credentials passing the following payload, using the appropriate userId:

{
   "user_id": "user id",
   "expires_in": 3600
}
{
    "access_token": 
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoidGVzdCIsImNvbXBhbnlJZCI6IjEzM2Q0MmNlLWVkZGItMTFlNi05OTUzLTAyMTI0YWI0M2Q2NyIsImFsbG93Q2FtZXJhIjp0cnVlLCJpYXQiOjE2NTEwNTQ4MjEsImV4cCI6MTY1MTA1ODQyMSwiaXNzIjoiQHN3aXRjaGJvYXJkLWNvcmUiLCJzdWIiOiJ0ZXN0IzEzM2Q0MmNlLWVkZGItMTFlNi05OTUzLTAyMTI0YWI0M2Q2NyJ9.une0gwwke1ZwShfXbSPk3KDtbEQ39-aMXWmgsq8M8M0",
    "expires_at": "2022-01-10T11:41:19.000Z",
    "user_id": "user_xxx"
}

The access token can be found in the response.

πŸ“˜

Access Token Expiration

A refresh policy for the token may be needed to ensure a smooth experience for the user.

The expires_in parameter represents the access token’s expiration time expressed in seconds. It must be chosen within a range between 360 (6 minutes) and 86400 (24 hours).

This operation is usually done in the context of user authentication so that the access token is returned to the client along with the user information. Alternatively, it can be retrieved at a later time, before displaying the widget. This is an implementation choice. A refresh policy for the token may be needed to ensure a smooth experience for the user.

3. Connect

The Web SDK can connect the user to Kaleyra Video by using the connect function Client.connect(userId, accessToken).

You can make a basic integration of the widget for testing purposes by simply copy-pasting the following snippet of code inside the <body> tag of an HTML file.

Substitute <version> with the desired version of the SDK.

πŸ“˜

Note:

You can find the latest version here: https://github.com/Bandyer/Bandyer-Chat-Widget#versions
Alternatively, if you have npm installed, you can run npm view @bandyer/bandyer-chat-widget version
on your terminal.

Set userId, appId, region, environment, and accessToken variables as indicated in the following code:

πŸ“˜

Note:

In sandbox environment β€˜region’ is always β€˜eu’.

<script src="https://cdn.bandyer.com/sdk/js/chat/<version>/bandyer-widget.min.js" type="text/javascript" ></script>
<script type="text/javascript">
    const userId = 'user id';
    const appId = 'app id associated to your account';
    const region = 'region to which your account belongs: eu or in';
    const environment = 'sandbox or production';
    const accessToken = 'returned by POST /sdk/credentials on server side' 		
    window.createWidget = async function() {
        window.Client = window.BandyerSDK.configure({
          appId: appId,
	      region: region,
	      environment: environment,
            tools: {
	          chat: true
	      }
        })
        await Client.connect(userId, accessToken)
    };

    window.createWidget();
</script>

πŸ‘

Good Job!

There are a more customizations available. Refer to Chat-Widget for further information.

Sample template

For a more complete template that includes a refresh policy for the access token you can refer to the following code snippet.

<script src="https://cdn.bandyer.com/sdk/js/chat/<version>/bandyer-widget.min.js" type="text/javascript" ></script>
<script type="text/javascript">
    const userId = 'user id';
    const appId = 'app id associated to your account';
    const region = 'region to which your account belongs: eu or in';
    const environment = 'sandbox or production';

    const retrieveAccessToken = async (region, environment, userId) => {
        // Retrieve the access token using POST /sdk/credentials on server side
        const accessToken = await callToYourServer()
        return accessToken
    }
    
    window.createWidget = async function() {
        window.Client = window.BandyerSDK.configure({
            appId: appId,
            region: region,
            environment: environment,
            tools: {
                // Choose you tools configuration
                chat: true
            }
        })
        try {

            Client.on('client:access_token:is_about_to_expire', async (data) => { // data: {expiresAt: "2022-01-10T11:41:19.000Z"'}
                const accessToken = await retrieveAccessToken(region, environment, userId); // Async function that allows you to ask a new access token to the server
                // Provide the obtained accessToken to the sdk
                const { expiresAt } = await Client.updateAccessToken(accessToken); // Return the new expiration date

            })
          
            Client.on('client:access_token:expired', async() => {
                // The session expired, you need to re-connect the Client with a new access token
                await Client.disconnect();
                const accessToken = await retrieveAccessToken(region, environment, userId); // Async function that allows you to ask a new access token to the server
                // Retrieve a new accessToken
                await Client.connect(userId, accessToken)
            })

            const accessToken = retrieveAccessToken(region, environment, userId)
            await Client.connect(userId, accessToken)
        } catch (e) {
            // Check the appid, region, environment or the access token
            console.error('Failed to retrieve the access token or to connect', e)
        }
    }

    window.createWidget();
</script>