Proview SDK — v7 to v8 Migration Guide

Client-side Proview SDK migration: v7 → v8 · Script: https://sdk.tlv.cx/session/init.jsOfficial v8 docs: Getting Started · Full API Reference · Session PlaybackThis guide covers migration-specific changes and before/after code only. Refer to the official docs links above for complete API reference, parameter defaults, and current examples.

Breaking changes

All changes below require code modification. Severity indicates what breaks without the fix.

🔴 Critical — the integration will not load without these

Script URL has changed. Update the loader on every page that runs proctoring.

<!-- v7 -->
<script async src="https://cdn.proview.io/client/init.js"></script>

<!-- v8 -->
<script async src="https://sdk.tlv.cx/session/init.js" crossorigin="anonymous"></script>

Global namespace renamed: ProctorClient3 → Proview. window.ProctorClient3 no longer exists. All method calls move under Proview.session.*.

// v7
window.ProctorClient3.start();
window.ProctorClient3.stop();
window.ProctorClient3.on(/* ... */);

// v8
Proview.session.start();
Proview.session.stop();
Proview.session.on(/* ... */);

Authentication credential changed: proctor_token → dsn. v7 used a per-session proctor_token UUID. v8 uses a project-level Data Source Name (DSN). Contact Talview support to provision your DSN. Initialization pattern changed: command queue → proviewOnLoad callback. v7 used a command queue (window.tv). v8 requires window.proviewOnLoad to be defined before the script tag; the Proview global is available inside the callback.

// v7
window.tv = window.tv || function () { (tv.q = tv.q || []).push(arguments); };

// v8
window.proviewOnLoad = async function () {
  // Proview global is available here
  const success = await Proview.session.init({ /* ... */ });
  if (!success) return;
};

🟠 High — behavioral breakage

Session start is now a Promise, not a callback. initCallback(err, uuid) is removed. session.start() returns a Promise that resolves with a SessionOutput.

// v7
tv('init', token, {
  initCallback: function (err, uuid) {
    if (err) return;
    ProctorClient3.start();
  },
});

// v8
const output = await Proview.session.start();
console.log('Session UUID:', output.uuid);

Client-side alert events removed — monitoring is now server-side via webhooks. v7 fired per-alert events via numeric IDs (ProctorClient3.on('log:event:type:16', cb)). v8 has no client-side alert events. All monitoring happens server-side and is delivered as structured incidents to your registered webhook endpoint. The only suspension signal visible client-side is the Suspend hook. See Webhooks overview. Error handling is now global, not per-init. Register Proview.onError(handler) once before calling session.init(). The per-init errorCallback is removed.

Proview.onError(function (err) {
  // err.code, err.message, err.type: 'warning' | 'critical'
});

Network events are now object-based, not a single callback. networkDisconnectionCallback is removed. Use the NetworkStatusChanged hook. The callback receives an object { status: 'online' | 'offline' }, not a string.

Proview.session.on('NetworkStatusChanged', function ({ status }) {
  if (status === 'offline') showBanner();
  if (status === 'online') hideBanner();
});

Webhook payload format has changed. The v7 rating_callback_url flat payload is replaced by a typed, versioned JSON envelope. See Webhooks overview and Subscribing to webhooks.

🟡 Medium & Low — parameter renames and removals

All renamed and removed parameters are listed in the Parameter reference table below.

Before you start

DSN — Contact Talview to provision DSNs for staging and production. Treat it as a secret; never commit it or expose it in source maps.
Workflow step identifiers — Session type is no longer passed in code; it is dashboard-configured. Confirm your workflow_step.identifier UUIDs with Talview before writing code.
Webhook endpoint — Provide your HTTPS endpoint URL to Talview support; they configure which event types are delivered. The endpoint must accept POST, respond HTTP 200 within 10 seconds, and be publicly reachable.

SDK migration

Script loading

Define window.proviewOnLoad before the script tag. The Proview global is available inside the callback.

<!-- v7 -->
<script>
  window.tv = window.tv || function () { (tv.q = tv.q || []).push(arguments); };
</script>
<script async src="https://cdn.proview.io/client/init.js"></script>

<!-- v8 -->
<script>
  window.proviewOnLoad = async function () {
    // Proview global is ready here
  };
</script>
<script async src="https://sdk.tlv.cx/session/init.js" crossorigin="anonymous"></script>

Initialization

