Initializing

This document explains how to integrate the Voxeet SDK into your application. If you use UI components, please refer to the Client UXKit.

Prerequisites

Before using the SDK in your project, please go to your developer portal account to create your account. If you already have one, login and retrieve your API keys. The consumer key and the consumer secret will allow you to use the SDK and therefore, bring video and audio features to your users.

Add the SDK into your application

Add the voxeet-web-sdk by using yarn or npm command as in the following example:

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

You can add this line inside your HTML file to access to VoxeetSDK.

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

With Carthage dependency manager:

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.

You can install Carthage with Homebrew using the following command:

$ brew update
$ brew install carthage

To integrate VoxeetSDK into your Xcode project using Carthage, specify it in your Cartfile:

github "voxeet/voxeet-sdk-ios" ~> 2.0

Run carthage update to build the frameworks and drag VoxeetSDK.framework and WebRTC.framework into your Xcode project. More information at https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos.

Or download the lastest release zip:

VoxeetSDK: https://github.com/voxeet/voxeet-ios-sdk/releases

Unzip and drag and drop frameworks into your project, select 'Copy items if needed' with the right target. Then in the general tab of your target, add the VoxeetConferenceKit.framework, VoxeetSDK.framework and WebRTC.framework into 'Embedded Binaries'.

Add the public-sdk in the dependencies block of your app'sbuild.gradle

compile("com.voxeet.sdk:public-sdk:${voxeetSdkVersion}") {
    transitive = true
}

With voxeetSdkVersion the latest version available. As of writing, the version is 2.0.73.3

Initialize the SDK

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 Voxeet recommends the secure authentication method in production, the simpler method is suitable for prototyping of the app.

Use the following code to initialize Voxeet SDK by embedding the app secrets into the app.

VoxeetSDK.initialize('consumerKey', 'consumerSecret')

Initialization using OAuth mechanism with the initializeToken method

VoxeetSDK.initializeToken("accessToken", () => {
   return Promise.resolve("Refresh accessed Token");
})
.catch((error) => {
    // An Error has occured, see Error Types
});

Use the following code to initialize Voxeet SDK by embedding the app secrets into the app.

VoxeetSDK.initialize('consumerKey', 'consumerSecret')

Initialization using OAuth mechanism with the initializeToken method

VoxeetSDK.initializeToken("accessToken", () => {
   return Promise.resolve("Refresh accessed Token");
})
.catch((error) => {
    // An Error has occured, see Error Types
});

Initialize the SDK with your Voxeet app secrets, this is the quickest way to bootstrap your project.

import VoxeetSDK

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
        
        // Voxeet SDK initialization.
        VoxeetSDK.shared.initialize(consumerKey: "YOUR_CONSUMER_KEY", consumerSecret: "YOUR_CONSUMER_SECRET")
        
        // Example of public variables to change the conference behavior.
        VoxeetSDK.shared.notification.type = .none
        VoxeetSDK.shared.conference.defaultBuiltInSpeaker = false
        VoxeetSDK.shared.conference.defaultVideo = false
        VoxeetSDK.shared.conference.audio3D = false
        
        return true
    }
}

Alternatively, and as recommended by Voxeet, use the OAuth method to initialize the SDK.

Initialize the SDK with your Voxeet app secrets, this is the quickest way to bootstrap your project.

VoxeetSDK.initialize('consumerKey', 'consumerSecret');

Initialization using OAuth mechanism with the initialize method

VoxeetSDK.initialize("", new RefreshTokenCallback() {
    @Override
    public void onRequired(TokenCallback callback) {
        ...
        //create here asynchronous call to web then :
        callback.ok("new access token");
        //or in case of error with Exception exception
        callback.error(exception);
    }
});

Secure authentication

Even though it is convenient to bootstrap your project by embedding the application secrets, it is not recommended for production because the secrets can be easily extracted from the application. Voxeet provides 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.

Sequence

Initial authentication

The customer server, acting as an authentication broker, needs the application key and secret to authenticate against Voxeet /oauth2/token API. Upon receiving the access token from the customer's server, the application calls initializeToken API to initialize the Voxeet SDK.

Refresh authentication

An access token has a limited period of validity and needs periodic refreshing. The Voxeet SDK will invoke the callback provided to the initializeToken method when the access token needs to be refreshed. This callback will contact the customer's server, which in turn will call Voxeet /oauth2/refresh API and return the refreshed token. The callback must return a Promise containing the refreshed access token.

Invalidate token

When the application decides to disconnect from Voxeet, it is recommended that the access token is invalidated. Voxeet /oauth2/invalidate API can be used for this purpose.

Open a session

Open a session for the participant using the following code:

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

Open a session for the participant using the following code:

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

Open a session for the participant using the following code:

let info = VTParticipantInfo(externalID: "1234", name: "Username", avatarURL: "https://voxeet.com/logo.jpg")
VoxeetSDK.shared.session.open(info: info) { error in }

Open a session for the user using the following code:

ParticipantInfo participantInfo = new UserInfo("a name", "optionnal id", "optionnal https avatar url");

VoxeetSDK.session().open(participantInfo).then(new PromiseExec<Boolean, Object>() {
    @Override
    public void onCall(@Nullable Boolean result, @NonNull Solver<Object> solver) {
        //insert your logic
    }
}).error(error());

Note: You can cascading promises

Close a session

After the conference, you can close it using the following code:

VoxeetSDK.session.close()

After the conference, you can close it using the following code:

VoxeetSDK.session.close()

After the conference, you can close it using the following code:

Example

VoxeetSDK.shared.session.close { error in }

After the conference, you can close it using the following code:

VoxeetSDK.session().close().then(new PromiseExec<Boolean, Object>() {
    @Override
    public void onCall(@Nullable Boolean result, @NonNull Solver<Object> solver) {
        //insert your logic
    }
}).error(error());

Note: You can cascading promises

Result

Voxeet SDK is integrated with your application, so you have access to all SDK functionalities.
Now you can easily configure your SDK. Tutorials visible on the panel on your left side and reference documentation will guide you on how to do it.