SDK Initialization

The init method initializes the Vida Web SDK and configures its behaviour. This method accepts an options object that allows customization of the SDK's functionality, appearance, and localization. Below is a detailed breakdown of all the parameters available in the InitOptions interface.

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: "identity-verification" /* Mandatory to pass this */
  countryCode: "MYS", /* Supported values - 'MYS' | 'PHL' | 'IDN' | 'SGP' | 'THA' | 'THL' | 'VNM' */
  locale: "EN",
  partnerTransactionId: "088f7c1f-49b4-fde2-4c5d-d61af9cca1f8",
  workflowConfigs: {
    identityVerification: {
      userConsent: { /* Optional */
        obtained: true,
        obtainedAt: Date.now(),
      },
      documentType: string, /* Optional */
      docVerification: {
        skipDocBackSideCapture: true, /* Optional */
        skipIntroductionScreen: false, /* Optional */
        skipDocSelectionScreen: false, /* Optional */
        skipTutorialScreen: false, /* Optional */
        maxRetryAttempts: 4, /* Optional */
        captureTimeOut: 120000, /* Optional */
      },
      faceMatch: {
        skipTutorialScreen: false, /* Optional */
        maxRetryAttempts: 4, /* Optional */
        detectionTimeOut: 120000, /* Optional */
      }
    },
  },
  themeConfigs: {
    primaryButtonBgColor: "#007bff",
    primaryButtonTextColor: "#ffffff",
    titleTextColor: "#333333",
  },
  onComplete: (data) => {
    console.log("Identity verification process completed:", data);
  },
  onError: (error) => {
    console.error("Error during Identity verification process:", error);
  },
});

Document Back Side Capture & Verification is only supported for following cards - MyKad, MyKas, MyPR & MyTentera.

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. Character limits partnerTransactionId and userInfo.id both accept a maximum of 100 characters. Sending a longer value will cause SDK initialization to fail.

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.
fraudShieldClientId	string	No	Client ID to enable device fraud detection. Mandatory if ID fraud shield needs to be enabled.
onComplete	(data: IdentityVerificationResponse) => void	Yes	Callback executed when the liveness/ Onboarding process is completed successfully. The response data is passed as an argument.
onError	(data: IdentityVerificationResponse) => void	No	Callback executed if an error occurs during the identity verification process either in the client side or in the API. The error data is passed as an argument.
onDocVerificationSuccess	(data: IdentityVerificationResponse) => void	No	Callback executed when doc verification is successful.
onDocVerificationError	(data: IdentityVerificationResponse) => void	No	Callback executed when doc verification is api is errored out.
onSelfieCapture	(image: string) => void	No	Callback executed when a selfie is captured. The captured image (Base64 string) is passed as an argument.
onDocFaceMatchError	(data: IdentityVerificationResponse) => void	No	Callback executed when document face match api is errored out.
hideNetworkStatusAlert	boolean	No	Passing this true will hide network status (internet connectivity / offline ) alert.
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	"identity-verification"	Yes	Specifies the workflow. use “identity-verification” for identity verification ( KYC ) flow.
countryCode	'MYS' | 'PHL' | 'IDN' | 'SGP' | 'THA' | 'VNM'	No	ISO3 country code for the Identity Verification flow. Defaults to MYS ( Malaysia )
partnerTransactionId	string	No	A unique transaction ID provided by the partner for tracking purposes. Note: Maximum 100 characters. Values longer than this will cause the request to fail.
userInfo.id	string	No	UserID or hash of the UserID. This will help to configure rules around users. Note: Maximum 100 characters. If not provided, the SDK uses a default value.
workflowConfigs	object	No	Configuration options specific to the identity verification workflow.
localeConfigs	object	No	Custom localization configurations.
themeConfigs	object	No	Custom styling options to align the SDK with your brand's design.