Getting started

To start video conference you need to follow 3 simple steps:

  1. Add VideolinkPlatform JS SDK into your webpage
  2. Create container where conference controls will be inserted
  3. Run few lines of javascript code when page is loaded.

Let’s take a look at what we’ve got:

<script src="http://cdn.videolinkplatform.com/vl_api.js"></script> 
<div id="conference-scene"></div> 
<script> 
    window.onload = function() { 
        new VideolinkPlatformConnector(
            {container: 'conference-scene', apiKey: '[[YOU_API_KEY]]'}, 
            function(connector) {
                vlRoom = connector.createRoom({name: 'test room'}); 
            }
        ) 
    } 
</script>

With first 2 lines we added link to JS SDK and created container element:

<script src="http://cdn.videolinkplatform.com/vl_api.js"></script> 
<div id="conference-scene"></div>

Then initialised connection to VL Platform and after it was established created room with name “test room”:

new VideolinkPlatformConnector(
    {container: 'conference-scene', apiKey: '[[YOU_API_KEY]]'}, 
    function(connector) { 
        vlRoom = connector.createRoom({name: 'test room'}); 
    }
)

That’s it. This few lines code snipped is enough to create video conference that works in all desktop browsers (including ones that don’t support WebRTC).

Each API key has its own rooms namespace. So room with name “test room” and API key “123” is not the same as room with name “test room” and API key “345”.

More sophisticated demo

Let's try to build simple video conferencing service based on Videolink Platform.

Our service will provide public rooms, each with custom url, that is the way for other users to connect in.

Layout and JS imports

We always need to have a scene (place where all video elements will be inserted) and SDK js script to be imported:

<script src="http://cdn.videolinkplatform.com/vl_api.js"></script>
<div id="conference-scene"></div>

Create room if user is conference initiator

If user creates new conference, we need to generate conference ID for him and change page url, so he can share it with other users to let them connect.

/**
 * This function generates random id
 */
function generateRoomUID() {
    return 'xxxxxxxx-yxxx-xxxxxxxxxxx'.replace(/[xy]/g, function(c) {
        var r = Math.random()*16|0, v = c == 'x' ? r : (r&0x3|0x8);
        return v.toString(16);
    });
}

/**
 * If room id is passed in url, use that one, otherwise generate random value
 */
function getRoomId() {
    if (window.location.hash.length > 0) {
        return window.location.hash.replace('#', '');
    }
    return generateRoomUID();
}

Function getRoomId checks if window.location.hash already contains room id (it does if somebody connects to existing conference) and creates new one if it's empty.

Function generateRoomUID generates random 25 symbols long room name (when we need to crate new one).

Connect via Videolink Platform

window.onload = function() {
    new VideolinkPlatformConnector({container: 'conference-scene', apiKey: '[[YOU_API_KEY]]'}, function(connector) {
        var roomName = getRoomId();
        vlRoom = connector.createRoom({name: roomName});
        //Change page url, so user can share connection to this conference room
        if (location.href.indexOf('#') == -1) window.location.hash = roomName;
    })  
}

Code above establishes connection to Videolink Platform and creates video room (or connects to existing one). It also changes page url from 'http://example.com' to 'http://example.com#random-room-hash', so user can send this link to other participants and they can also connect to the same room.

Well, that's it!

You can see demo based on the example above here.

Advanced use

There are 2 main classes that are used to establish and manage video conference: VideolinkPlatformConnector and VideolinkPlatformRoom.

VideolinkPlatformConnector provides communication channel between browser and VideolinkPlatform cloud and prepares everything to video conference start: creates DOM elements (if needed), establishes required signalling connections, etc. It’s also used to create VideolinkPlatformRoom, that actually incapsulates video conference.

VideolinkPlatformRoom uses VideolinkPlatformConnector to communicate with the cloud and provides methods to manage current conference.

VideolinkPlatformConnector

VideolinkPlatformConnector is a data bridge between all conference participants. It detects browser capabilities, creates all required connections and manages user identities. It’s also used to create conference room and is starting point for conference establishment.