// v7
tv('init', 'xxxxxxxx-proctor-token-xxxx', {
  profileId: 'candidate-user-id',
  session: 'session-uuid',
  session_type: 'record_and_review',
  sessionTitle: 'Technical Interview',
  firstName: 'Jane',
  lastName: 'Doe',
  email: 'jane@example.com',
  initCallback: function (err, uuid) {
    if (err) return;
    ProctorClient3.start();
  },
  errorCallback: function (err) { console.error(err); },
  networkDisconnectionCallback: function () { showOfflineBanner(); },
});

// v8
window.proviewOnLoad = async function () {
  // 1. Register the global error handler before init()
  Proview.onError(function (err) {
    // err.code, err.message, err.type: 'warning' | 'critical'
    console.error('[Proview]', err.code, err.message);
  });

  // 2. Register session hooks before init()
  Proview.session.on('NetworkStatusChanged', function ({ status }) {
    if (status === 'offline') showOfflineBanner();
    if (status === 'online') hideOfflineBanner();
  });

  Proview.session.on('Suspend', function ({ state, reason }) {
    console.log('Session suspended:', reason);
  });

  Proview.session.on('StateChange', function ({ state, reason }) {
    console.log('State →', state, reason);
  });

  // 3. Initialize — returns Promise<boolean>
  const success = await Proview.session.init({
    dsn: 'YOUR_DSN_HERE',
    identifier: 'session-uuid-from-your-backend',
    attendee: {
      identifier: 'candidate-user-id',
      first_name: 'Jane',
      last_name: 'Doe',
      email: 'jane@example.com',
    },
    workflow_step: {
      identifier: 'workflow-step-uuid-from-your-backend',
      name: 'Technical Interview',
      duration: 60,
    },
  });

  if (!success) {
    console.error('Proview failed to initialize');
    return;
  }
};

Start the session on a user action (for example, an “Start Exam” button click):

// v8 — start on user action
document.getElementById('start-exam').addEventListener('click', async function () {
  try {
    const output = await Proview.session.start();
    // output.uuid, output.state, output.attendee, output.workflow_step
    console.log('Session started:', output.uuid);
  } catch (err) {
    console.error('Unable to start proctoring', err);
  }
});

Stop and complete

// Normal completion — candidate reached the end of the assessment
await Proview.session.complete();

// Abnormal stop — timed out, navigated away, or terminated early
await Proview.session.stop();

Pause and resume

reason is required for both pause() and resume(). The SDK throws if the string is empty.

// v7
ProctorClient3.pause();
ProctorClient3.resume();

// v8
await Proview.session.pause('Scheduled break');
await Proview.session.resume('Break over');

Session hooks

Proview.session.on(eventName, callback) replaces v7’s numeric alert IDs. session.on() returns an unsubscribe function, or use session.off(eventName, namedCallback) to remove a specific listener.

Event	Payload shape	When fired
`Suspend`	`{ state, reason }`	Session auto-suspended by the monitoring system
`Terminate`	`{ state, reason }`	Session ended by the system due to violations
`Pause`	`{ state, reason }`	Session paused (mirrors `session.pause()`)
`Resume`	`{ state, reason }`	Session resumed (mirrors `session.resume()`)
`StateChange`	`{ state, reason }`	Any session state transition
`NetworkStatusChanged`	`{ status: 'online' \| 'offline' }`	Network connectivity changes
`StreamingStatusChanged`	`{ status: 'connected' \| 'disconnected' \| 'reconnecting' \| 'reconnected', data? }`	Media stream quality changes

No client-side alert events in v8. The v7 numeric alert IDs (ProctorClient3.on('log:event:type:N', cb)) do not exist in v8. All monitoring happens server-side and is delivered as structured incidents to your webhook endpoint.

Session states

SessionOutput.state (and the state field in hook payloads) uses the SDK SessionState enum. These are the same eight uppercase values documented in Configuration.

State	Meaning	How reached
`INITIALISED`	SDK loaded, before `session.init()` completes	SDK ready
`ONBOARDING_IN_PROGRESS`	Candidate is in the precheck / onboarding step	After `session.start()` resolves
`MONITORING_IN_PROGRESS`	Active — candidate is being monitored	After onboarding completes
`PAUSED`	Temporarily halted by your code	`session.pause(reason)`
`SUSPENDED`	Auto-paused by monitoring due to a violation	System — fires the `Suspend` hook
`STOPPED`	Interrupted before completion	`session.stop()`
`COMPLETED`	Candidate finished legitimately	`session.complete()`
`TERMINATED`	Ended by the system due to violations	System — fires the `Terminate` hook

