konvolo-channel-widget

Konvolo Channel Widget

A React component that embeds a Konvolo Channel in your application.

Installation

npm install konvolo-channel-widget
# or
yarn add konvolo-channel-widget

Usage

Basic Usage

import KonvoloChannel from "konvolo-channel-widget";

function App() {
  return <KonvoloChannel cid="your-channel-id" theme="light" />;
}

Using KonvoloProvider (Recommended)

The KonvoloProvider provides a more flexible way to manage multiple channels and their states:

import { KonvoloProvider, useKonvolo } from "konvolo-channel-widget";

// Wrap your app with the provider
function App() {
  return (
    <KonvoloProvider
      initialChannels={{
        channel1: { cid: "your-channel-id", theme: "light" },
      }}
    >
      <YourApp />
    </KonvoloProvider>
  );
}

// Use the channels in your components
function YourComponent() {
  const { openChannel, closeChannel, addChannel } = useKonvolo();

  useEffect(() => {
    // Add a channel
    addChannel("my-channel", {
      cid: "your-channel-id",
      theme: "light",
    });
  }, []);

  return (
    <button onClick={() => openChannel("my-channel")}>Open Channel</button>
  );
}

Props

KonvoloChannel Props

Prop	Type	Default	Description
cid	string	required	The channel ID for your Konvolo Channel
theme	"light" | "dark"	"light"	The theme of the channel
width	string	"100%"	The width of the channel iframe
height	string	"100%"	The height of the channel iframe
style	React.CSSProperties	undefined	Additional CSS styles to apply to the iframe
small	boolean	false	Whether to display the channel in small mode. Sets to true by default if height is less than 600px
language	"sv" | "en" | "fi" | "no" | "da" | "de" | "es" | "fr" | "it"	navigator.language	The language of the channel.
onInterviewCompleted	() => void	undefined	Callback function when the interview is completed
onInterviewStarted	() => void	undefined	Callback function when the interview is started
onChannelLoaded	() => void	undefined	Callback function when the channel is loaded
metadata	Record<string, string>	undefined	Additional metadata to pass to the channel
email	string	undefined	Pre-fill the email field in the channel
firstAnswer	string	undefined	Pre-fill the first answer in the channel
test	boolean	false	If true, responses and insights will no be generated
showCloseButton	boolean	false	Whether to show the close button in the channel
showResetButton	boolean	false	Whether to show the reset button in the channel

KonvoloProvider Props

Prop	Type	Default	Description
children	ReactNode	required	The child components to render
initialChannels	Record<string, KonvoloChannelProps>	{}	Initial channels to be managed by the provider
modalStyle	React.CSSProperties	{}	Additional CSS styles to apply to the modal container

useKonvolo Hook

The useKonvolo hook provides the following methods:

Method	Parameters	Description
openChannel	(id: string) => void	Opens a channel with the specified ID
closeChannel	(id: string) => void	Closes a channel with the specified ID
updateChannelProps	(id: string, props: Partial) => void	Updates the props of a channel
addChannel	(id: string, props: KonvoloChannelProps) => void	Adds a new channel to be managed by the provider
removeChannel	(id: string) => void	Removes a channel from the provider
channels	Record<string, ChannelState>	Current state of all channels

Features

• Responsive iframe that adapts to your container
• Light and dark theme support
• Multiple language support
• Event callbacks for interview status
• Customizable styling
• Small mode for compact display
• Metadata support for additional information
• Email and first answer pre-filling
• Modal-based channel management with KonvoloProvider
• Multiple channel support
• Channel state management

Minimum Dimensions

The channel has minimum dimensions to ensure proper display:

• Minimum width: 300px
• Minimum height: 140px

Browser Support

The widget requires a modern browser that supports:

• React 16.8+
• ES6+
• Iframe communication

Security

The widget uses iframe communication and requires the following permissions for proper functionality:

• clipboard-write: For copying content from the channel
• microphone: Required if voice features are activated in the channel

Content Security Policy (CSP)

To properly integrate the Konvolo Channel widget, you need to configure your Content Security Policy to allow communication with the Konvolo portal. Add the following to your server's response headers:

const cspHeader = `
  default-src 'self';
  frame-src 'self' https://portal.konvolo.com;
  connect-src 'self' https://portal.konvolo.com;
  script-src 'self' 'unsafe-inline' 'unsafe-eval';
  style-src 'self' 'unsafe-inline';
  media-src 'self' https://portal.konvolo.com;
`;

response.headers.set("Content-Security-Policy", cspHeader);

Note: The media-src directive is added to allow microphone access through the iframe.

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy...