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

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

function session.init(initOptions: InitOptions): void;

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.
identifier*	string	Value that can identify the proctored session in the source platform.
attendee*	Attendee	Attendee object containing candidate details. See Attendee Attributes.
workflow_step*	Workflow	Workflow object containing exam/workflow details. See 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).

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.

function onError(errorHandler: ErrorObject): void;

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[]

Example

<script>
  // Configure proviewOnLoad before adding the Loader Script
  window.proviewOnLoad = function () {
    Proview.session.init({
        dsn: "",
        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>

getLanguages

Get all supported language codes. Language code in BCP‑47 format (examples: “en”, “en-US”, “fr”, “fr-CA”). The language subtag typically follows ISO 639-1 (e.g., “en”), and the optional region subtag follows ISO 3166-1 Alpha-2 (e.g., “US”).

Function Type: Synchronous

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 format (examples: “en”, “en-US”, “fr”, “fr-CA”). The language subtag typically follows ISO 639-1 (e.g., “en”), and the optional region subtag follows 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

function setLanguage(language: string): string;

Example

// 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

getAttendee

Retrieve current attendee attributes.

Function Type: Synchronous

function getAttendee(): Attendee | undefined ;

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: [e-mail]
country_code	string (3)	ISO country code
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

Example

// 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');
}

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

function getWorkflow(): Workflow | undefined;

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
flow_uuid	string	Proctoring configuration identifier for the provided dsn. If the workflow step is already created with a flow, this will not override it.
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

Example

// 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');
}

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

function getLocale(): Locale

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

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”).

function getVersion(): String ;

Session Module

getState

Return the current state of the proctoring session.

Function Type: Synchronous

function getState(): SessionState ;

SessionState

Its of type enum which contains following values.

• INITIALISED
• ONBOARDING_IN_PROGRESS
• MONITORING_IN_PROGRESS
• PAUSED
• SUSPENDED
• STOPPED
• COMPLETED
• TERMINATED

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

function register(callback: (sessionOutput: SessionOutput | null, err: Error | null) => void): void;

SessionOutput

Attribute	Type	Description	Default
uuid	GUID	Reference Talview identifier for client application to track.
state	session.states	Current state of the session (INITIALISED, ONBOARDING_IN_PROGRESS, MONITORING_IN_PROGRESS, PAUSED, SUSPENDED, STOPPED, COMPLETED, TERMINATED)
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: [e-mail]
identifier	string	unique session identifier from the source system. It will be the session external id in the Talview platform.

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

function start(): Promise<SessionOutput>;
                            //or
function start(callback: (sessionOutput: SessionOutput, error: Error) => void): void;

SessionOutput

Attribute	Type	Description	Default
uuid	GUID	Reference Talview identifier for client application to track.
state	session.states	Current state of the session (INITIALISED, ONBOARDING_IN_PROGRESS, MONITORING_IN_PROGRESS, PAUSED, SUSPENDED, STOPPED, COMPLETED, TERMINATED)
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: [e-mail]
identifier	string	unique session identifier from the source system. It will be the session external id in the Talview platform.

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[]

Example

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);
}

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

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

SessionOutput

Attribute	Type	Description	Default
uuid	GUID	Reference Talview identifier for client application to track.
state	session.states	Current state of the session (INITIALISED, ONBOARDING_IN_PROGRESS, MONITORING_IN_PROGRESS, PAUSED, SUSPENDED, STOPPED, COMPLETED, TERMINATED)
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: [e-mail]
identifier	string	unique session identifier from the source system. It will be the session external id in the Talview platform.

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[]

Example

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);
}

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

function complete(callback:(sessionOutput: SessionOutput | null, err: Error | null) => void): void;

SessionOutput

Attribute	Type	Description	Default
uuid	GUID	Reference Talview identifier for client application to track.
state	session.states	Current state of the session (INITIALISED, ONBOARDING_IN_PROGRESS, MONITORING_IN_PROGRESS, PAUSED, SUSPENDED, STOPPED, COMPLETED, TERMINATED)
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: [e-mail]
identifier	string	unique session identifier from the source system. It will be the session external id in the Talview platform.

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[]

Example

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);
}

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.

function pause(reason: string, callback: (output: sessionStateOutput, err: Error | null) => void): void;

Session State Output

SessionStateOutput = {
state: Session State
reason: string
}

Session State is of type enum which contains following values.

• INITIALISED
• ONBOARDING_IN_PROGRESS
• MONITORING_IN_PROGRESS
• PAUSED
• SUSPENDED
• STOPPED
• COMPLETED
• TERMINATED

Example

// 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"
});

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.

function resume(reason: string, callback: (output: sessionStateOutput, err: Error | null) => void): void;

Session State Output