Webhook payload.status is a separate, server-side vocabulary — CREATED, IN_PROGRESS, PAUSED, SUSPENDED, STOPPED, COMPLETED, TERMINATED. It is delivered in webhook events and is not the same set as the SDK state above (for example, server-side IN_PROGRESS corresponds to the SDK’s MONITORING_IN_PROGRESS). Don’t map the two one-to-one. See Webhooks overview.

Parameter reference: v7 → v8 changes

v7	v8	Change
`proctor_token`	`dsn`	Renamed + format changed — DSN is project-level, not per-session
`session`	`identifier`	Renamed only
`profileId`	`attendee.identifier`	Moved into the nested `attendee` object
`firstName` / `lastName`	`attendee.first_name` / `attendee.last_name`	Snake_case + nested in `attendee`
`email`	`attendee.email`	Nested in `attendee`
`session_type`	—	Removed — configure per workflow in the Proview dashboard
`sessionTitle`	`workflow_step.name`	Moved into the `workflow_step` object
`initCallback(err, uuid)`	`await Proview.session.start()` → `SessionOutput`	Replaced — start is now a separate Promise-based call, not a callback passed to init
`errorCallback(err)`	`Proview.onError(handler)`	Replaced — errors handled via a global `Proview.onError()` call made once before `session.init()`
`networkDisconnectionCallback`	`session.on('NetworkStatusChanged', cb)`	Replaced — network events are a session hook; payload is `{ status }` (object, not string)

For the full session.init() options and the attendee, workflow_step, and SessionOutput object shapes, see Configuration and Types.

Rollout checklist

Code changes Staging validation

Full lifecycle: init() → start() → complete() → webhook received
Session and incident webhook payloads received and stored correctly
Suspend hook fires and is handled
NetworkStatusChanged payload handled as a { status } object
Pause / resume tested end-to-end with non-empty reason strings
Session playback loads
Error handler fires on an invalid DSN
Browser console: no CSP violations, no 404s from the old domain

Production cutover

DSN swapped to the production value
CSP updated in production (including 'unsafe-inline' directives)
Webhook endpoint registered for production with Talview support

Troubleshooting

`Proview` is undefined on page load

proviewOnLoad was not defined before the script tag, or the SDK script failed to load. Ensure window.proviewOnLoad = async function () {...} is in a <script> block immediately before the <script async src="..."> tag. Check the network tab for a 404 or CSP block on sdk.tlv.cx.

CSP violation on sdk.tlv.cx

Add https://sdk.tlv.cx to script-src (with 'unsafe-inline') and to img-src. Add https://*.talview.com and wss://*.talview.com to connect-src. Keep https://cdn.proview.io in your v7 directives until all in-flight v7 sessions have ended, then remove it.

session.init() resolves false

The DSN is invalid or belongs to the wrong environment (for example, a staging DSN used in production), or a required field is missing. Check Proview.onError() output for the specific error code, and verify the DSN with your Talview account team.

session.pause() rejects: 'Pause reason is required'

The reason argument is empty or whitespace. Pass a non-empty string: session.pause('Scheduled break').

Webhooks not arriving at my endpoint

Confirm the endpoint is registered with Talview support, returns HTTP 200 within 10 seconds, and is publicly reachable over HTTPS. Webhooks may be retried, so implement idempotent upsert logic keyed on payload.uuid with an updated_at guard.

For general SDK troubleshooting, see Troubleshooting. For integration issues not covered here, contact Talview support and include the session UUID, browser console output, and network requests to sdk.tlv.cx.

​Breaking changes

​🔴 Critical — the integration will not load without these

​🟠 High — behavioral breakage

​🟡 Medium & Low — parameter renames and removals

​Before you start

​SDK migration

​Script loading

​Initialization

​Stop and complete

​Pause and resume

​Session hooks

​Session states

​Parameter reference: v7 → v8 changes

​Rollout checklist

​Troubleshooting

Breaking changes

🔴 Critical — the integration will not load without these

🟠 High — behavioral breakage

🟡 Medium & Low — parameter renames and removals

Before you start

SDK migration

Script loading

Initialization

Stop and complete

Pause and resume

Session hooks

Session states

Parameter reference: v7 → v8 changes

Rollout checklist

Troubleshooting