Developer

iFrame

Adding an Avatar iFrame to a Web Page

Trulience avatars can be embedded in a web page using an iFrame:

<iframe 
    height="600px"
    src="https://www.trulience.com/avatar/<your-avatar-id>"
    allow="camera; microphone; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
    allowfullscreen>
    frameborder="0" 
</iframe>

Here’s how this embed code looks in action:

Authentication

By default, newly created avatars are configured to use a default encryption key. This prevents abuse of your avatar by restricting who can access it.

The default Trulience encryption key won’t work when embedding your avatars elsewhere. We use this key to protect your avatars when they are accessed, for example by pressing the CONNECT button in the dashboard. You will need to adjust your avatars’ encryption setting in the ADVANCED tab to either:

• Set encryption to ‘None’ - this disables authentication entirely and allows anyone to access your avatar.
• Restrict access using your own encryption keys - you will need to implement backend code to generate corresponding JWT tokens.

If you wish to retain authentication on your site you will have to generate your own token and append it onto the iFrame’s src attribute like this:

<iframe src="https://www.trulience.com/avatar/<your-avatar-id>?token=<your-token>"></iframe>

Setting encryption to ‘None’ means you can omit the token from the URL.

Configuring the UI

You will notice that the avatar embed comes with some inbuilt UI. You can configure this UI by appending query parameters to the avatar URL or by editing your avatars’ client JSON configuration via the dashboard.

Configuration Parameters

The following parameters can be used to configure the behaviour of the iframe:

Adjusting Colour

Here’s a list of colour attributes you can adjust using CSS colour strings, e.g. #ffffff or pink:

• dialPageBackground
• dialButtonTextColor
• dialButtonBackground
• chatScreenBGColor
• userChatBubbleBGColor
• avatarChatBubbleBGColor
• userChatBubbleBorderColor
• avatarChatBubbleBorderColor
• userChatBubbleTextColor
• avatarChatBubbleTextColor
• inputBoxBGColor
• inputBoxBorderColor
• inputBoxTextColor
• sendButtonBGColor
• sendButtonArrowColor
• sendButtonBorderColor
• borderColorBetweenInputAndScreen
• overlayButtonColor
• loadingBarColor

Example

Here’s an example, demonstrating styling using query params:

<iframe 
    height="700px" 
    allow="camera; microphone; fullscreen" 
    src="https://www.trulience.com/avatar/<id>?chatScreenBGColor=#e7e7e7&userChatBubbleBGColor=#ff6200&avatarChatBubbleBGColor=#000000&userChatBubbleBorderColor=none&avatarChatBubbleBorderColor=none&userChatBubbleTextColor=white&avatarChatBubbleTextColor=white&inputBoxBGColor=#fff&inputBoxBorderColor=#fff&inputBoxTextColor=inherit&sendButtonBGColor=white&sendButtonArrowColor=#000000&sendButtonBorderColor=none&borderColorBetweenInputAndScreen=#f0f0f0" 
    frameborder="0"
    allow="camera; microphone; fullscreen; accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
    allowfullscreen>
</iframe>

iFrame messaging

Behind the scenes, the iFrame embed is loading the Trulience SDK. You can interact with the SDK through iFrame messaging.

Listening to SDK Events

You can register which SDK events you want to listen to by appending them to your iFrame’s src attribute via a query param, for example:

<iframe src="https://www.trulience.com/avatar/<id>?registerTrlEvents=auth-success,auth-fail,mic-update,speech-recognition-start,speech-recognition-end,speech-recognition-final-transcript" />

Extra iFrame Events

On top of the existing SDK events, the iframe also dispatches the following events:

Please refer to our SDK documentation to find out more about events like auth-success.

Example

You can listen to iFrame events like this:

window.addEventListener("message", (event) => {
    
    // Verify event.origin as necessary.
    if (event.origin) {
        // Test the origin here and return if it does not match the expected value.
    }

    if (event.data !== null && event.data !== undefined) {
        let eventData = event.data;
        console.log("Event name = " + eventData.name + " | Event parameters = " + eventData.params);
    }
}, false);

Sending Events

The iframe listens and reacts to the following events:

Example

You can define functions to send iFrame events like this:

const sendChatMessage = (message) => {
    const dataToSend = { "command" : "trl-chat", "message" : message};
    const iframe = document.getElementById('iframeId');
    iframe.contentWindow.postMessage(dataToSend, "*");
}