Framework Integration

Learn how to integrate the SDK with popular web frameworks.

React Integration

Basic JavaScript Setup

For plain JavaScript React applications, simply import the SDK:

import '@azakawcompliance/azakaw-web-sdk';

TypeScript Setup

The package ships its own React JSX types. Add this single line to your global.d.ts file (or any .d.ts covered by your tsconfig.json include):

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

This registers <az-customer-onboarding> on React's JSX types, so the element and all of its attributes — including the SdkRegion / SdkEnvironment enum values — are type-checked and autocompleted. The shipped types cover both React 16 (global JSX namespace) and React 17+ (React.JSX), so no hand-written declare global block is needed.

note

Earlier versions of this guide asked you to declare az-customer-onboarding yourself inside declare global { namespace JSX { ... } }. That approach no longer works on React 19, which removed the global JSX namespace. Replace any such block with the /// <reference ... /> line above.

Implementation Example

Here's a complete example showing best practices for event handling and performance:

import React, { useCallback, useContext, useEffect, useRef } from 'react';
import '@azakawcompliance/azakaw-web-sdk';
import {
  CustomerOnboardingWebComponent,
  SdkEnvironment,
  SdkRegion,
} from '@azakawcompliance/azakaw-web-sdk';
import { SessionContext } from '../context/sessionProvider';

const Onboarding = () => {
  const ref = useRef<CustomerOnboardingWebComponent>(null);
  const { sessionId } = useContext(SessionContext);

  // Define callback outside useEffect to prevent recreation on every render
  const onOnboardingComplete = useCallback(() => {
    console.log('Completed onboarding.');
  }, []);

  useEffect(() => {
    if (!ref?.current) return;
    const azakawElemRef = ref?.current;

    azakawElemRef?.addEventListener(
      'onboardingCompleted',
      onOnboardingComplete
    );

    return () => {
      azakawElemRef?.removeEventListener(
        'onboardingCompleted',
        onOnboardingComplete
      );
    };
  }, [sessionId, onOnboardingComplete]); 

  return (
    sessionId && (
      <az-customer-onboarding
        class="az-customer-onboarding"
        session-id={sessionId}
        host-origin="http://localhost:3000"
        environment={SdkEnvironment.Sandbox}
        region={SdkRegion.UAE}
        ref={ref}
      ></az-customer-onboarding>
    )
  );
};

export default Onboarding;

SdkEnvironment and SdkRegion are runtime exports, so you can use the enum members directly instead of raw strings. Plain string literals (environment="Sandbox", region="UAE") also work — they are case-sensitive.

Angular Integration

Setup Module

Add CUSTOM_ELEMENTS_SCHEMA in your AppModule:

import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  bootstrap: [AppComponent]
})
export class AppModule { }

Component Implementation

import { Component, ElementRef, OnDestroy, ViewChild } from '@angular/core';
import '@azakawcompliance/azakaw-web-sdk';
import { CustomerOnboardingWebComponent } from '@azakawcompliance/azakaw-web-sdk';

@Component({
  selector: 'app-root',
  template: `
    <div class="wrapper">
      <az-customer-onboarding
        #customerOnboardingElem
        session-id="your-session-id"
        host-origin="http://localhost:4201"
        environment="Sandbox"
        region="UAE"
      ></az-customer-onboarding>
    </div>
  `
})
export class AppComponent implements OnDestroy {
  @ViewChild('customerOnboardingElem')
  customerOnboardingElem!: ElementRef<CustomerOnboardingWebComponent>;

  ngAfterViewInit(): void {
    this.customerOnboardingElem?.nativeElement?.addEventListener(
      'onboardingCompleted',
      this.onOnboardingCompleted
    );
  }

  ngOnDestroy(): void {
    this.customerOnboardingElem?.nativeElement?.removeEventListener(
      'onboardingCompleted',
      this.onOnboardingCompleted
    );
  }

  private onOnboardingCompleted = () => {
    console.log('Completed onboarding');
  };
}