Create new connector

var vlPlatform = new VideolinkPlatformConnector(settings, onReady, onError);

Parameters

  • settings*

    • apiKey: your personal API key. Connections without API key are not allowed.
    • container: DOM element where conference controls and containers will be inserted. If “container” is not specified, createRoom() method should receive remoteContainer and localContainer options.
  • onReady(connector): callback that contains VideolinkPlatformConnector instance as parameter and is called if connection was successfully established.

  • onError(errorMessage): error callback that contains error string as parameter. Usually caused when server is unreachable (no internet connection) or because of incorrect API key.

var vlPlatform = new VideolinkPlatformConnector(
    {apiKey: 'API-KEY-HERE', container: 'conference-scene'}, 
    function(connector) { 
        //Connection established, now we can create a room 
    }, function(error) { 
        console.log('Error happened: ' + error); 
    }
);

VideolinkPlatformRoom

VideolinkPlatformRoom is a representation of video conference room. That’s the place where users can exchange messages, join/leave conversation, etc.

Create room

var vlRoom = vlPlatformConnector.createRoom(roomOptions).on(callbacks)

Room options:

  • remoteContainer: DOM element where remote video stream will be inserted
  • localContainer: DOM element where local video stream (small) will be inserted
  • name: name of the room where user should be connected to. If room doesn’t exist it will be created. If “name” is not specified, random value will be generated.

After room was created current user will be automatically connected to the conference. SDK will ask him for permission to access his webcam/microphone and after approval will share his video/audio streams to other participants.

Own video will be inserted into localContainer and video streams of remote participants into remoteContainer.

if localContainer and remoteContainer are not specified, elements created in global container (specified in VideolinkPlatformConnector settings.container) will be used.

var vlRoom = vlPlatformConnector.createRoom({name: 'test room'});

Room methods

getUserId

Each user that connects to a conference gets own unique id. This id is stored in browser cookies and is used as user identification key.

console.log('Current user: ' + vlRoom.getUserId());

leave

Leave current conference room.

vlRoom.leave();

mute

Mute own microphone.

vlRoom.mute();

unmute

Stop own microphone muting.

vlRoom.unmute();

muteWebcam

Stop sending own video stream.

vlRoom.muteWebcam();

unmuteWebcam

Start sending own video stream.

vlRoom.unmuteWebcam();

sendMessage

Send message to particular user. Each user will receive this message in onMessage event.

vlRoom.sendMessage('123456', {type: 'chat-message', text: 'hello!'});

sendBroadcastMessage

Send message to all conference participants. Each user will receive this message in onBroadcastMessage event.

vlRoom.sendBroadcastMessage({type: 'chat-message', text: 'hello everybody!'});

Room events

To get notified when room events are fired you can use .on method and bind own event handler for any event. For example

vlRoom.on('onBroadcastMessage', function(message) {
    console.log(message)
})

onCreated

Fired after room was successfully created.

vlRoom.on('onCreated', function() {
    console.log('Room successfully created');
})

onConnected

Fired when local user connects to the conference.

vlRoom.on('onConnected', function() {
    console.log('Local user connected, lets try to get access to his webcam');
})

onBeforeCaptureMedia

Fired before getUserMedia is executed. Since getUserMedia usually asks user permission to receive access to his camera/mic, onBeforeCaptureMedia is a good play to tell user why we need to get access to his webcam.

vlRoom.on('onBeforeCaptureMedia', function() {
    alert("Dear user, it's time to check how strong is our friendship. In a second we'll ask access to your webcam.");
})

onAllowMediaCallback

Fired if user allowed to use his media webcam/mic.

vlRoom.on('onAllowMediaCallback', function() {
    alert("Dear friend! Thank you for providing access to your webcam. You'll be connected to the conference shortly.");
})

onNoWebcam

Fires if current user doesn’t have webcam or didn’t allow to use it.

vlRoom.on('onNoWebcam', function() {
    alert('Dear user, you need to have webcam or at list microphone to be able to join the room');
})

onLocalStream(stream)

