Using the Zoom Apps Layers API

The following information is applicable to Zoom Apps Layers API v1.5, and requires Zoom Client v5.10.6 or higher.

Configuring the Zoom Apps APIs

Include the Zoom Apps APIs needed for Layers in your app's zoomSdk.config call:

const configResponse = await zoomSdk.config({
  size: { width: 480, height: 360 },
  capabilities: [
    // The following are needed for Layers API.
    // Include any other capabilities your app needs here, too.
    `getRunningContext`
    `runRenderingContext`,
    `closeRenderingContext`,
    `drawParticipant`,
    `clearParticipant`,
    `drawImage`,
    `clearImage`,
    `drawWebView`,
    `clearWebview`,
    `postMessage`,
    `sendAppInvitationToAllParticipants`,
    `onMessage`,
    `onMyMediaChange`,
    `onRenderedAppOpened`
  ]
}

Setting the rendering context

Once the meeting is up and running, use the runRenderingContext method to set the rendering context:

zoomSdk.runRenderingContext({ view: viewMode });

The method spawns an additional Zoom app from the meeting sidebar in the main window or the individual participant window. The behavior is defined by the viewMode value.

Calling runRenderingContext() automatically changes the runningContext().

Options for viewMode

• immersive: Team Mode - canvas like environment.
• defaultCutout: available shapes (person, standard, rectangle, circle, square, verticalRectangle). Corners for all shapes are rounded (30px radius), except corners for the standard shape, which are squared.
• camera: Camera Mode - virtual camera device streaming from your Zoom App.

Team Mode (Person)

zoomSdk
    .runRenderingContext({
        view: "immersive",
        defaultCutout: "person",
    })
    .then((ctx) => {
        console.log("runRenderingContext returned", ctx);
    })
    .catch((e) => {
        console.log(e);
    });

Presentation Mode (rectangle)

zoomSdk
    .runRenderingContext({
        view: "immersive",
        defaultCutout: "rectangle",
    })
    .then((ctx) => {
        console.log("runRenderingContext returned", ctx);
    })
    .catch((e) => {
        console.log(e);
    });

Camera Mode

zoomSdk
    .drawParticipant({
        participantUUID: "xxx",
        x: 0,
        y: 0,
        width: x,
        height: y,
        zIndex: z,
    })
    .then((ctx) => {
        console.log("drawParticipant returned", ctx);
    })
    .catch((e) => {
        console.log(e);
    });

Constraints

Keep the following in mind when using the rendering context:

• Only a meeting host may set the rendering context to immersive.
• To transition other meeting participants to an immersive view, the meeting host's app instance must use the sendAppInvitationToAllParticipants API.
• Only one app instance can create an immersive rendering context at a time.
  • If another app instance attempts to call it, it fails and displays an error.
  • Camera Mode and Presentation mode can run at the same time.
• If the aomhost package needs to be downloaded, runRenderingContext returns a non-success result code.

Closing the rendering context

To close the child immersive app, use the closeRenderingContext method. This returns the app to the sidebar and sets the runningContext() to inMeeting.

zoomSdk.closeRenderingContext();

Usage example for all modes:

zoomSdk
    .closeRenderingContext()
    .then((ctx) => {
        console.log("closeRenderingContext returned", ctx);
    })
    .catch((e) => {
        console.log(e);
    });

What's the running context and why does it matter?

The getRunningContext() method provides information about the app's current mode.

Contexts relevant to layers:

• inMeeting: The app is running in the default right side panel.
• inImmersive: The app is running in an immersive mode (team or presentation mode). This mode occupies the main meeting canvas and affects the experience for all participants.
• inCamera: The app is running as a virtual camera device in Camera Mode, using off-screen rendering.

Usage example

zoomSdk
    .getRunningContext()
    .then((ctx) => {
        console.log("getRunningContext returned", ctx);
    })
    .catch((e) => {
        console.log(e);
    });