Embedded Expert Video
If you are integrating the video service into an existing application for your experts, you might want to include the expert side of the video call in your application for a seamless experience.
Prerequisites
Before trying to integrate an embedded expert video, make sure that you have requested an OAuth client for your application and have implemented the iframe authentication.
In addition to authentication, your application needs to be able to create new conversations via the API so that the embedded video has a conversation to join.
Embedding the expert video
Expert video controls can be embedded in your application via iframes. The URL
pattern for expert videos is
https://console.us.skillspring.com/embeddableVideo/:conversationId
. Make sure
to allow microphone and camera access when embedding. An example element for
embedding might look like this:
<iframe
title="Expert video controls"
src="https://console.us.skillspring.com/embeddableVideo/55a02455-d428-4a46-90fc-5c9d2a9c40bb"
allow="camera;microphone"
style="border-width: 0; flex: 1; width: 700px"
/>
Custom Colors
The expert video controls use a green color by default. To customize the color
palette, you can provide a primaryColor
query parameter in the iframe URL. The
value of primaryColor
should be an RGB or HEX value in the format
rgb(r, g, b)
or #RRGGBB
and should be URI encoded. The app will use the
provided color as the primary color in a generated palette (lighter or darker
shades may be used in different UI components for accessibility).
For example, to use #639
as a custom color, the URL of the iframe should be
https://console.us.skillspring.com/embeddableVideo/:conversationId?primaryColor=%23639
Hiding the conversation info
The expert video will show details of the conversation by default. The details include whether it was scheduled or realtime, if there is a screen-pop link, and an icon to represent whether the customer has joined or not. In some embedding scenarios, that information is already provided in the embedding context and can be left out of the expert video component.
The conversation info can be hidden with the hideConversationInfo
query
parameter. For example:
https://console.us.skillspring.com/embeddableVideo/:conversationId?hideConversationInfo=true
Watching for conversation events
When the conversation starts and ends, the embedded frame will send a message to the parent frame.
The parent frame can listen for the videoConnected
and/or videoHangup
messages and react to the conversation starting or ending.
For example, one could remove the embedded frame when the conversation is over with code like this:
window.addEventListener('message', function (event) {
if (
event.data.source === 'SkillSpring' &&
event.data.message === 'videoHangup'
) {
const conversationId = event.data.conversationId;
// Use the conversationId to update your application state and
// probably close the embedded frame now that the conversation is
// over
}
});
window.addEventListener('message', function (event) {
if (
event.data.source === 'SkillSpring' &&
event.data.message === 'videoConnected'
) {
const conversationId = event.data.conversationId;
// Conversation started
}
});
Full Screen and Full Window controls
In order to support full screen (true browser fullscreen) and full window (maximize the video in the window) features of the video controls, you must listen to requests to toggle the state, control the full screen (or full window), and respond to the frame to assert that the requested state toggle was performed.
Declaring support for screen size requests
Because the full screen and full window features require support from the parent frame when embedding, they will be disabled by default. The user will not see the size changing controls in their video experience unless you opt-in. If you would like to support the size changing features, you must add some query parameters to the embedding URL, depending on what you support. Here are some examples:
Supporting only the full screen behavior:
https://console.us.skillspring.com/embeddableVideo/:conversationId?enableFeature=fullscreen
Supporting both full screen and full window:
https://console.us.skillspring.com/embeddableVideo/:conversationId?enableFeature=fullscreen&enableFeature=fullwindow
Implementing screen size request handling
When the user requests to toggle the full screen state (entering or exiting), a
frame message for requestToggleFullScreen
will be sent. You can listen to this
message and initiate a full screen request on the iframe itself. We recommend
you use a fullscreen library to ensure all browser support is normalized, but
here is a native browser example:
const SKILLSPRING_CONSOLE_URL = 'https://console.us.skillspring.com';
// assume the value of 'iframe' is the iframe DOM element hosting the embedded video
const isFullScreen = () =>
!!(
document.fullscreenElement ||
document.mozFullScreenElement ||
document.webkitFullscreenElement
);
// any time the full screen state changes, notify the iframe
document.addEventListener('fullscreenchange', () => {
iframe.contentWindow.postMessage(
{
target: 'SkillSpring',
message: isFullScreen() ? 'startFullScreen' : 'stopFullScreen',
},
SKILLSPRING_CONSOLE_URL
);
});
window.addEventListener('message', function (event) {
if (
event.data.source === 'SkillSpring' &&
event.data.message === 'requestToggleFullScreen'
) {
if (isFullScreen()) {
document.exitFullscreen(); // be sure to catch errors
} else {
iframe.requestFullScreen(); // be sure to catch errors
}
}
});
The "full window" scenario is similar, but requires you to track the state and change styles on the iframe element appropriately:
/* suggested, not required */
iframe.full-window {
position: 'absolute';
height: '100%';
width: '100%';
}
const SKILLSPRING_CONSOLE_URL = 'https://console.us.skillspring.com';
let isFullWindow = false;
window.addEventListener('message', function (event) {
if (
event.data.source === 'SkillSpring' &&
event.data.message === 'requestToggleFullWindow'
) {
isFullWindow = !isFullWindow; // toggle the state
if (isFullWindow) {
iframe.classList.add('full-window');
iframe.contentWindow.postMessage(
{
target: 'SkillSpring',
message: 'startFullWindow',
},
SKILLSPRING_CONSOLE_URL
);
} else {
iframe.classList.remove('full-window');
iframe.contentWindow.postMessage(
{
target: 'SkillSpring',
message: 'stopFullWindow',
},
SKILLSPRING_CONSOLE_URL
);
}
}
});