@viviedu/applet-sdk
    Preparing search index...

    Class ClientApplet<Msg, Params>

    An instance of ClientApplet, methods and attributes affect and refer to an applet running in the Vivi Client.

    Do not directly instantiate, instead use newApplet or newClientApplet.

    Type Parameters

    • Msg
    • Params extends BaseParams = never

    Hierarchy (View Summary)

    Index

    Properties

    adjustTimer cancelControl customParams downloadImage downloads exportToCloud getClientIp getClientStorage getClientTimerStatus getClientToken getClientVisibility getControlStatus getDisplayState getPlatformInfo getRoomDevices getRoomStudentLock getUserName getUserRoles grantControl hideTimer isBox isClient microphone navigateHome onScreenShareRequest openInBrowser pauseScreenShare pauseTimer requestControl resumeScreenShare revokeControl sendClientEvent setBadge setCaptions setClientStorage setClientViewMode setClientVisibility setTimerPosition shareScreen showTimer startScreenShare startTimer stop stopPlayContent stopScreenShare stopTimer toggleClientTimerControls

    Accessors

    _debug

    Methods

    listen send

    Properties

    adjustTimer:
        | (
            (
                ms: number,
            ) => Promise<
                UndefinedToOptional<
                    {
                        duration: number;
                        phase: "end"
                        | "low"
                        | "pause"
                        | "pause_low"
                        | "prestart"
                        | "start";
                        position: "bottom_right" | "top_left";
                        remaining_time: number;
                        timer_panel_visible: boolean | undefined;
                    },
                >,
            >
        )
        | null = null

    Requires Feature: client-timer-controls

    Adjusts the timer duration by the given number of milliseconds. Use positive values to add time, negative to subtract.

    Milliseconds to adjust by (positive or negative)

    The updated timer status

    cancelControl: ((deviceId?: string) => Promise<boolean>) | null = null

    Requires Feature: student-control

    Cancel a pending control request. If deviceId is provided, cancels that device's request (presenter only). If omitted, cancels the current device's own request.

    The device ID whose request to cancel

    true if the cancel request was sent successfully

    customParams: Params | undefined

    The params that were passed (custom_params) when starting the applet.

    downloadImage: ((dataUrl: string) => Promise<boolean>) | null = null

    Requires Feature: downloads-images

    Sends an image data URL payload to the client to be downloaded to disk.

    The data URL of the image to download

    true if the download was saved successfully, false otherwise

    downloads: boolean = false

    true if the applet can download content to the user's device

    exportToCloud:
        | (
            (
                dataUrl: string,
                destination: "google-drive" | "one-drive" | "one-note",
            ) => Promise<
                UndefinedToOptional<
                    {
                        failureReason: | "account-linking-cancelled"
                        | "error"
                        | "in-progress"
                        | "upload-cancelled"
                        | "";
                        message: string;
                        success: boolean;
                    },
                >,
            >
        )
        | null = null

    Requires Feature: cloud-exports

    Sends an image data URL payload to the client to be exported to a cloud destination.

    The data URL to export

    The cloud destination to export to:

    • 'google-drive': Export to Google Drive
    • 'one-drive': Export to OneDrive
    • 'one-note': Export to OneNote

    true if the export was initiated successfully, false otherwise

    getClientIp: (() => Promise<string>) | null = null

    Requires Feature: client-ip-discovery

    Returns the client's local IP address as seen by the box, using the box's /reflect endpoint. Useful when Safari's ICE candidate filtering prevents direct IP discovery.

    The client's IPv4 address

    getClientStorage: ((key: string, byUser?: boolean) => Promise<unknown>) | null = null

    Requires Feature: client-storage

    Retrieves a value from client-side storage by key.

    The storage key to retrieve

    If true, storage is scoped to the current user and applet

    The stored value, or undefined if not found

    getClientTimerStatus:
        | (
            () => Promise<
                UndefinedToOptional<
                    {
                        duration: number;
                        phase: "end"
                        | "low"
                        | "pause"
                        | "pause_low"
                        | "prestart"
                        | "start";
                        position: "bottom_right" | "top_left";
                        remaining_time: number;
                        timer_panel_visible: boolean | undefined;
                    },
                >,
            >
        )
        | null = null

    Requires Feature: client-timer-controls

    Queries the current timer status on the client, including phase, remaining time, and timer panel visibility.

    The current client timer status

    getClientToken: (() => Promise<string>) | null = null

    Requires Feature: client-token

    Returns the client authentication token

    The current client token

    getClientVisibility: (() => Promise<boolean>) | null = null

    Requires Feature: client-view-mode

    Query the client applet's current visibility.

    Whether the client applet content is currently visible

    getControlStatus:
        | (
            () => Promise<
                | UndefinedToOptional<
                    {
                        control_screens: number[];
                        in_control: boolean;
                        requesting_control: boolean;
                    },
                >
                | null,
            >
        )
        | null = null

    Requires Feature: student-control

    Query the current control status for this device. Useful on applet startup to reflect a pre-existing control grant before the first vivi:control-status-changed event fires.

    the current control status, including whether this device is in control, is requesting control, and which screens it controls

    getDisplayState:
        | (
            () => Promise<
                UndefinedToOptional<
                    {
                        displays: UndefinedToOptional<
                            {
                                device_id: string;
                                device_name: string
                                | undefined;
                                display_id: string;
                                frozen: boolean;
                                hibernating: boolean;
                                hidden: boolean;
                                is_local: boolean;
                                is_presenter: boolean;
                                kind: "play-content" | "stream" | undefined;
                                ready: boolean;
                                screens: number[];
                                source: "play-content" | "screen" | "camera";
                            },
                        >[];
                        is_presenter: boolean;
                        local_device_id: string;
                    },
                >,
            >
        )
        | null = null

    Requires Feature: display-state

    Query what the box is currently displaying in detail.

    The display state of the box

    getPlatformInfo:
        | (
            () => Promise<
                UndefinedToOptional<
                    {
                        hasMultipleMonitors: boolean
                        | "unknown_not_native";
                        hasTouch: boolean;
                        iosModel: string;
                        iosType: string;
                        isChrome: boolean;
                        isPortable: boolean;
                        isPwa: boolean;
                        isSafari: boolean;
                        locale: string;
                        orientation: string;
                        osVersion: number[];
                        osVersionFriendly: string;
                        platform: string;
                        pwaVisitorIsMobile: boolean;
                        screenHeight: number;
                        screenWidth: number;
                        subPlatform: string | null;
                        userAgent: string;
                        wrapper: string;
                    },
                >,
            >
        )
        | null = null

    Requires Feature: client-platform-info

    Query the platform information of the client device.

    The platform information

    getRoomDevices:
        | (
            () => Promise<
                UndefinedToOptional<
                    {
                        control_requested: boolean;
                        control_screens: number[];
                        device_id: string;
                        has_control: boolean;
                        is_presenter: boolean;
                        name: string;
                        platform: string;
                    },
                >[],
            >
        )
        | null = null

    Requires Features: student-control, user-roles-listing

    Query all devices connected to the room and their control status. Only populated for presenter devices.

    Array of room devices with control status

    getRoomStudentLock: (() => Promise<boolean>) | null = null

    Requires Feature: get-room-student-lock

    Query the student lock state of the room the applet is running in.

    true if the room's student lock is enabled, false otherwise

    getUserName: (() => Promise<string>) | null = null

    Requires Feature: client-user-name

    Returns the connected client's user name.

    The user name

    getUserRoles:
        | (
            () => Promise<
                UndefinedToOptional<{ admin: boolean; presenter: boolean }>,
            >
        )
        | null = null

    Requires Feature: user-role-listing

    Query all the roles the user has as a record. eg: { admin: false, presenter: true }

    The record of user roles

    grantControl: ((deviceId: string) => Promise<boolean>) | null = null

    Requires Feature: student-control

    Grant control of the display to a specific device. Presenter only.

    The device ID to grant control to

    true if the grant request was sent successfully

    hideTimer:
        | (
            () => Promise<
                UndefinedToOptional<
                    {
                        duration: number;
                        phase: "end"
                        | "low"
                        | "pause"
                        | "pause_low"
                        | "prestart"
                        | "start";
                        position: "bottom_right" | "top_left";
                        remaining_time: number;
                        timer_panel_visible: boolean | undefined;
                    },
                >,
            >
        )
        | null = null

    Requires Feature: client-timer-controls

    Hides the timer UI on the display without stopping the countdown.

    The updated timer status

    isBox: false = ...

    false for ClientApplet

    isClient: true = ...

    true for ClientApplet

    microphone: boolean = false

    true if the applet has the microphone feature and can access the user's microphone using regular browser APIs.

    navigateHome: (() => Promise<boolean>) | null = null

    Requires Feature: navigate-home

    Dismiss the applet overlay on the client without stopping the applet on the box. The user can re-enter by selecting the applet again.

    true if the navigate-home request was accepted

    onScreenShareRequest:
        | (
            (
                handler: (
                    request: ScreenShareRequest,
                ) => MaybePromise<ScreenShareResponse>,
            ) => () => void
        )
        | null = null

    Requires Feature: screen-share-intercept

    Register a handler to intercept screen share requests from the client. When a screen share is initiated, the client asks the applet if it wants to handle the request before proceeding with the default sharing flow.

    The handler must resolve within 3 seconds or the client will time out and proceed with default behavior.

    Async function that receives the request and returns { handled: true } to intercept (preventing default sharing) or { handled: false } to allow default behavior.

    A callback to unregister the handler

    const unsubscribe = applet.onScreenShareRequest(async (request) => {
      // request.streamSource: 'screen' | 'camera'
      // request.isHidden: boolean
      // request.isRestart: boolean
      return { handled: true };
    });
    openInBrowser: ((url: string) => Promise<boolean>) | null = null

    Requires Feature: open-in-browser

    Opens the given URL in the user's default browser.

    The URL to open

    true if the request was accepted

    pauseScreenShare: ((deviceId?: string) => Promise<boolean>) | null = null

    Requires Feature: screen-share-control

    Request the client to pause (freeze) a screen share.

    The device ID whose stream to pause. If omitted, pauses the local client's stream. If provided and different from the local client, requires presenter permissions.

    true if the pause request was accepted

    pauseTimer:
        | (
            () => Promise<
                UndefinedToOptional<
                    {
                        duration: number;
                        phase: "end"
                        | "low"
                        | "pause"
                        | "pause_low"
                        | "prestart"
                        | "start";
                        position: "bottom_right" | "top_left";
                        remaining_time: number;
                        timer_panel_visible: boolean | undefined;
                    },
                >,
            >
        )
        | null = null

    Requires Feature: client-timer-controls

    Pauses the timer countdown on the display.

    The updated timer status

    requestControl: (() => Promise<boolean>) | null = null

    Requires Feature: student-control

    Request control of the display for this device. Only available to non-presenter devices.

    true if the control request was sent successfully

    resumeScreenShare: ((deviceId?: string) => Promise<boolean>) | null = null

    Requires Feature: screen-share-control

    Request the client to resume (unfreeze) a paused screen share.

    The device ID whose stream to resume. If omitted, resumes the local client's stream. If provided and different from the local client, requires presenter permissions.

    true if the resume request was accepted

    revokeControl: (() => Promise<boolean>) | null = null

    Requires Feature: student-control

    Revoke control from the device that currently has it. Presenter only.

    true if the revoke request was sent successfully

    sendClientEvent: ((name: string, data: {}) => Promise<boolean>) | null = null

    Requires Feature: client-events

    Send an event associated with the client / user

    promise that resolves once event is sent

    setBadge:
        | (
            (
                badge?: UndefinedToOptional<{ color: string; icon: string }>,
            ) => Promise<boolean>
        )
        | null = null

    Requires Feature: client-badge

    Sets a badge on the applet's icon button in the room toolbar. Omit badge parameters or pass undefined to clear the badge.

    The badge to display, or omit to clear.

    true if the badge was set successfully

    setCaptions: ((captions: string[]) => Promise<boolean>) | null = null

    Requires Feature: client-captions

    Sets the captions on the client, which appear over all other content. Can also be used to clear the captions by passing an empty array.

    An array of strings, each being one line of captions.

    true if the captions were set

    setClientStorage:
        | ((key: string, value: unknown, byUser?: boolean) => Promise<boolean>)
        | null = null

    Requires Feature: client-storage

    Stores a key-value pair in client-side storage, scoped to the applet.

    The storage key

    The value to store

    If true, storage is scoped to the current user and applet

    { success: boolean } indicating whether the value was stored

    setClientViewMode:
        | (
            (
                mode:
                    | "normal"
                    | "primary-header-only"
                    | "secondary-header-only"
                    | "focused"
                    | "fullscreen",
            ) => Promise<boolean>
        )
        | null = null

    Requires Feature: client-view-mode

    Sets the view mode on the client.

    The view mode to set:

    • 'normal': Standard windowed mode with both headers visible
    • 'primary-header-only': Main header visible, secondary header hidden
    • 'secondary-header-only': Main header hidden, secondary header visible
    • 'focused': Both headers hidden, no OS fullscreen
    • 'fullscreen': Both headers hidden, OS fullscreen

    true if the view mode was set successfully

    setClientVisibility: ((visible: boolean) => Promise<boolean>) | null = null

    Requires Feature: client-view-mode

    Set the client applet's visibility.

    Whether the client applet content is visible

    The updated visibility state

    setTimerPosition:
        | (
            (
                position: "bottom_right" | "top_left",
            ) => Promise<
                UndefinedToOptional<
                    {
                        duration: number;
                        phase: "end"
                        | "low"
                        | "pause"
                        | "pause_low"
                        | "prestart"
                        | "start";
                        position: "bottom_right" | "top_left";
                        remaining_time: number;
                        timer_panel_visible: boolean | undefined;
                    },
                >,
            >
        )
        | null = null

    Requires Feature: client-timer-controls

    Sets the position of the timer overlay on the display.

    The desired timer position

    The updated timer status

    shareScreen: ((deviceId: string) => Promise<boolean>) | null = null

    Requires Feature: student-control

    Share a student's screen on the display. Presenter only. This revokes existing control before starting the stream.

    The device ID whose screen to share

    true if the share request was sent successfully

    showTimer:
        | (
            () => Promise<
                UndefinedToOptional<
                    {
                        duration: number;
                        phase: "end"
                        | "low"
                        | "pause"
                        | "pause_low"
                        | "prestart"
                        | "start";
                        position: "bottom_right" | "top_left";
                        remaining_time: number;
                        timer_panel_visible: boolean | undefined;
                    },
                >,
            >
        )
        | null = null

    Requires Feature: client-timer-controls

    Shows the timer UI on the display.

    The updated timer status

    startScreenShare:
        | (
            (
                options?: {
                    hidden?: boolean;
                    mute?: boolean;
                    screens?: number[];
                    source?: "screen" | "camera";
                },
            ) => Promise<boolean>
        )
        | null = null

    Requires Feature: screen-share-control

    Request the client to start a screen share.

    Optional screen share configuration

    If true, the share is started in hidden mode

    If true, the share is started muted

    The screens to share to

    The stream source:

    • 'screen': Share the device's screen
    • 'camera': Share the device's camera

    true if the start request was accepted

    startTimer:
        | (
            () => Promise<
                UndefinedToOptional<
                    {
                        duration: number;
                        phase: "end"
                        | "low"
                        | "pause"
                        | "pause_low"
                        | "prestart"
                        | "start";
                        position: "bottom_right" | "top_left";
                        remaining_time: number;
                        timer_panel_visible: boolean | undefined;
                    },
                >,
            >
        )
        | null = null

    Requires Feature: client-timer-controls

    Starts or resumes the timer countdown on the display.

    The updated timer status

    stop: (() => Promise<boolean>) | null = null

    Requires Feature: stop-client-applet

    Request the system to stop this applet.

    true if the stop request was accepted

    stopPlayContent: ((displayId?: string) => Promise<boolean>) | null = null

    Requires Feature: play-content-control

    Request the client to stop a play-content display (e.g. video, PDF).

    The display ID to stop. If omitted, stops the play-content display started by the local client. If provided and the display was started by a different client, requires presenter permissions.

    true if the stop request was accepted

    stopScreenShare: ((deviceId?: string) => Promise<boolean>) | null = null

    Requires Feature: screen-share-control

    Request the client to stop a screen share.

    The device ID whose stream to stop. If omitted, stops the local client's stream. If provided and different from the local client, requires presenter permissions.

    true if the stop request was accepted

    stopTimer:
        | (
            () => Promise<
                UndefinedToOptional<
                    {
                        duration: number;
                        phase: "end"
                        | "low"
                        | "pause"
                        | "pause_low"
                        | "prestart"
                        | "start";
                        position: "bottom_right" | "top_left";
                        remaining_time: number;
                        timer_panel_visible: boolean | undefined;
                    },
                >,
            >
        )
        | null = null

    Requires Feature: client-timer-controls

    Stops the timer on the display, resetting it and hiding the timer UI.

    The updated timer status

    toggleClientTimerControls: (() => Promise<boolean>) | null = null

    Requires Feature: client-timer-controls

    Toggles the visibility of the share screen timer controls on the client.

    true if the visibility was toggled

    Accessors

    _debug

    • get _debug(): { features: string[]; mode: "control" | "signage" }

      Properties exposed specifically for debugging purposes only

      Caution

      The contents, structure and existence of _debug are not stable, backwards-compatible or guaranteed. Do not use for business logic.

      Returns { features: string[]; mode: "control" | "signage" }

    Methods

    • Add a listener for any incoming messages sent from other applet instances.

      The message will be of type Msg that the user defines. (eg: Applet<Msg>)

      Parameters

      • listener: Listener<Msg>

        The listener function that will be called when a message is received.

      Returns () => void

      A callback to remove the listener

    • Send an message of type Msg to other applet instances.

      Will reject if the message was not successfully sent.

      Parameters

      • message: Msg

        The message to be sent

      Returns Promise<void>

    Settings

    Member Visibility

    On This Page

    Properties
    Accessors
    Methods