stream: Local video (or audio) stream

Fired when local user provides his video/audio stream.

vlRoom.on('onLocalStream', function(stream) {
    console.log('Local user joined the conference. Waiting for other participants...');
})

onRemoteParticipantConnected(stream, remoteId)

stream: video or audio stream of connected participant

remoteId: connected participant id

Fired when remote participant got connected to the room.

vlRoom.on('onRemoteParticipantConnected', function(stream, remoteId) {
    alert('Good news everyone! User #' + remoteId + ' joined our conference');
})

onRemoteParticipantDisconnected(remoteId)

remoteId: remote participant id

Fired when participant leaves the room.

vlRoom.on('onRemoteParticipantDisconnected', function(remoteId) {
    alert('User #' + remoteId + ' left us');
})

onEmpty

Fired when last participant left the room. This event fires only if room had some participants, but they all have left.

vlRoom.on('onEmpty', function() {
    console.log('Now we are alone');
})

onMessage(message)

message: structure-free object

Fired when message received. Messages are the way to communicate with particular user.

vlRoom.on('onMessage', function(message) {
    alert('Incoming message: ' + message.text);
})

onBroadcastMessage(message)

message: structure-free object

Broadcast message received. Broadcast messages are sent to all room participants and are handy to send group notification, chat messages, etc.

vlRoom.on('onBroadcastMessage', function(message) {
    alert('Incoming group message: ' + message.text);
})

onClientTypeChange

Fires if browser doesn’t support WebRTC and SDK switches to Flash.

vlRoom.on('onClientTypeChange', function() {
    alert("Dear user, unfortunately you browser doesn't support latest technologies, so we will have to switch to compatibility mode.");
})

Screen sharing

VideolinkPlatform provides screen sharing from Chrome to other WebRTC supporting browsers via Chrome extension, which is used as the most convinient and easy way to get access to user screen. Extension can be used to share screen as well as single window.

Since Chrome extension restricted to url of website that will use it, we've made a tool that automatically generates custom screen sharing extensions (with custom name and logo). Such extensions can be uploaded to Chrome Store and distributed to end users.

How to build screen sharing extension

  1. Generate custom screen sharing extension with our tool.
  2. Upload extension to Chrome Web Store (how to upload extensions to Chrome Store).

  3. In order to let your users install extension directly from web page (without visiting Chrome Store), you need to add special meta tag to header section of your page to specify connection with extension: 

    <link rel="chrome-webstore-item" href="https://chrome.google.com/webstore/detail/EXTENTION_ID">
    EXTENTION_ID is unique id of extension that is generated for each uploaded item. How to get id of my extention?

  4. After you have meta tag in place you can use object window.videolinkPlatformScreenSharing from JS SDK to manage screen sharing.

    To start sharing just execute window.videolinkPlatformScreenSharing.share, which installs extension (if needed), asks current user which screen (or window) should be shared and sends it to other participants after selection.

Below you can find more information about screen sharing related functions.

SDK methods

JS SDK contains public object window.videolinkPlatformScreenSharing which should be used to manage screen sharing.

window.videolinkPlatformScreenSharing.setExtensionId(ext_id)

Set id of screen sharing extension. This method must be called before sharing initialisation.

ext_id: id of your screen sharing extension

window.videolinkPlatformScreenSharing.onInstall(callback)

Callback function that will be executed if user was prompted to install extension and installation was successfully completed. In order to activate extension web page must be reloaded, so this callback should always refresh it. If callback is not specified, SDK will reload page automatically after installation.

callback: code to execute after extension was installed

window.videolinkPlatformScreenSharing.onSuccess(callback)

Callback function that will be executed after user shared his screen.

callback: code to execute after screen (or window) was shared.

window.videolinkPlatformScreenSharing.share(options)

Share screen or single window of current user to other participants. Before running this function setExtensionId must be executed.

options: array that specifies type of sharing. Supported values "screen", "window" or both.

window.videolinkPlatformScreenSharing.share(["screen", "window"])

window.videolinkPlatformScreenSharing.stop()

Stop screen sharing.