Skip to main content

Starting a Journey

Access the SDK via the global window.UAEKYC object after the script loads:
const { startJourney, Status, ErrorCode } = window.UAEKYC;

const config = {
  journeyToken: "your-journey-token", // Required: from Create Journey API
  language: "en",                     // Optional: default "en"
  theme: "system",                    // Optional: "light", "dark", or "system"
  apiDomain: "your-api-domain.com",   // Optional: defaults to window origin
  privacyPolicyUrl: "https://example.com/privacy",
  logoUrl: "https://example.com/logo.png",
  accentColor: "#CFB16C",             // Optional
  docCaptureCamFacingMode: "environment"
};

const handleJourneyComplete = (result) => {
  console.log("Status:", Status[result.status]);
  console.log("Message:", result.message);

  if (result.code) {
    console.log("Error code:", ErrorCode[result.code]);
  }

  if (result.status === Status.Success) {
    console.log("KYC completed successfully");
  } else if (result.status === Status.Error) {
    console.error("KYC failed:", ErrorCode[result.code]);
  } else if (result.status === Status.Cancelled) {
    console.log("User cancelled");
  } else if (result.status === Status.DocumentVerificationFailed) {
    console.log("Document verification failed");
  } else if (result.status === Status.FaceVerificationFailed) {
    console.log("Face verification failed");
  } else if (result.status === Status.Expired) {
    console.log("Journey session expired");
  } else if (result.status === Status.Blocked) {
    console.log("Journey blocked — user must wait before retrying");
  }
};

startJourney(config, handleJourneyComplete);

Implementation Notes

Container Element

The SDK requires a container element with the ID uae-kyc-container to be present in your HTML before startJourney is called:
<div id="uae-kyc-container"></div>

Iframe Loading

The SDK mounts itself inside an iframe within the container element. This iframe encapsulates the entire KYC journey and isolates it from the rest of your application.

Responsive Design

Style the container element to ensure the iframe displays correctly across devices:
#uae-kyc-container {
  width: 100%;
  height: 100vh;
}

Journey Result

The callback receives a JourneyResult object:
interface JourneyResult {
  status: Status;
  message: string;
  code?: ErrorCode;
}
  • status — The outcome of the journey (see Configuration & Reference)
  • message — Human-readable description of the result. This message is not user-friendly and should not be displayed directly to end users.
  • code — Present only when status is Error; identifies the specific error

Advanced Active Liveness

Available from SDK v3.5.5 and above. This is a feature-flag controlled capability configured at the ICP level — no code changes required on your side.
The Advanced Active Liveness feature counters replay and video-injection attacks by introducing randomised, session-bound face orientation challenges during the liveness check.

How It Works

1

Face space divided into sectors

The user’s face space is divided into 8 directional sectors.
2

Random sector selection per session

Per session, the SDK randomly selects 3 to 5 sectors and instructs the user to orient their face accordingly in real time.
3

Anti-replay by design

The randomised, session-bound sector sequence makes the check fundamentally non-replayable — a pre-recorded video cannot satisfy an instruction set it was not recorded against.
4

Anti-spoofing detection

Beyond sector coverage, the SDK applies anti-spoofing detection that analyses the motion trajectory and depth consistency of head rotation. Video-based translations (flat 2D motion replays) are distinguished from genuine 3D head rotation and flagged accordingly.

Key Properties

PropertyDetail
ActivationFeature flag at ICP level — drop-in replacement, no client code changes
Minimum SDK versionv3.5.5+
Sectors per session3–5 (randomly selected from 8 directional sectors)
Attack resistanceReplay attacks, video injection, 2D presentation attacks
User experienceLightweight, intuitive gestures — smooth UX with high presentation attack detection
The gestures are lightweight and intuitive, keeping the user experience smooth while significantly raising the bar on presentation attack detection. Contact ICP to enable this feature for your integration.