API Reference

Complete reference for the Azakaw Web SDK API.

Component Properties

Inputs

Input	Type	Default	Required	Description
session-id	string	null	yes	Session ID against which the user onboarding will be performed. Issued by your backend — see Session Management
host-origin	string	null	yes	The URL on which your web application is hosted
environment	SdkEnvironment (Sandbox | Production)	Sandbox	optional	Target environment for the onboarding session. Case-sensitive
region	SdkRegion (KSA | Qatar | UAE)	UAE	optional	Region in which the onboarding session is processed; selects the portal domain. All three are available in Production; Sandbox is UAE only. Case-sensitive
auto-resize	boolean	false	optional	The iframe height will be resized dynamically based on the content shown inside it
hide-sidebar	boolean	false	optional	Hides the sidebar on the user onboarding page
hide-onboarding-sections	boolean	false	optional	Starts the user onboarding from the first page of the form; the user is only allowed to see the onboarding sections page once onboarding is completed

Events

Event Name	Returns	Description
onboardingCompleted	void	Fired when user completes the onboarding

Environment and region

environment and region are resolved independently and combined into the portal URL the SDK loads. region selects the domain and environment selects the subdomain. Both values are matched exactly, so casing matters.

Region	Domain	Sandbox	Production
UAE (default)	azakaw.com	sandbox.azakaw.com	app.azakaw.com
KSA	azakawksa.com	— not available	app.azakawksa.com
Qatar	azakawqatar.com	— not available	app.azakawqatar.com

Omit region to use UAE.

note

Sandbox is available for UAE only. KSA and Qatar are Production-only — pair them with environment="Production". There is no sandbox environment for those regions to test against yet.

caution

region and environment are read once when the component mounts; changing them afterward has no effect. Set them before the element is added to the DOM.

Types

The package exports its types and enums from the package root:

import {
  CustomerOnboardingWebComponent,
  SdkEnvironment,
  SdkRegion,
} from '@azakawcompliance/azakaw-web-sdk';

SdkRegion

enum SdkRegion {
  KSA = 'KSA',
  Qatar = 'Qatar',
  UAE = 'UAE',
}

SdkEnvironment

enum SdkEnvironment {
  Sandbox = 'Sandbox',
  Production = 'Production',
}

Both are runtime exports, so they can be used as values in your code as well as types.

CustomerOnboardingWebComponent

The main web component class. Properties are named after the HTML attributes:

declare class CustomerOnboardingWebComponent extends HTMLElement {
  'session-id': string;
  'host-origin': string;
  'environment': SdkEnvironment;
  'region': SdkRegion;
  'auto-resize': boolean;
  'hide-sidebar': boolean;
  'hide-onboarding-sections': boolean;
  attributeChangedCallback(
    attrName: string,
    oldValue: string,
    newValue: string,
    namespace?: string
  ): void;
  connectedCallback(): void;
  disconnectedCallback(): void;
}

The package also augments the DOM type maps, so document.querySelector('az-customer-onboarding') is typed and the onboardingCompleted event is recognised by addEventListener:

declare global {
  interface HTMLElementTagNameMap {
    'az-customer-onboarding': CustomerOnboardingWebComponent;
  }

  interface HTMLElementEventMap {
    onboardingCompleted: CustomEvent<void>;
  }
}

React JSX types

React JSX typings ship under a separate entry point. Add the following to a .d.ts file covered by your tsconfig.json — see Framework Integration:

/// <reference types="@azakawcompliance/azakaw-web-sdk/react" />

Component Lifecycle

The web component follows this lifecycle:

1. Component Initialization

   • Validates required properties
   • Resolves the portal URL from environment and region
   • Sets up event listeners

2. Session Handling

   • Validates session ID
   • Establishes connection

3. Onboarding Process

   • Renders UI
   • Handles user interactions
   • Manages state

4. Completion

   • Fires onboardingCompleted event
   • Cleans up resources

Error States

The component handles various error states:

1. Invalid Session ID

   • Component will show error message
   • Won't proceed with onboarding

2. Network Issues

   • Displays connection error
   • Attempts to reconnect

3. Invalid Host Origin

   • Shows configuration error
   • Prevents initialization

Examples

Basic Implementation

<az-customer-onboarding
  session-id="d43151a9-a031-4067-a4c7-21baee51cfa3"
  host-origin="http://localhost:4200"
  environment="Sandbox"
  region="UAE"
></az-customer-onboarding>

With Event Handling

const element = document.querySelector('az-customer-onboarding');
element.addEventListener('onboardingCompleted', () => {
  // Handle completion
});

TypeScript Implementation

import {
  CustomerOnboardingWebComponent,
  SdkEnvironment,
  SdkRegion,
} from '@azakawcompliance/azakaw-web-sdk';

const handleComplete = () => {
  console.log('Onboarding completed');
};

// Configure the element before it is added to the DOM — see the caution in
// "Environment and region" above.
const element = document.createElement(
  'az-customer-onboarding'
) as CustomerOnboardingWebComponent;

element.setAttribute('session-id', 'd43151a9-a031-4067-a4c7-21baee51cfa3');
element.setAttribute('host-origin', 'http://localhost:4200');
element.setAttribute('environment', SdkEnvironment.Sandbox);
element.setAttribute('region', SdkRegion.UAE);
element.addEventListener('onboardingCompleted', handleComplete);

document.querySelector('.container')!.appendChild(element);