Embedded Expert Video

If you are integrating SkillSpring 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
            );
        }
    }
});