Getting Started
VideoKit is a service that provides an API and SDK that allow you to add video communications into your web application. A basic integration should take just a few minutes and give you working video call functionality with sensible layout and appearance. From there, you can customize appearance and behavior, and subscribe to events if you want deeper integration with your application.
Starting with a basic call
To get started, just include our SDK and then initialize a call. We need just an apiKey
, a callId
, and a container
. Here's a full working example, which you are encouraged to try out:
12345678910 <
div
id
=
"video-call"
></
div
>
<script>
VideoKit({
apiKey:
'YOUR_API_KEY'
,
callId:
'my-call-1293487'
,
container:
'#video-call'
});
</
script
>
1234567891011121314 import React, { useEffect, useRef } from
'react'
;
import VideoKit from
'videokit'
;
const App = () => {
const vk = VideoKit({
apiKey:
'YOUR_API_KEY'
,
callId:
'my-call-1293487'
,
});
const videoCallEl = useRef();
useEffect(() => vk.mount(videoCallEl.current));
return
(
<div ref={videoCallEl}></div>
)
}
12345678910111213 <
template
>
<
main
>
<
div
ref
=
"videoCall"
></
div
>
</
main
>
</
template
>
<
script
>
import VideoKit from
'videokit'
;
const vk = VideoKit({
apiKey:
'YOUR_API_KEY'
,
callId:
'my-call-1293487'
,
});
vk.mount(
this
.$refs.videoCall);
</
script
>
The callId
is an arbitrary identifier provided by you that is unique to the call. You make this up however it makes sense to your application, and then users joining with the same callId
will be in the same call. You don't need to register or initialize the call in any other way beforehand.
Using the npm module
The VideoKit client is also available as an npm module:
1 npm
install
videokit
Then use the module in your front end application:
123456789101112 <
div
id
=
"video-call"
></
div
>
<
script
>
import VideoKit from
'videokit'
;
const vk = VideoKit({
apiKey:
'YOUR_API_KEY'
,
callId:
'my-call-1293487'
});
vk.mount(document.querySelector(
'#video-call'
));
</
script
>
Participant user details
By default, users will appear as anonymous. In order to specify their name and avatar, send along those parameters from your front end application:
123456789 VideoKit({
apiKey:
'YOUR_API_KEY'
,
callId:
'my-call-1293487'
,
container:
'#video-call'
,
user: {
name:
'Pat Benetar'
,
}
})
Secured calls with JWT tokens
Tokens are JWT's signed by your private key, and allow you to specify verifiable user and call details not subject to tampering or spoofing.
Calls can be secured by creating a JWT token comprised of VideoKit parameters, signed with your private key. The token must include your apiKey
, callId
, and a user
object, and may contain all other VideoKit
parameters. The apiKey
must have a security level of token
configured in the admin interface for the given key.
12 VideoKit(token)
Generating tokens
You can either send POST requests to our back-end API, or else you can generate your own tokens in your back-end application.
12345 curl -XPOST https:
//videokit
.io
/api/token
\
-H
'Content-Type: application/json'
\
-H
'Authorization: Bearer <api_secret>'
\
-d '{
"apiKey"
:
"YOUR_API_KEY"
,
"callId"
:
"my-call-1293487"
,
"container"
:
"#video-call"
,
"user"
: {
"name"
:
"Pat Benetar"
} }'
123 HTTP
/1
.1 200
{
"token"
:
"eyJhbGciOiJIUzI1NiIsI..."
}
You can also generate tokens using a library such as jsonwebtoken
for node.js. For example, you can create a new JWT token the following way:
const jwt = require('jsonwebtoken');
const token = jwt.sign(
{ apiKey, callId, user },
privateKey,
{ algorithm: 'RS256' },
);
Customizing appearance
You can change the appearance of the video call interface by providing style
parameters. For ultimate flexibility, you may also wish to provide your own external stylesheet URL.
1234567891011 VideoKit({
apiKey:
'YOUR_API_KEY'
,
callId:
'my-call-1293487'
,
container:
'#video-call'
,
style: {
gap: 10,
positiveColor:
'#ff00ff'
,
negativeColor:
'#203090'
,
}
});
See more about style parameters in the Style Object reference below.
Listening to events
For a deeper integration, you may wish to listen to events and react from your consuming application. For example, when each user joins the call, you may want to flash a message of some sort. In that case you can listen for the peerJoined
event, and take whatever appropriate action.
123456789 const vk = VideoKit({
apiKey:
'YOUR_API_KEY'
,
callId:
'my-call-1293487'
,
container:
'#video-call'
})
vk.on(
'peerJoined'
, event => {
console.log(
"Peer joined the call"
, event)
})
See more about style parameters in the Events reference below.
Alternative iframe API
Under the covers, the JavaScript SDK generates an iframe and sets up the event pipeline with messages traveling through postMessage and event emitters. If you prefer, you can construct your own iframe and listen for your own events manually, without the JavaScript SDK.
1234 <
iframe
allow
=
"camera;microphone;fullscreen;speaker;display-capture"
/>
In this approach, set up your own iframe with a src
attribute pointing to https://frame.videokit.io
with query parameters matching arguments to the VideoKit()
initialization above. Specify objects' keys and values using conventional syntax in the form of user[avatar]=...
.
API Reference
VideoKit parameters
Initialize the JavaScript library in the browser with these parameters to VideoKit(params|token)
. Pass parameters either directly as an object with keys below, or else as a signed JWT token.
name | type | required? | description |
---|---|---|---|
apiKey |
string | required | Your API key. |
callId |
string | required | Arbitrary identifier provided by you that is unique to the call. You make this up however it makes sense to your application, and then users joining with the same callId will be in the same call. |
user |
object | optional | Specify details like name , avatar , and role for the user joining the call. More details below. This method is not secure in that it allows motivated users to spoof their own details. |
modules |
array | optional | Specify modules to include in the user interface. Modules available include actions and participants . |
style |
object | optional | Specify visual style attributes. |
User object
The user
object above has these optional properties.
name | type | required? | description |
---|---|---|---|
name |
string | optional | The name of the user joining the call. Displayed to other users in the call on their video feed. |
avatar |
string | optional | A URL to an image to be used as the user's avatar. |
role |
string | optional | Specify whether this user should be a host or participant |
startMuted |
boolean | optional | Start with the mic muted when joining the call. |
startPaused |
boolean | optional | Start with the camera paused when joining the call. |
Style object
The style
object above has these optional properties.
name | type | required? | description |
---|---|---|---|
streamGap |
string | optional | Pixel gap between video streams |
streamBorderRadius |
string | optional | Border radius on video streams |
baseColor |
string | optional | Default text color |
positiveColor |
string | optional | Selected / active color |
negativeColor |
string | optional | Muted / paused color |
Instance methods
vk.mute()
Mute the participant's outgoing audio stream.
vk.unmute()
Unmute the participant's outgoing audio stream.
vk.pause()
Pause the participant's outgoing video stream.
vk.resume()
Resume the participant's outgoing video stream.
vk.configure({ style, modules })
Reconfigure an instance with style
or modules
parameters.
vk.broadcast({ data })
Broadcast data to all participants in the call. On the receiving end, listen with vk.on('broadcast', ...)
vk.on(event, handler)
Listen to events and run a handler function. See more in the following section below.
Event reference
A VideoKit instance is an EventEmitter
, and uses node's event API (e.g. vk.on(event, data => {...})
)
event | data | description |
---|---|---|
muted |
{ peer } |
Local participant turned off their microphone. |
unmuted |
{ peer } |
Local participant turned on their microphone. |
paused |
{ peer } |
Local participant turned off their camera. |
resumed |
{ peer } |
Local participant turned on their camera. |
broadcast |
{ data } |
Custom application data was broadcast to everyone. |
joinCallAttempt |
{} |
An attempt to join the call is happening. |
joinCallError |
{ error } |
The joinCallAttempt failed. |
joinedCall |
{} |
The joinCallAttempt succeeded. |
leftCall |
{} |
Local particpant left the call. |
peerJoined |
{ peer } |
Another participant joined the call. |
peerLeft |
{ peer } |
Another participant left the call. |