NEWDolby Interactivity APIs are now the Dolby.io Communications APIs Learn More >
X

Initializing

This document explains how to integrate the Dolby.io Communications Client SDKs into your application. If you use UI components, please refer to the UXKit.

Prerequisites

Before using the SDK in your project, find your Consumer Key and Consumer Secret by following these steps:

  1. Select the SIGN IN link located in the upper right corner of the Dolby.io page. Log in using your email and password.
  2. Click the DASHBOARD link visible in the upper right corner of the website.
  3. Select your application from the APPLICATIONS category located on the left side menu.
  4. Select the API Keys category from the drop-down menu visible under your application.
  5. In the Communications APIs section, you can access your Consumer Key and Consumer Secret.

Add the SDK into your application

To add the Dolby.io Communications SDK for Web into your application, you can either use a packet manager or insert the proper script inside your HTML file.

If you want to use a package manager, add voxeet-web-sdk to your application by using the npm or yarn command, as in the following examples:

npm i @voxeet/voxeet-web-sdk
yarn add @voxeet/voxeet-web-sdk

If you want to use a CDN, add the following script to your HTML file:

<script
  src="https://unpkg.com/@voxeet/voxeet-web-sdk"
  type="text/javascript"
></script>

Initialize the SDK with secure authentication

There are two ways to initialize the SDK. You can either use the recommended secure authentication method or simply embed the app secrets in the app and call the initialize method. For security reasons Dolby recommends the secure authentication method in production; the simpler method is suitable for prototyping of the app.

This section describes how to use the secure method.

The Dolby.io Communications APIs provide an easy to use server-side RESTful API that allows customers’ servers to act as brokers that refresh tokens, so the application secrets are not distributed over the Internet.

The following diagram illustrates the workflow of the secure authentication model.

The secure Auth sequenceThe secure Auth sequence

The secure Auth sequence

Customer’s server

A sample server can be found within the voxeet-io-web repository. The README file explains how to run the server with the secrets for your application.

The examples shown use the API presented by the sample server for communication between the application and the server. The examples assume that this communication is secure and the application is trusted. In a real service, the application’s user would need to log into this server.

Initial authentication

The customer’s server, acting as an authentication broker, needs the application key and secret to authenticate against the /oauth2/token API.
The access token is returned and the customer’s server passes it back to the application.
Upon receiving the access token from the customer’s server, the application calls the initializeToken API to initialize the Dolby.io Communications Client SDKs.

The customer’s server can request the access token with:

let consumerKey = "consumerKey";
let consumerSecret = "consumerSecret";
let authHeader =
  "Basic " + btoa(encodeURI(consumerKey) + ":" + encodeURI(consumerSecret));

let tokenURL = "https://session.voxeet.com/v1/oauth2/token";
let tokenParams = {
  method: "POST",
  headers: {
    Authorization: authHeader,
  },
  body: {
    grant_type: "client_credentials",
  },
};

var access_token;

fetch(tokenURL, tokenParams)
  .then((data) => data.json())
  .then((result) => {
    access_token = result.access_token;
    // Return the access_token to the application

    console.log(`returned access_token is ${result.access_token}`);
  });

When the application has received the access token from the customer’s server, it can initialize the SDK with:

fetch(serverURL + '/api/token')
 .then(data => data.json())
 .then(result => {
 access_token = result.access_token

 VoxeetSDK.initializeToken(access_token, () => {
 // This callback is called when the token needs to be refreshed. See the next section for details.
 ...
 }).catch(error => {
 // An Error has occured
 })
 })

Refresh authentication

An access token has a limited period of validity and needs periodic refreshing. In the application, the Dolby.io Communications Client SDKs invokes the callback provided to the initialize call when the access token needs to be refreshed. This callback contacts the customer’s server, which in turn calls the /oauth2/token API again and returns the refreshed token, which is passed back to the Client SDK by the application.

When the application has received the refreshed access token from the customer’s server, it can pass this to the SDK with this change:

/**
The callback to `VoxeetSDK.initializeToken` must return a Promise containing 
the refreshed access token
*/

const url = serverURL + '/api/token';
fetch(url)
 .then(data => data.json())
 .then(json => {
 VoxeetSDK.initializeToken(json.access_token, () => {
 // This callback is called when the token needs to be refreshed.

 // Call the server to get a new access token
 return fetch(url)
 .then(data => data.json())
 .then(json => json.access_token)
 .catch(error => {
 // An error has occurred
 });
 });
 })
 .then(() => {
 // Initialize your application
 })
 .catch(error => {
 // An error has occurred
 });

Open a session

/* Example of participantInfo */
await VoxeetSDK.session.open({ name: "John Doe" })

Close a session

await VoxeetSDK.session.close()

Result

The Dolby.io Communications Client SDKs is integrated with your application, so you have access to all SDK functionalities.

Now you can easily configure your SDK. Tutorials available in the left-side navigation panel and reference documentation guides how to do it.


Did this page help you?