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
Face space divided into sectors
The user’s face space is divided into 8 directional sectors.
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.
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.
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
| Property | Detail |
|---|
| Activation | Feature flag at ICP level — drop-in replacement, no client code changes |
| Minimum SDK version | v3.5.5+ |
| Sectors per session | 3–5 (randomly selected from 8 directional sectors) |
| Attack resistance | Replay attacks, video injection, 2D presentation attacks |
| User experience | Lightweight, 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.