Embedding into Your Website

You can now host the Digital Person as a widget on your website and interact with your Digital Person through that widget. All you would need to do is embed a code snippet into your website’s HTML code. This does not require any custom development and is the fastest way to integrate. The Digital Person displayed on the web page comes with a default styling in a square frame at the bottom right corner of the page with a configurable greeting text.

Key features:

Click-to-start functionality
Supports session persistence
Supports Content cards
Configurable greeting text, profile picture and position
Toggle between float mode to full frame mode
Advanced Customizations to change the colors, styles, and fonts

Widget Demo.mp4

User Interface Controls

The user can control the camera and microphone permissions whenever they want during the session using the icons within the widget. The camera and microphone options are both turned off when the widget loads, allowing you to select either or both. The browser would require you to grant microphone and/or camera permissions for an enhanced interactive experience with the Digital Person. Upon session time out, the widget returns to the initial state, where the profile picture and greeting message are displayed.

Communicating to a Digital Person requires you to grant microphone (audio-only connection) and/or camera (video connection) permissions the first time you interact with the Digital Person on the webpage

User Interface Controls

Controls	Descriptions
	Ends the interaction with the Digital Person.
	Indicates the microphone is currently muted. Click the button to unmute the microphone
	Indicates the microphone is active and unmuted. Click the button to mute the microphone.
	Indicates the camera is turned off.
	Indicates the microphone is turned off.
	Move to full-frame mode
	Move to floating mode
	Indicates the Digital Person is actively speaking
	Indicates the user is speaking
	When the audio indicator pulses, it indicates the Digital Person is listening via the microphone.
	Digital person is processing the request
	Can hear Digital Peson’s voice
	Digital person is muted

Obtaining code for your project

The code used to embed into the website is the same for every project, except for the API Key which you must provide separately.

To copy the code:

Go to the Digital DNA Studio dashboard and open the project.
Expand the Embed Code option on the Project Management page.
Copy the code or save it as a text file.

Authenticating the Widget

Replace the YOUR_API_KEY value with the web API key you generate for your project. See Connecting Using API Keys for details.

Upgrading the Widget

The code snippet SM_CONFIG includes the version of the widget as part of the src parameter. The version can be identified for troubleshooting purposes by observing the number included in the URL: “.../widget-snippet-1.8.0.min.js". Each time we release a new feature for the widget, the widget version is updated. Copy and re-embed the code snippet from your Digital DNA Studio project if you wish to utilize the latest features of the widget. For latest updates on the widget see, Digital DNA Studio Release Notes.

Customizing the Widget

The code snippet SM_CONFIG can be edited to include the below additional parameters to customize the experience. For customizing colors, styles, and fonts, see Advanced Customizations.

   <script
      src="https://static.soulmachines.com/widget-snippet-1.8.0.min.js"
      data-sm-api-key="'YOUR_API_KEY'"
      data-sm-position="bottomRight"
      data-sm-greeting="Welcome"
      data-sm-layout="fullFrame"
      data-sm-profile-picture="https://assets.cdn.soulmachines.cloud/AvatarCoverImages/image-sam-l.jpg"
    ></script>

Parameter	Required/Optional	Description
`data-sm-api-key`	required	This is the Web API Keys you generated for your project.
`data-sm-token-server`	alternative	This is the url for the custom JWT Token Server you’ve deployed for your project. If you wish to use the JWT token server instead of apiKey, you must delete the `data-sm-api-key` parameter. If both `data-sm-api-key` and `data-sm-token-server` are provided, the Web API Key will be used and the token server will be ignored. Example: `data-sm-token-server="https://my-token-server.com/api/jwt"`
`data-sm-profile-picture`	optional	URL of an image of the Digital Person in a publicly accessible location. Supports an image in jpg, gif, and png format.
`data-sm-greeting`	optional	This can be used to configure the greeting text displayed on the screen to encourage the users to interact with the Digital Person. The greeting cannot be turned off. If it is not configured then a default greeting is displayed: `Got any questions? I'm happy to help.`
`data-sm-position`	optional	The available positions are `bottomLeft` and `bottomRight` and the default is `bottomRight` (if not provided).
`data-sm-layout`	optional	Use the attribute `data-sm-layout="fullFrame"` in the code snippet to set the layout of the widget. Once connected, it will open into full frame mode, rather than floating mode. If not specified, the layout is defaulted to float mode. The user can switch between these modes during the interaction with the Digital Person.

Changing the Profile Picture

When the session starts, the image of the digital person is not displayed by default; you can work around this problem by using the data-sm-profile-picture parameter and displaying a static image or using a gif of the digital person.

default-profile-pic.mov

Default Profile Image

