> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talview.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Interfaces

The Proview SDK composed of the following modules:

* root: the global module that exposes initialization, global configuration, and other cross-cutting or non‑module-specific features.
* session: the module that manages proctored session lifecycle operations such as register, start, stop, and complete.

## Global Module:

### init

The Proview root module is added via a loader script or imported. Proview becomes usable only after initialization using `Proview.session.init(initOptions)`. The `options ` parameter is a configuration object .

**Function Type:** Synchronous<br />

<Tip>
  Only when the Proview root module is initialized, other features and modules are accessible.
</Tip>

```jsx theme={null}
function session.init(initOptions: InitOptions): void;
```

<AccordionGroup>
  <Accordion title="Init Options">
    | Attribute             | Type                    | Description                                                                                           | Default                                                                  |
    | --------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
    | dsn                   | `string`                | The DSN tells the SDK where to send the events. If this is not set, the SDK will not send any events. |                                                                          |
    | container\_id         | `string`                | The ID of the HTML element where the Proview SDK will be rendered.                                    |                                                                          |
    | session\_identifier\* | `string`                | Value that can identify the proctored session in the source platform.                                 |                                                                          |
    | attendee\*            | `Attendee`              | Attendee object containing candidate details. See [Attendee Attributes](#attendee-attributes).        |                                                                          |
    | workflow\_step\*      | `Workflow`              | Workflow object containing exam/workflow details. See [Workflow](#workflow).                          |                                                                          |
    | limit\_languages      | `[locale.languages]`\[] | This will limit language options for users to select from the supported list                          | All supported languages                                                  |
    | language              | `string`                | Explicitly set the SDK language                                                                       | Browser default if its not supported then fallback to English (`en-US`). |
  </Accordion>
</AccordionGroup>

### onError

Register a global error handler to receive notifications whenever the SDK encounters an error or warning. Proview supports only a single handler — registering a new handler replaces the previously registered one.

**Function Type:** Asynchronous\
**Input:** A function that receives an error object as parameter describing the problem and returns void. Any error in error handler will be logged in console but not be escalated.

```jsx theme={null}
function onError(errorHandler: ErrorObject): void;
```

<AccordionGroup>
  <Accordion title="Error Object">
    | Attribute        | Type                | Description                                                                                                                | Default |
    | ---------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------- |
    | code             | `string`            | This will identify predefined error by code. Ref Error Code section                                                        |         |
    | message          | `string`            | Message will contain reason for the error.                                                                                 |         |
    | type             | `enum`              | Error could be of type warning or critical. When critical error is raised it will impact core proctoring feature delivery. |         |
    | validationErrors | `validationError[]` |                                                                                                                            |         |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Example">
    ```jsx theme={null}
    <script>
      // Configure proviewOnLoad before adding the Loader Script
      window.proviewOnLoad = function () {
        Proview.session.init({
            dsn: "",
            session_identifier: "attempt_789",
            attendee: {
                identifier: "candidate_123",
            },
            workflow_step: {
                identifier: "exam_456",
            },
        });

        // Register an error handler
        Proview.onError((err)=>{
    		  // handle or log the error
          console.error('Proview error:', err);
          // e.g., send to your telemetry system
          // sendTelemetry('proview_error', err);
        });
      };
    </script>

    <script
      src="https://sdk.tlv.cx/session/init.js" async
      crossorigin="anonymous">
    </script>
    ```
  </Accordion>
</AccordionGroup>

### getLanguages

Get all supported language codes.
Language code in [BCP‑47](https://developer.mozilla.org/en-US/docs/Glossary/BCP_47_language_tag) format
(examples: "en", "en-US", "fr", "fr-CA"). The language subtag typically follows [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) (e.g., "en"), and the optional region subtag follows [ISO 3166-1 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) (e.g., "US").

**Function Type:** Synchronous

```jsx theme={null}
function getLanguages(): string[];
```

### setLanguage

Set the SDK’s language/locale used for localization (UI text, formatting hints, etc.).

Accepts a language tag in [BCP‑47](https://developer.mozilla.org/en-US/docs/Glossary/BCP_47_language_tag) format (examples: "en", "en-US", "fr", "fr-CA"). The language subtag typically follows [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) (e.g., "en"), and the optional region subtag follows [ISO 3166-1 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) (e.g., "US").

**Fallback rules**

* If the provided language tag is supported, the SDK applies it and returns the applied tag.
* If the provided dialect/region is not supported but the base language is, the SDK falls back to an available variant for that language (for example, "en-GB" → "en").
* If the provided language is not supported at all, the SDK attempts to fall back to the browser default locale (if available).
* If no suitable browser default is available, the SDK falls back to English ("en").
* The function updates the SDK’s language setting immediately and returns the effective language code.

**Function Type:** Synchronous\
**Input:** language code

```jsx theme={null}
function setLanguage(language: string): string;
```

<AccordionGroup>
  <Accordion title="Example">
    ```jsx theme={null}
    // Set French (generic)
    const applied = Proview.locale.setLanguage('fr');
    console.log('Language set to:', applied); // e.g. "fr"

    // Set English (United States)
    Proview.locale.setLanguage('en-US');

    // If unsupported, SDK falls back (browser default or 'en')
    const applied2 = Proview.locale.setLanguage('xx-YY');
    console.log(applied2); // e.g. "en" or browser default
    ```
  </Accordion>
</AccordionGroup>

[//]: # "### limitLanguages"

[//]: #

[//]: # "Limit which languages the SDK will offer or accept. Use this to restrict available languages to a specific subset required by your application."

[//]: #

[//]: # "- After calling this function, the SDK will only permit languages in the provided list. Any attempts to set or infer a language that is not in the allowed list will result in a fallback (for example, to the browser default or to a configured default)."

[//]: # "- Call this early (typically during initialization) to ensure the SDK does not briefly expose unsupported languages."

[//]: #

[//]: # "**Function Type:** Synchronous  "

[//]: # "**Input:** An array of language identifiers (either BCP‑47 strings like \"en-US\" / \"fr\" or constants from Proview.Constant.Language)."

[//]: #

[//]: #

[//]: # "```jsx"

[//]: # "function limitLanguages(languages: string[]): void;"

[//]: # "```"

[//]: #

[//]: # "<AccordionGroup>"

[//]: # "    <Accordion title=\"Example\">"

[//]: # "        ```jsx"

[//]: # "        Proview.locale.limitLanguages(['fr', 'en-us']);"

[//]: # "        ```"

[//]: # "    </Accordion>"

[//]: # "</AccordionGroup>"

### getAttendee

Retrieve current attendee attributes.

**Function Type:** Synchronous

```jsx theme={null}
function getAttendee(): Attendee | undefined ;
```

<AccordionGroup>
  <Accordion title="Attendee Attributes">
    | Attribute     | Type          | Description                                                                                                                 | Default                                                                                                                           |
    | ------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
    | identifier\*  | `string`      | unique user identifier from the source system. It will be the external id in the Talview platform.                          |                                                                                                                                   |
    | first\_name   | `string`      | First name of the attendee/candidate                                                                                        |                                                                                                                                   |
    | last\_name    | `string`      | Last name of the attendee/candidate                                                                                         |                                                                                                                                   |
    | middle\_name  | `string`      | Middle name of the attendee/candidate                                                                                       |                                                                                                                                   |
    | email         | `string`      | Email address of the attendee/candidate                                                                                     | If not passed then system will generate email based on identifier. e.g: [Att0001@dnd.talview.com](mailto:Att0001@dnd.talview.com) |
    | country\_code | `string (3)`  | [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements)                      |                                                                                                                                   |
    | country       | `string`      | Country code is passed then system will auto identify the country otherwise system will identify country code from country. |                                                                                                                                   |
    | phone         | `string (15)` | E164 format phone number of the attendee/candidate                                                                          |                                                                                                                                   |
    | id            | `int`         | Talview unique id generated for the course                                                                                  |                                                                                                                                   |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Example">
    ```jsx theme={null}
    // Get the current attendee information
    const attendee = Proview.getAttendee();

    if (attendee) {
        console.log('Attendee identifier:', attendee.identifier);
        console.log('Full name:', `${attendee.first_name} ${attendee.last_name}`);
        console.log('Email:', attendee.email);
        console.log('Country:', attendee.country);
        console.log('Phone:', attendee.phone);
    } else {
        console.log('No attendee information available');
    }
    ```
  </Accordion>
</AccordionGroup>

### getWorkflow

Retrieve the current workflow attributes used by the SDK.

* Call this after the Proview root module has been initialized and any workflow has been configured or loaded.
* If no workflow is set, the function may return null or undefined — handle that case in your code.

**Function Type:** Synchronous

```jsx theme={null}
function getWorkflow(): Workflow | undefined;
```

<AccordionGroup>
  <Accordion title="Workflow">
    | Attribute    | Type                | Description                                                                                                      | Default                                                            |
    | ------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
    | identifier\* | `string`            | Unique identifier for the exam from the calling application. It will be the external id in the Talview platform. |                                                                    |
    | name         | `string`            | Name of the exam                                                                                                 | If name is not passed then external id will be used.               |
    | flow\_id     | `int`               | This is the proctor session onboarding flow identifier.                                                          | if not passed then detail flow will be mapped based on project DSN |
    | duration     | `int`               | duration of the exam in min                                                                                      |                                                                    |
    | resource     | `[{string,string}]` | Array of key value pair to persist additional info related to exam.                                              |                                                                    |
    | course       | `[Course]`          |                                                                                                                  |                                                                    |
    | id           | `int`               | Talview unique id generated for the course                                                                       |                                                                    |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Example">
    ```jsx theme={null}
    // Get the current workflow information
    const workflow = Proview.getWorkflow();

    if (workflow) {
        console.log('Workflow identifier:', workflow.identifier);
        console.log('Workflow name:', workflow.name);
        console.log('Duration:', workflow.duration);
    } else {
        console.log('No workflow information available');
    }
    ```
  </Accordion>
</AccordionGroup>

### getLocale

Returns the SDK's current locale as an object with language, timezone, and currency. The timezone and currency fields are used only for scheduling- and payment-related features which will be supported in furture.

**Function Type:** Synchronous

```jsx theme={null}
function getLocale(): Locale
```

<AccordionGroup>
  <Accordion title="Locale">
    | Attribute    | Type     | Description                                                | Default               |
    | ------------ | -------- | ---------------------------------------------------------- | --------------------- |
    | language     | `string` | Language code in BCP-47 format (e.g., "en", "en-US", "fr") | based on browser info |
    | ~~currency~~ | `string` | ISO 4217 currency codes                                    | based on browser info |
    | ~~timezone~~ | `string` | Timezone                                                   | based on browser info |
  </Accordion>
</AccordionGroup>

### getVersion

Return the SDK's current version string. The SDK follows Semantic Versioning: Major,Minor,Patch. If you only need the version after initialization, call it after Proview\.session.init.

**Function Type:** Synchronous
**Output:** string (Semantic Versioning, e.g. "1.2.3").

```jsx theme={null}
function getVersion(): String ;
```

## Session Module

### getState

Return the current state of the proctoring session.

**Function Type:** Synchronous

```jsx theme={null}
function getState(): SessionState ;
```

<AccordionGroup>
  <Accordion title="SessionState">
    Its of type enum which contains following values.

    * `init`
    * `registered`
    * `running`
    * `paused`
    * `suspended`
    * `terminated`
    * `stopped`
    * `completed`
  </Accordion>
</AccordionGroup>

### register

Register attendee and workflow with the backend.You can optionally call register beforehand to optimize the workflow and improve overall process performance.

**Function Type:** Asynchronous

```jsx theme={null}
function register(callback: (sessionOutput: SessionOutput | null, err: Error | null) => void): void;
```

<AccordionGroup>
  <Accordion title="SessionOutput">
    | Attribute      | Type             | Description                                                                                                   | Default                                                                                                                           |
    | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
    | uuid           | `GUID`           | Reference Talview identifier for client application to track.                                                 |                                                                                                                                   |
    | state          | `session.states` | Current state of the session (init, registered, running, paused, suspended, terminated, stopped, completed)   |                                                                                                                                   |
    | attendee       | `Attendee`       | Object containing attendee information                                                                        |                                                                                                                                   |
    | workflow\_step | `Workflow`       | Object containing workflow information                                                                        | If not passed then system will generate email based on identifier. e.g: [Att0001@dnd.talview.com](mailto:Att0001@dnd.talview.com) |
    | identifier     | `string`         | unique session identifier from the source system. It will be the session external id in the Talview platform. |                                                                                                                                   |
  </Accordion>
</AccordionGroup>

[//]: # "### registerHook"

[//]: #

[//]: # "Register an event listener for specific session events. This allows you to execute custom code when certain session state changes or events occur during the proctoring workflow."

[//]: #

[//]: # "**Function Type:** Synchronous"

[//]: #

[//]: # "**Input:**"

[//]: # "- hookType: The type of hook to register (e.g., `Proview.Hooks.onRegister`, `Proview.Hooks.onSessionStateChange`)"

[//]: #

[//]: # "```jsx"

[//]: # "function registerHook(hookType: HookType, callback: Function): void;"

[//]: # "```"

[//]: # "<AccordionGroup>"

[//]: # "    <Accordion title=\"Example\">"

[//]: #

[//]: # "     ```jsx"

[//]: # "    try {"

[//]: # "    Proview.session.registerHook(Proview.Hooks.onSessionPause, function (sessionStateOutput) {"

[//]: # "        console.log('Session paused. Reason:', sessionStateOutput.reason);"

[//]: # "        console.log('Session state:', sessionStateOutput.state);"

[//]: # "    });"

[//]: # "    }"

[//]: # "    catch (error) {"

[//]: # "        console.error('Failed to register hooks:', error);"

[//]: # "    }"

[//]: # "        ```"

[//]: #

[//]: # "    </Accordion>"

[//]: # "</AccordionGroup>"

### start

Begin the proctoring session for the configured attendee and workflow. This starts whatever proctoring mode was requested (for example, recorded or live).

* The Proview root module must be initialized.
* Either an attendee (or attendee identifier) and workflow (or workflow identifier) must be set or the session must already be in registered state. If required identifiers are missing, the call will fail.
* If `register` is not called beforehand, it will be executed as part of the start process.

**Function Type:** Asynchronous

[//]: # "**Error / Warning Codes:**"

[//]: #

[//]: # "- PV/Common/Err0001 - Unable to connect to server, Could be internet connection or network block (restricted office environment)."

[//]: # "- PV/Validation/Err00001 - Missing Required field"

[//]: # "- PV/Validation/Err00002 - Invalid type"

```jsx theme={null}
function start(): Promise<SessionOutput>;
                            //or
function start(callback: (sessionOutput: SessionOutput, error: Error) => void): void;
```

<AccordionGroup>
  <Accordion title="SessionOutput">
    | Attribute      | Type             | Description                                                                                                   | Default                                                                                                                           |
    | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
    | uuid           | `GUID`           | Reference Talview identifier for client application to track.                                                 |                                                                                                                                   |
    | state          | `session.states` | Current state of the session (init, registered, running, paused, suspended, terminated, stopped, completed)   |                                                                                                                                   |
    | attendee       | `Attendee`       | Object containing attendee information                                                                        |                                                                                                                                   |
    | workflow\_step | `Workflow`       | Object containing workflow information                                                                        | If not passed then system will generate email based on identifier. e.g: [Att0001@dnd.talview.com](mailto:Att0001@dnd.talview.com) |
    | identifier     | `string`         | unique session identifier from the source system. It will be the session external id in the Talview platform. |                                                                                                                                   |
  </Accordion>
</AccordionGroup>

[//]: # "<AccordionGroup>"

[//]: # "    <Accordion title=\"SessionOptions\">"

[//]: # "        | Attribute | Type | Description | Default |"

[//]: # "        | --- | --- | --- | --- |"

[//]: # "        | attendee_identifier | `string` | Value that can identify the user in the source platform. |  |"

[//]: # "        | workflow_identifier | `string` | Value that can identify the exam in the source platform.  |  |"

[//]: # "        | session_identifier | `string` | Value that can identify the proctored session in the source platform. If not passed will use workflow_identifier as default. |  |"

[//]: # "        | type | `string` | The type of the Proctored Session |  |"

[//]: # "        | durtion | `number` | Total allotted time (In minutes) for the proctored session. . |  |"

[//]: # "        | remaining_duration | `number` |  Remaining time for(In minutes) the ongoing proctored session. |  |"

[//]: # "    </Accordion>"

[//]: # "</AccordionGroup>"

<AccordionGroup>
  <Accordion title="Error">
    | Attribute        | Type                | Description                                                                                                                | Default |
    | ---------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------- |
    | code             | `string`            | This will identify predefined error by code. Ref Error Code section                                                        |         |
    | message          | `string`            | Message will contain reason for the error.                                                                                 |         |
    | type             | `enum`              | Error could be of type warning or critical. When critical error is raised it will impact core proctoring feature delivery. |         |
    | validationErrors | `validationError[]` |                                                                                                                            |         |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Example">
    ```jsx theme={null}
    Proview.session.start((sessionOutput, err)=>{
    if (err) {
        console.error('Failed to start session:', err);
        return;
    }
        console.log('Session state:', sessionOutput.state);
        console.log('Session uuid:', sessionOutput.uuid);
    });

    // or
    try
    {
        const sessionOutput = await Proview.session.start();
    } catch (err) {
    console.error('Failed to start session:', err);
    }
    ```
  </Accordion>
</AccordionGroup>

### stop

Stop the currently active proctoring session. If no session is active, the call will fail with an error.

* Attempts to stop the active session on the server and update the SDK’s session state ("stopped").
* If no session is currently active, the call rejects or returns an error indicating that there is no session to stop.
* Perform any necessary cleanup or finalization needed (stop recording, flush artifacts, etc.) as part of stopping the session.

**Function Type:** Asynchronous

```jsx theme={null}
function stop(): Promise<SessionOutput>;
            //or
function stop(callback: (sessionOutput: SessionOutput | null, err: Error | null) => void): void;
```

[//]: # "**Error / Warning Codes:**"

[//]: #

[//]: # "- PV/Common/Err00002 - Operation not allowed. In this case stop is not support since the session is not running."

<AccordionGroup>
  <Accordion title="SessionOutput">
    | Attribute      | Type             | Description                                                                                                   | Default                                                                                                                           |
    | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
    | uuid           | `GUID`           | Reference Talview identifier for client application to track.                                                 |                                                                                                                                   |
    | state          | `session.states` | Current state of the session (init, registered, running, paused, suspended, terminated, stopped, completed)   |                                                                                                                                   |
    | attendee       | `Attendee`       | Object containing attendee information                                                                        |                                                                                                                                   |
    | workflow\_step | `Workflow`       | Object containing workflow information                                                                        | If not passed then system will generate email based on identifier. e.g: [Att0001@dnd.talview.com](mailto:Att0001@dnd.talview.com) |
    | identifier     | `string`         | unique session identifier from the source system. It will be the session external id in the Talview platform. |                                                                                                                                   |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Error">
    | Attribute        | Type                | Description                                                                                                                | Default |
    | ---------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------- |
    | code             | `string`            | This will identify predefined error by code. Ref Error Code section                                                        |         |
    | message          | `string`            | Message will contain reason for the error.                                                                                 |         |
    | type             | `enum`              | Error could be of type warning or critical. When critical error is raised it will impact core proctoring feature delivery. |         |
    | validationErrors | `validationError[]` |                                                                                                                            |         |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Example">
    ```jsx theme={null}
    Proview.session.stop((sessionOutput, err) => {
    if (err) {
        console.error('Failed to stop session:', err);
        return;
    }
        console.log('Session state:', sessionOutput.state);
    });

    // or

    try {
        const sessionOutput = await Proview.session.stop();
        console.log('Session state:', sessionOutput.state);
    } catch (err) {
    console.error('Failed to stop session:', err);
    }
    ```
  </Accordion>
</AccordionGroup>

### complete

Mark the current proctoring session as completed. Completion is an end state — Session that are not in end state can be marked as completed, completed sessions cannot be restarted or resumed for proctoring

* Transitions the session to the "completed" state on the server and updates the SDK state locally.
* Once completed, the session is final and cannot be started or resumed.
  * If the session is scheduled then it will be auto completed at the session end time + buffer time
* The call should be idempotent: repeated attempts to complete an already-completed session should either succeed silently.
* Perform any finalization needed (e.g., flush pending artifacts, stop recordings) before calling complete to ensure all data is preserved and release device connection and access.

**Function Type:** Asynchronous

```jsx theme={null}
function complete(callback:(sessionOutput: SessionOutput | null, err: Error | null) => void): void;
```

<AccordionGroup>
  <Accordion title="SessionOutput">
    | Attribute      | Type             | Description                                                                                                   | Default                                                                                                                           |
    | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
    | uuid           | `GUID`           | Reference Talview identifier for client application to track.                                                 |                                                                                                                                   |
    | state          | `session.states` | Current state of the session (init, registered, running, paused, suspended, terminated, stopped, completed)   |                                                                                                                                   |
    | attendee       | `Attendee`       | Object containing attendee information                                                                        |                                                                                                                                   |
    | workflow\_step | `Workflow`       | Object containing workflow information                                                                        | If not passed then system will generate email based on identifier. e.g: [Att0001@dnd.talview.com](mailto:Att0001@dnd.talview.com) |
    | identifier     | `string`         | unique session identifier from the source system. It will be the session external id in the Talview platform. |                                                                                                                                   |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Error">
    | Attribute        | Type                | Description                                                                                                                | Default |
    | ---------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------- |
    | code             | `string`            | This will identify predefined error by code. Ref Error Code section                                                        |         |
    | message          | `string`            | Message will contain reason for the error.                                                                                 |         |
    | type             | `enum`              | Error could be of type warning or critical. When critical error is raised it will impact core proctoring feature delivery. |         |
    | validationErrors | `validationError[]` |                                                                                                                            |         |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Example">
    ```jsx theme={null}
    Proview.session.complete((sessionOutput, err) => {
      if (err) {
        console.error('Failed to complete session:', err);
        return;
      }
      console.log('Session state:', sessionOutput.state);
    });

    // or

    try {
      const sessionOutput = await Proview.session.complete({
        score: 87,
        finishedAt: new Date().toISOString()
      });
      console.log('Session state:', sessionOutput.state); // "completed"
    } catch (err) {
      console.error('Failed to complete session:', err);
    }
    ```
  </Accordion>
</AccordionGroup>

### pause

This will allow application to pause running proctored session.

**Function Type:** Asynchronous

**Input:** reason a string value, Void function that takes Session State, uuid (Proview session unique ID) and Error as parameter.

```jsx theme={null}
function pause(reason: string, callback: (output: sessionStateOutput, err: Error | null) => void): void;
```

<AccordionGroup>
  <Accordion title="Session State Output">
    ```jsx theme={null}
    SessionStateOutput = {
    state: Session State
    reason: string
    }

    ```

    Session State is of type enum which contains following values.

    * `init`
    * `registered`
    * `running`
    * `paused`
    * `suspended`
    * `terminated`
    * `stopped`
    * `completed`
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Example">
    ```jsx theme={null}
    // Pause the current proctoring session
    Proview.session.pause("User requested break", (sessionStateOutput, err) => {
    if (err) {
    console.error('Failed to pause session:', err);
    return;
    }
    console.log('Session paused:', sessionStateOutput.state); // "paused"
    });
    ```
  </Accordion>
</AccordionGroup>

### resume

This will allow application to resume a paused proctored session.

**Function Type:** Asynchronous

**Input:** reason a string value, Void function that takes Session State Output, uuid (Proview session unique ID) and Error as parameter.

```jsx theme={null}
function resume(reason: string, callback: (output: sessionStateOutput, err: Error | null) => void): void;
```

<AccordionGroup>
  <Accordion title="Session State Output">
    ```jsx theme={null}
    SessionStateOutput = {
    state: Session State
    reason: string
    }

    ```

    Session State is of type enum which contains following values.

    * `init`
    * `registered`
    * `running`
    * `paused`
    * `suspended`
    * `terminated`
    * `stopped`
    * `completed`
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Example">
    **Client Usage (Function):**

    ```jsx theme={null}
    // Promise-based
    try {
    const sessionOutput = await Proview.session.resume("Break time over");
    console.log('Session resumed:', sessionOutput.state);
    } catch (err) {
    console.error('Failed to resume session:', err);
    }

    // Callback-based
    Proview.session.resume("Break time over", (sessionStateOutput, err) => {
    if (err) {
    console.error('Failed to resume session:', err);
    return;
    }
    console.log('Session resumed:', sessionStateOutput.state);
    });
    ```
  </Accordion>
</AccordionGroup>

[//]: # "### suspend"

[//]: #

[//]: # "This will allow application to suspend a started session that is not completed/terminated."

[//]: #

[//]: # "**Function Type:** Asynchronous"

[//]: #

[//]: # "**Input:** reason a string value, Void function that takes Session State Output, uuid (Proview session unique ID) and Error as parameter."

[//]: #

[//]: # "```jsx"

[//]: # "function suspend(reason: string, callback: (output: sessionStateOutput, err: Error | null) => void): void;"

[//]: # "```"

[//]: #

[//]: # "<AccordionGroup>"

[//]: # "    <Accordion title=\"Session State Output\">"

[//]: #

[//]: # "        ```jsx"

[//]: # "        SessionStateOutput = {"

[//]: # "        state: Session State"

[//]: # "        reason: string"

[//]: # "    }"

[//]: #

[//]: # "        ```"

[//]: # "        Session State is of type enum which contains following values."

[//]: #

[//]: # "        - `init`"

[//]: # "        - `registered`"

[//]: # "        - `running`"

[//]: # "        - `paused`"

[//]: # "        - `suspended`"

[//]: # "        - `terminated`"

[//]: # "        - `stopped`"

[//]: # "        - `completed`"

[//]: #

[//]: # "    </Accordion>"

[//]: # "</AccordionGroup>"

[//]: #

[//]: # "<AccordionGroup>"

[//]: # "    <Accordion title=\"Example\">"

[//]: #

[//]: # "        **Client Usage (Function):**"

[//]: # "        ```jsx"

[//]: # "        // Promise-based"

[//]: # "        try {"

[//]: # "        const sessionOutput = await Proview.session.suspend(\"Violation detected\");"

[//]: # "        console.log('Session suspended:', sessionOutput.state);"

[//]: # "    } catch (err) {"

[//]: # "        console.error('Failed to suspend session:', err);"

[//]: # "    }"

[//]: #

[//]: # "        // Callback-based"

[//]: # "        Proview.session.suspend(\"Violation detected\", (sessionStateOutput, err) => {"

[//]: # "        if (err) {"

[//]: # "        console.error('Failed to suspend session:', err);"

[//]: # "        return;"

[//]: # "    }"

[//]: # "        console.log('Session suspended:', sessionStateOutput.state);"

[//]: # "    });"

[//]: # "        ```"

[//]: #

[//]: # "    </Accordion>"

[//]: # "</AccordionGroup>"

[//]: #

[//]: # "### terminate"

[//]: #

[//]: # "This will allow application to suspend a started session that is not completed."

[//]: #

[//]: # "**Function Type:** Asynchronous"

[//]: #

[//]: # "**Input:** reason a string value, Void function that takes Session State Output, uuid (Proview session unique ID) and Error as parameter."

[//]: #

[//]: # "```jsx"

[//]: # "function terminate(reason: string, callback: (output: sessionStateOutput, err: Error | null) => void): void;"

[//]: # "```"

[//]: #

[//]: # "<AccordionGroup>"

[//]: # "    <Accordion title=\"Session State Output\">"

[//]: #

[//]: # "        ```jsx"

[//]: # "        SessionStateOutput = {"

[//]: # "        state: Session State"

[//]: # "        reason: string"

[//]: # "    }"

[//]: #

[//]: # "        ```"

[//]: # "        Session State is of type enum which contains following values."

[//]: #

[//]: # "        - `init`"

[//]: # "        - `registered`"

[//]: # "        - `running`"

[//]: # "        - `paused`"

[//]: # "        - `suspended`"

[//]: # "        - `terminated`"

[//]: # "        - `stopped`"

[//]: # "        - `completed`"

[//]: #

[//]: # "    </Accordion>"

[//]: # "</AccordionGroup>"

# Session Hooks

Session hooks allow you to register event listeners that get triggered when specific session state changes occur. Use the simple `Proview.session.on()` syntax to listen for events.

```jsx theme={null}
Proview.session.on(eventName, callback);
```

### Pause

Triggered when a proctoring session is paused.

```jsx theme={null}
Proview.session.on('Pause', (sessionStateOutput) => {
  // Handle session pause
});
```

<AccordionGroup>
  <Accordion title="Example">
    ```jsx theme={null}
    Proview.session.on('Pause', (sessionStateOutput) => {
    console.log('Session paused:', sessionStateOutput.state);
    console.log('Pause reason:', sessionStateOutput.reason);
    });
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Session State Output">
    ```jsx theme={null}
    SessionStateOutput = {
    state: SessionState,
    reason: string
    }
    ```

    **SessionState** enum values:

    * `init` - Session initialized
    * `registered` - Session registered
    * `running` - Session actively running
    * `paused` - Session paused
    * `suspended` - Session suspended
    * `terminated` - Session terminated
    * `stopped` - Session stopped
    * `completed` - Session completed
  </Accordion>
</AccordionGroup>

### Resume

Triggered when a paused proctoring session is resumed.

```jsx theme={null}
Proview.session.on('Resume', (sessionStateOutput) => {
  // Handle session resume
});
```

<AccordionGroup>
  <Accordion title="Example">
    ```jsx theme={null}
    Proview.session.on('Resume', (sessionStateOutput) => {
    console.log('Session resumed:', sessionStateOutput.state);
    console.log('Resume reason:', sessionStateOutput.reason);
    });
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Session State Output">
    ```jsx theme={null}
    SessionStateOutput = {
    state: SessionState,
    reason: string
    }
    ```

    **SessionState** enum values:

    * `init` - Session initialized
    * `registered` - Session registered
    * `running` - Session actively running
    * `paused` - Session paused
    * `suspended` - Session suspended
    * `terminated` - Session terminated
    * `stopped` - Session stopped
    * `completed` - Session completed
  </Accordion>
</AccordionGroup>

### Suspend

Triggered when a proctoring session is suspended due to violations or technical issues.

```jsx theme={null}
Proview.session.on('Suspend', (sessionStateOutput) => {
  // Handle session suspension
});
```

<AccordionGroup>
  <Accordion title="Example">
    ```jsx theme={null}
    Proview.session.on('Suspend', (sessionStateOutput) => {
    console.log('Session suspended:', sessionStateOutput.state);
    console.log('Suspension reason:', sessionStateOutput.reason);
    });
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Session State Output">
    ```jsx theme={null}
    SessionStateOutput = {
    state: SessionState,
    reason: string
    }
    ```

    **SessionState** enum values:

    * `init` - Session initialized
    * `registered` - Session registered
    * `running` - Session actively running
    * `paused` - Session paused
    * `suspended` - Session suspended
    * `terminated` - Session terminated
    * `stopped` - Session stopped
    * `completed` - Session completed
  </Accordion>
</AccordionGroup>

### Terminate

Triggered when a proctoring session is terminated.

```jsx theme={null}
Proview.session.on('Terminate', (sessionStateOutput) => {
  // Handle session termination
});
```

<AccordionGroup>
  <Accordion title="Example">
    ```jsx theme={null}
    Proview.session.on('Terminate', (sessionStateOutput) => {
    console.log('Session terminated:', sessionStateOutput.state);
    console.log('Termination reason:', sessionStateOutput.reason);
    });
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Session State Output">
    ```jsx theme={null}
    SessionStateOutput = {
    state: SessionState,
    reason: string
    }
    ```

    **SessionState** enum values:

    * `init` - Session initialized
    * `registered` - Session registered
    * `running` - Session actively running
    * `paused` - Session paused
    * `suspended` - Session suspended
    * `terminated` - Session terminated
    * `stopped` - Session stopped
    * `completed` - Session completed
  </Accordion>
</AccordionGroup>

### StateChange

Triggered whenever the session state changes.

```jsx theme={null}
Proview.session.on('StateChange', (sessionStateOutput) => {
  // Handle any state change
});
```

<AccordionGroup>
  <Accordion title="Example">
    ```jsx theme={null}
    Proview.session.on('StateChange', (sessionStateOutput) => {
    console.log('Session state changed:', sessionStateOutput.state);
    console.log('State change reason:', sessionStateOutput.reason);
    });
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Session State Output">
    ```jsx theme={null}
    SessionStateOutput = {
    state: SessionState,
    reason: string
    }
    ```

    **SessionState** enum values:

    * `init` - Session initialized
    * `registered` - Session registered
    * `running` - Session actively running
    * `paused` - Session paused
    * `suspended` - Session suspended
    * `terminated` - Session terminated
    * `stopped` - Session stopped
    * `completed` - Session completed
  </Accordion>
</AccordionGroup>

### NetworkStatusChanged

Use this hook to react whenever the candidate's device goes offline or comes back online. The payload includes the normalized network status, so you can surface diagnostics or pause downstream uploads.

```jsx theme={null}
Proview.session.on('NetworkStatusChanged', ({ status }) => {
  if (status === 'offline') {
    console.warn('Network connectivity lost — show retry UI');
  } else {
    console.log('Network restored, resume streaming');
  }
});
```

<AccordionGroup>
  <Accordion title="Payload">
    ```ts theme={null}
    type NetworkStatusPayload = {
      status: 'online' | 'offline';
    };
    ```

    * Emitted on every browser online/offline transition detected by Proview.
    * Invalid or missing payloads automatically normalize to `{ status: 'offline' }`.
  </Accordion>
</AccordionGroup>

### StreamingStatusChanged

Listen for changes in the underlying media streaming connection (different from coarse session states). This hook fires as the media pipeline connects, reconnects, or disconnects so that you can show precise UI copy or log telemetry.

```jsx theme={null}
Proview.session.on('StreamingStatusChanged', ({ status, data }) => {
  switch (status) {
    case 'connected':
      toast.success('Streaming live');
      break;
    case 'reconnecting':
      toast.info('Trying to restore streaming…');
      break;
    case 'disconnected':
      toast.error('Streaming stopped', data);
      break;
    default:
      break;
  }
});
```

<AccordionGroup>
  <Accordion title="Payload">
    ```ts theme={null}
    type StreamingStatusPayload = {
      status: 'connected' | 'disconnected' | 'reconnecting' | 'reconnected';
      data?: Record<string, unknown>;
    };
    ```

    * Events are emitted from the live room lifecycle (`connected`, `disconnected`, `reconnecting`, `reconnected`).
    * Payloads missing a `status` field normalize to `{ status: 'disconnected' }`.
  </Accordion>
</AccordionGroup>

## Removing Event Listeners

Use the `off` method to remove event listeners:

```jsx theme={null}
// Remove specific listener
Proview.session.off(eventName, callback);
```

<AccordionGroup>
  <Accordion title="Example: Removing Listeners">
    ```jsx theme={null}
    // Create handler function
    const handleSessionPause = (sessionStateOutput) => {
    console.log('Session paused:', sessionStateOutput.state);
    };

    // Add the listener
    Proview.session.on('Pause', handleSessionPause);

    // Later, remove the specific listener
    Proview.session.off('Pause', handleSessionPause);
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Session State Output">
    ```jsx theme={null}
    SessionStateOutput = {
    state: SessionState,
    reason: string
    }
    ```

    **SessionState** enum values:

    * `init` - Session initialized
    * `registered` - Session registered
    * `running` - Session actively running
    * `paused` - Session paused
    * `suspended` - Session suspended
    * `terminated` - Session terminated
    * `stopped` - Session stopped
    * `completed` - Session completed
  </Accordion>
</AccordionGroup>