APIs - Talview Docs

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.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 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.
attendee_identifier	`string`	Value that can identify the user in the source platform. While this is not a mandatory field at the time of init but its required to start a proctored session.
workflow_identifier	`string`	Value that can identify the exam in the source platform. While this is not a mandatory field at the time of init but its required to start a proctored session.
session_identifier	`string`	Value that can identify the proctored session in the source platform.
limit_languages	`[locale.languages]`[]	This will limit language options for users to select from the supported list	All supported languages
language	`[locale.languages]`	Explicitly set the SDK language	Browser default if its not supported then fallback to English (`en-US`).

Example

<script>
    // Configure proviewOnLoad before adding the Loader Script
    window.proviewOnLoad = function () {
    Proview.init({ dsn: "" });
};
</script>

<script src="https://dev.proview.io/cdn/init.js" async crossorigin="anonymous"></script>

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: Error Object): void;

Error Object

Attribute	Type	Description
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.init({
      dsn: "",
		  type: Proview.ProctoringType.RECORDED,
		  attendee_identifier :"att_0001",
		  workflow_identifier :"exam_0023"
    });

    // 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://dev.proview.io/cdn/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

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

function limitLanguages(languages: string[]): void;

Example

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`
last_name	`string`
middle_name	`string`
email	`string`		If not passed then system will generate email based on identifier. e.g: Att0001@dnd.talview.com
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
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');
}

setAttendee

Set or update the current attendee’s attributes used by the SDK (name, email, identifier, etc.).

Unique Identifier

Identifier is a unique field to map the user with the session.
Change of identifier via SDK is not support post the session register / start
It can be set either via setAttendee or as part of init via initOptions

Function Type: Synchronous

function setAttendee(Attendee): void ;

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`
last_name	`string`
middle_name	`string`
email	`string`		If not passed then system will generate email based on identifier. e.g: Att0001@dnd.talview.com
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
id	`int`	Talview unique id generated for the course

Example


const attendee = {
    first_name: "James",
    last_name: "Handerson",
    email: "james.handerson@gmail.com",
    identifier: "Att0001",
};

try {
    Proview.setAttendee(attendee);
} catch (error) {
    console.error('Failed to set attendee:', error);
    throw error;
}

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

setWorkflow

Set or update the current workflow attributes used by the SDK (for example, exam or course metadata).

If a workflow identifier was provided in Proview.init and the session is already registered, the identifier supplied at initialization takes precedence and will override workflow.identifier passed to this method.
This associate user’s action to the particular workflow.

If workflow associated information is utilized by the system then system will throw an error.

Function Type: Synchronous

function setWorkflow(Workflow): void;

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

Example

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`		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.init. Function Type: Synchronous Output: string (Semantic Versioning, e.g. “1.2.3”).

function getVersion(): String ;

Session Module

getState (read only)

Return the current state of the proctoring session. Function Type: Synchronous

function getState(): SessionState ;

SessionState

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`
attendee	`Attendee`
workflow	`Workflow`		If not passed then system will generate email based on identifier. e.g: Att0001@dnd.talview.com
identifier	`string`	unique session identifier from the source system. It will be the session external id in the Talview platform.

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)

function registerHook(hookType: HookType, callback: Function): void;

Example

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

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 Input:

session type (optional) — One of Proview.session.types values (e.g., session.types.RECORDED). If omitted, the SDK will use the default RECORDED.
Void function that takes SessionOutput and error as parameter. callback invoked on start completion

function start(sessionOptions: SessionOptions): Promise<SessionOutput>;
                            //or
function start(sessionOptions: SessionOptions, 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`
attendee	`Attendee`
workflow	`Workflow`		If not passed then system will generate email based on identifier. e.g: Att0001@dnd.talview.com
identifier	`string`	unique session identifier from the source system. It will be the session external id in the Talview platform.

SessionOptions

Attribute	Type	Description
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.

Error

Attribute	Type	Description
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({
    type: RECORDED,
    sessionIdentifier: "session_0012"
    duration: 20,
    remaining_duration: 10,

}, (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({
    type: RECORDED,
    sessionIdentifier: "session_0012"
});
console.log('Session state:', sessionOutput.state);
console.log('Session uuid:', sessionOutput.uuid);
} 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`
attendee	`Attendee`
workflow	`Workflow`		If not passed then system will generate email based on identifier. e.g: Att0001@dnd.talview.com
identifier	`string`	unique session identifier from the source system. It will be the session external id in the Talview platform.

Error

Attribute	Type	Description
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`
attendee	`Attendee`
workflow	`Workflow`		If not passed then system will generate email based on identifier. e.g: Att0001@dnd.talview.com
identifier	`string`	unique session identifier from the source system. It will be the session external id in the Talview platform.

Error

Attribute	Type	Description
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);
}

Proview SDK

​Global Module:

​init

​onError

​getLanguages

​setLanguage

​limitLanguages

​getAttendee

​setAttendee

​getWorkflow

​setWorkflow

​getLocale

​getVersion

​Session Module

​getState (read only)

​register

​registerHook

​start

​stop

​complete

Global Module:

init

onError

getLanguages

setLanguage

limitLanguages

getAttendee

setAttendee

getWorkflow

setWorkflow

getLocale

getVersion

Session Module

getState (read only)

register

registerHook

start

stop

complete