Download the image of the Digital Person you are using in the project by right-clicking the image under the “WHAT LOOK IS RIGHT FOR YOU?” section in Digital DNA Studio, and then click Save as Picture. (Or create a gif of the Digital Person)
Place the image/gif in a publicly accessible location, so that you can obtain its URL.
Enter the URL in the data-sm-profile-picture parameter in the code snippet.

Setting the widget to full-frame layout

There are two layout styles available for the widget: float mode and full-frame mode. Unless otherwise specified, the widget launches in the float mode by default. If you would like your Digital Person widget to launch full-frame, use the data-sm-layout="fullFrame" attribute in the code snippet. The user can switch between these layouts at anytime during the conversation using the expand icon at the top right-hand corner.
You can also enable voice commands for toggling the layout of the widget, see Configuring verbal commands.

Float Mode

Full-frame mode

The widget remains at the bottom of the screen, displayed within a small frame. However, the content cards appear on top of the Widget as a floating card, as shown below:

When switched to full-frame mode the widget expands to fill the entire webpage, displaying the content cards within the widget frame:

Embed it in your website

In general, the edited embed code needs to be added to the <head> tag in the HTML of the website. The embed code must be present on every page that you would want to embed the Digital Person on.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>SM Widget Example</title>
  <script src="https://static.soulmachines.com/widget-snippet.min.js" data-sm-greeting="Welcome" data-sm-api-key="YOUR_API_KEY"></script> 
</head>
<body></body>
</html>

Below are instructions for embedding the widget into popular website builders and hosting platforms:

Some of these website providers allow for a "global embed" functionality and this feature can be used to have the widget appear on every single page of the website.

Content Cards Support

The widget currently offers the following content card options for displaying rich content. See the section Displaying Content Cards to understand how to configure these content cards in your corpus. When configured, the cards appear on top of the Digital Person Widget as a floating card as shown below:

Options Card

Displays a clickable list of options:

Links Card

Displays a clickable link to an external website or internal webpage. The link card can optionally display an image and description. If not present in the data it will be hidden. The external link navigates the user to the external website in a new tab in the browser.

Image Card

Displays a remotely hosted image above the widget. We recommend using an image that is 350px by 350px.

Markdown Card

Displays styled markdown compatible content. The markdown card, once configured can be used to present content in plain text formatting (markdown) that gets converted to HTML content. A common use of the markdown card is to present a variety of different types of information together in one card and customize the card’s content.

Limitations

The Digital person image does not display before the session starts, a workaround for this is to use the data-sm-profile-picture parameter in the code snippet and display a static image or gif of the digital person
Greeting html element is not responsive when loaded on a mobile view

Supported browsers

PC- Chrome, Edge chromium, and Firefox
Mac- Chrome, Safari, and Firefox
Android - Chrome, and Firefox
iOS - Chrome, Safari, and Firefox

Consideration when embedding into social media apps

Embedding into the following social media applications is supported on iOS: Messenger, Facebook, Instagram, and LinkedIn
None of the social media applications are supported on Android

FAQs

Can I customize my web component widget?

In addition to changing the profile picture, greeting message, position, and layout of the digital person widget, you can also change the color schemes, font, and styles.

Is the widget always going to be on the bottom right corner of the website?

We have now provided a option to position the widget at the bottom right or bottom left using the data-sm-position parameter in the code snippet.

Does the widget work on mobile browsers?

Yes, the widget is designed to have a responsive view for both mobile and desktop browsers. However. the greeting message is not yet responsive for mobile devices. Currently, the mobile browser views are:

What human OS platform Digital People are supported by the widget?

The widget supports Digital People on any HumanOS platform, minus two features:

camera and mic decoupling functionality is only supported by Digital People that are Human OS2.0+
session persistence functionality is only supported by Digital People that are Human OS2.4+

Who has access to the Web Widget technology?

The Web Widget and corresponding embed code is available for all DDNA Studio users in their project summary or “deployment” screen of the individual project.

How can I get a different view of the Digital Person other than the head and shoulders view?

The widget by default comes with a head and shoulders view (default camera cuts) to the Digital Person. It also supports the Cinematic Camera Cuts which are automatically toggled based on the conversation.

Do I need to re-embed my code snippet from Studio, if I make any changes to my project?

No, any changes to the project within DDNA Studio should automatically reflect on the embedded widget as long as you “save” and “deploy” the project.

⚠ ⚠ If you have copy pasted the embed code before the July 11 release of the Web Widget (v1.5), you have to re-copy and paste the embed code to avail functionality on or after this release ⚠ ⚠

Do I need to understand the CMS or web platform requirements of my customer to see if they are eligible for the web widget?

The Web Widget is a Soul Machines javascript tool that encapsulates our SMWebSDK in a web component wrapper. This technology works for any website that allows for code injections, iframes or HTML code snippets to be added to them. In the modern day, this would encompass the majority of the websites developed today

Contents

Related Topics