SessionStateOutput = {
state: Session State
reason: string
}

Session State is of type enum which contains following values.

• INITIALISED
• ONBOARDING_IN_PROGRESS
• MONITORING_IN_PROGRESS
• PAUSED
• SUSPENDED
• STOPPED
• COMPLETED
• TERMINATED

Example

Client Usage (Function):

// 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);
});

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.

Proview.session.on(eventName, callback);

Pause

Triggered when a proctoring session is paused.

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

Example

Proview.session.on('Pause', (sessionStateOutput) => {
console.log('Session paused:', sessionStateOutput.state);
console.log('Pause reason:', sessionStateOutput.reason);
});

Session State Output

SessionStateOutput = {
state: SessionState,
reason: string
}

Session State enum values:

• INITIALISED - Session initialized
• ONBOARDING_IN_PROGRESS - Onboarding in progress
• MONITORING_IN_PROGRESS - Monitoring in progress
• PAUSED - Session paused
• SUSPENDED - Session suspended
• STOPPED - Session stopped
• COMPLETED - Session completed
• TERMINATED - Session terminated

Resume

Triggered when a paused proctoring session is resumed.

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

Example

Proview.session.on('Resume', (sessionStateOutput) => {
console.log('Session resumed:', sessionStateOutput.state);
console.log('Resume reason:', sessionStateOutput.reason);
});

Session State Output

SessionStateOutput = {
state: SessionState,
reason: string
}

Session State enum values:

• INITIALISED - Session initialized
• ONBOARDING_IN_PROGRESS - Onboarding in progress
• MONITORING_IN_PROGRESS - Monitoring in progress
• PAUSED - Session paused
• SUSPENDED - Session suspended
• STOPPED - Session stopped
• COMPLETED - Session completed
• TERMINATED - Session terminated

Suspend

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

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

Example

Proview.session.on('Suspend', (sessionStateOutput) => {
console.log('Session suspended:', sessionStateOutput.state);
console.log('Suspension reason:', sessionStateOutput.reason);
});

Session State Output

SessionStateOutput = {
state: SessionState,
reason: string
}

Session State enum values:

• INITIALISED - Session initialized
• ONBOARDING_IN_PROGRESS - Onboarding in progress
• MONITORING_IN_PROGRESS - Monitoring in progress
• PAUSED - Session paused
• SUSPENDED - Session suspended
• STOPPED - Session stopped
• COMPLETED - Session completed
• TERMINATED - Session terminated

Terminate

Triggered when a proctoring session is terminated.

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

Example

Proview.session.on('Terminate', (sessionStateOutput) => {
console.log('Session terminated:', sessionStateOutput.state);
console.log('Termination reason:', sessionStateOutput.reason);
});

Session State Output

SessionStateOutput = {
state: SessionState,
reason: string
}

Session State enum values:

• INITIALISED - Session initialized
• ONBOARDING_IN_PROGRESS - Onboarding in progress
• MONITORING_IN_PROGRESS - Monitoring in progress
• PAUSED - Session paused
• SUSPENDED - Session suspended
• STOPPED - Session stopped
• COMPLETED - Session completed
• TERMINATED - Session terminated

StateChange

Triggered whenever the session state changes.

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

Example

Proview.session.on('StateChange', (sessionStateOutput) => {
console.log('Session state changed:', sessionStateOutput.state);
console.log('State change reason:', sessionStateOutput.reason);
});

Session State Output

SessionStateOutput = {
state: SessionState,
reason: string
}

Session State enum values:

• INITIALISED - Session initialized
• ONBOARDING_IN_PROGRESS - Onboarding in progress
• MONITORING_IN_PROGRESS - Monitoring in progress
• PAUSED - Session paused
• SUSPENDED - Session suspended
• STOPPED - Session stopped
• COMPLETED - Session completed
• TERMINATED - Session terminated

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.

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

Payload

type NetworkStatusPayload = {
  status: 'online' | 'offline';
};

• Emitted on every browser online/offline transition detected by Proview.
• Invalid or missing payloads automatically normalize to { status: 'offline' }.

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.

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;
  }
});

Payload

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' }.

Removing Event Listeners

Use the off method to remove event listeners:

// Remove specific listener
Proview.session.off(eventName, callback);

Example: Removing Listeners

// 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);

Session State Output

SessionStateOutput = {
state: SessionState,
reason: string
}

Session State enum values:

• INITIALISED - Session initialized
• ONBOARDING_IN_PROGRESS - Onboarding in progress
• MONITORING_IN_PROGRESS - Monitoring in progress
• PAUSED - Session paused
• SUSPENDED - Session suspended
• STOPPED - Session stopped
• COMPLETED - Session completed
• TERMINATED - Session terminated