🖼️ Integrating via iFrame

Embedding Pencil Spaces via iFrame allows you to incorporate all the power of Pencil Spaces into your application, without disrupting your existing user workflows.

This guide covers essential guidelines, permissions, user authentication options, and branding capabilities to help you embed Pencil Spaces correctly.

Permissions policies

To ensure a smooth and secure iFrame integration, ensure that you allow the following permissions in your iFrame permissions policy:

• camera / microphone: Enables video and audio access on your devices

• display-capture: Allows screen sharing

• clipboard-read / clipboard-write: Enables copying and pasting from the clipboard

• picture-in-picture: Supports picture-in-picture mode within the iFrame.

• autoplay: Allows for sound to play automatically if the user joins a Space but has not yet interacted with the page

• fullscreen: Allows users to expand Pencil Spaces in full screen.

• compute-pressure: Detects the performance level of a user’s device and adjusts resource-intensive processes accordingly. If the device is under strain, we automatically reduce load to keep the experience smooth.

Example

<iframe
  src="https://my.pencilapp.com/spaces/XYZ"
  width="100%"
  height="100%"
  allow="clipboard-read; clipboard-write; display-capture; fullscreen; autoplay; camera; microphone; picture-in-picture; compute-pressure">
</iframe>

Standalone mode

We offer a "Standalone Mode" option that can be enabled via Settings > API (live) or via URL param.

When this mode is active, we remove navigation links outside the Space, preventing users from accessing Spaces Manager. We also hide functions like "Copy Link" and "Invite Users," ensuring all user management is handled programmatically by your application.

User authentication

For streamlined SSO, Pencil Spaces provides API-managed authentication. This approach allows institutions to fully control user access programmatically.

To get started, you can use our /user/createAPIUser endpoint to create a new API user, and our /user/authorize endpoint to authorize an API user.

API users can be reused across multiple sessions for easier user management. Authentication tokens are valid for one hour and can be appended to the URL as shown below:

https://my.pencilapp.com/spaces/XYZ?loginMethod=token&loginType=api&token={token}

Customizations

We support the following customizations supplied as URL params:

• startCall=true - When set, we automatically launch the call if the user is a host in the Space. If the user is a participant, this parameter is ignored.

• gv=true - When set, the Space is defaulted to gallery view.

  • This will not override leader mode if leader mode is active in the Space.

  • If there is no call in the Space, the user will be automatically switched to gallery view after the call starts.

• standalone=true - When set, standalone mode is enabled a particular Space, overriding your institution’s default.

• language={code} - When set, the user interface is translated into the target language defined by code. Please provide language codes in ISO 639-1 format (e.g., fr for French). A full list of supported languages can be found in the language selector when you go to Settings > Profile > Languages.

• startLocalRecording=true - Automatically begins local recording when a user joins a call in their Space. Recording must be enabled to proceed with the call. Not supported on mobile devices (e.g., iPad) that do not allow browser-based recording.

• broadcastEvents=true - When set, in Space events are broadcast to the parent via postMessage. Learn more in the Embed events section below.

Embed events

We broadcast embed events from the iFrame to your host page via window.postMessage. This lets you observe key user actions (camera/mic toggles, screen share, presence changes, connection status, etc.) and wire them into your own analytics or UI.

To get started, add the broadcastEvents=true URL parameter when loading the Space in the iFrame. Events are dispatched as message events with a payload { type, detail }.

const VALID_ORIGINS = new Set([
'https://my.pencilapp.com',
'https://staging.pencilapp.com'
]);

window.addEventListener('message', (event) => {
  if (!PENCIL_ORIGINS.has(event.origin)) return; // security: origin check
  const data = event?.data;
  if (data && typeof data === 'object' && 'type' in data) {
    console.log('EmbedEvent:', data);
  }
});

We support the following event types

Branding and theming

Pencil Spaces offers a range branding and theming options to match your organization’s identity. These include custom logos, color schemes, and personalized UI.

You can customize branding from settings (see our help article here). If you require additional branding customizations, please contact your account manager.