SDK Initialization

The init method initializes the Vida Web SDK and configures its behavior. This method accepts an options object that allows customization of the SDK's functionality, appearance, and localization.

Example Code for init method

import { VidaSDK } from "vida-web-sdk";

/* If using script tag, directly use - window.VidaSDK.init() */
VidaSDK.init({
  token: "your-bearer-token",
  signingKey: "your-signing-key",
  env: "production", // pass "sandbox" for sandbox env, This param is required only for integration via npm package
  elementId: "sdk-container",
  workflow: "liveness", 
  locale: "EN",
  partnerTransactionId: "088f7c1f-49b4-fde2-4c5d-d61af9cca1f8",
  partner: { /* applicable for user onboarding auth */
    logo: "<URL for Branding Logo>";
    name: "<Your Brand/Org Name>";
  },
  userInfo: {
    id: "user-123"
  },
  workflowConfigs: {
    liveness: {
      maxRetryAttempts: 4,
      detectionTimeOut: 120000,
    },
  },
  themeConfigs: {
    primaryButtonBgColor: "#007bff",
    primaryButtonTextColor: "#ffffff",
    titleTextColor: "#333333",
  },
  onComplete: (data) => {
    console.log("Liveness completed:", data);
  },
  onError: (error) => {
    console.error("Error during liveness:", error);
  },
});

Below is a detailed breakdown of all the parameters available in the InitOptions interface.

Using ID Fraud Shield?

When ID Fraud Shield is enabled for your account, it runs alongside this liveness flow to strengthen verification with additional fraud-risk signals. Provide userInfo.id so fraud rules can be applied per user.

userInfo.id is optional — if you do not provide it, the SDK uses a default value — but we recommend setting your own.

See the ID Fraud Shield Integration guide for full details.

Parameters

Parameter	Type	Required	Description
token	string	Yes	The bearer token obtained from Vida SSO. Used for authentication.
signingKey	string	Yes	The signing key shared by Vida. Required for secure SDK initialization.
env	string	Yes for npm based integration	This is required only if your integration method is via npm package. Environment values are production / sandbox
elementId	string	No	The ID of the HTML element where the SDK will be rendered. If not provided, the SDK will create an element and render the SDK.
onComplete	(data: LivenessResponse) => void	No	Callback executed when the liveness process is completed successfully. The response data is passed as an argument.
onError	(data: LivenessResponse) => void	No	Callback executed if an error occurs during the liveness process either in the client side or in the API. The error data is passed as an argument.
onSelfieCapture	(image: string) => void	No	Callback executed when a selfie is captured. The captured image (Base64 string) is passed as an argument.
locale	string	No	Language code for localization (e.g., "EN" for English, "ID" for Indonesian). Defaults to browser language if not specified. Falls back to EN if browser language is not available/applicable.
workflow	"liveness"	No	Specifies the workflow. Currently, only "liveness" is supported. (In future, may support “ocr” and “kyc”).
partnerTransactionId	string	No	A unique transaction ID provided by the partner for tracking purposes.
userinfo.Id	string	No	UserID or hash of the UserID. This will help to configure rules around users.
workflowConfigs	object	No	Configuration options specific to the liveness workflow.
localeConfigs	object	No	Custom localization configurations.
themeConfigs	object	No	Custom styling options to align the SDK with your brand's design.

This table summarizes all the parameters you can use in the init method to configure the Vida Web SDK.