@eka-care/abha-stg

v0.1.106

Published

6 hours ago

This guide provides everything you need to integrate the ABHA SDK into your application.

Downloads

1,852

0High
0Medium
0Low

ABHA SDK Implementation

This guide provides everything you need to integrate the ABHA SDK into your application.

Overview

The ABHA SDK allows you to integrate Create ABHA, Login with ABHA, ABHA Consent Management, ABHA Profile KYC flows into your healthcare applications. It provides:

Create ABHA: Create a new ABHA using Mobile or Aadhaar.
Login with ABHA: Login to your exisiting ABHA using PHR Address, ABHA number, Aadhaar number or Mobile number.
ABHA Consent Management: Manage Consent requests raised by healthcare providers to share medical records securely.
ABHA Profile KYC: Get your ABHA address KYC verified.

Installation

Prerequisites

A modern web browser.
Your domain must be whitelisted with Eka Care to avoid CORS(Cross-Origin Resource Sharing) error. (Contact Eka Care to request API access and domain whitelisting.)
A valid HTML container element where the SDK will mount.

Setup

Add the following HTML and script tags to your webpage:

<!DOCTYPE html>
<html>
  <head>
    <title>ABHA SDK Integration</title>

    <!-- Include ABHA SDK CSS -->
    <link
      rel="stylesheet"
      href="https://unpkg.com/@eka-care/abha-stg/dist/sdk/abha/css/abha.css"
    />
  </head>
  <body>
    <h1>ABHA SDK Demo</h1>

    <!-- Mount Button -->
    <button class="button" onclick="mountABHASDK()">Mount SDK</button>

    <!-- Container for ABHA SDK -->
    <div id="sdk_container"></div>

    <!-- Include ABHA SDK JS -->
    <script
      type="module"
      src="https://unpkg.com/@eka-care/abha-stg/dist/sdk/abha/js/abha.js"
    ></script>

    <script>
      function mountABHASDK() {
        window.initAbhaApp({
          containerId: "sdk_container",
          clientId: "ext",
          theme:{
              // if you want to customise sdk theme/colors
             // pass the colors of your organisation design system
          },
         // data object 
          data: {
            // pass the required data as per the flow
           },

          // Success callback
          onSuccess: (params) => {
            console.log("ABHA Registration flow completed successfully:", params);
          },

          //KYC Successs callback
          onKYCSuccess: (params) => {
            console.log("ABHA KYC Verified successfully:", params);
          },

          //Consent Successs callback
          onConsentSuccess: (params) => {
            console.log("ABHA Consent flow completed successfully:", params);
          },

          // Error callback
          onError: (params) => {
            console.error("ABHA SDK failed:", params);
          },
          
          // Abha Close callback
          onAbhaClose: () => {
            console.log("ABHA SDK closed");
          },

          // Skip ABHA callback
          onSkipAbha: (params) => {
            console.log("ABHA flow SKIPPED:", params);
          },
        });
      }
    </script>
  </body>
</html>

Core Functions

1. initAbhaApp

Initializes and renders the ABHA SDK in your specified container.

Parameters:

| Name | Type | Required | Description | | ------------- | --------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | containerId | string | ✅ | The HTML element ID where the SDK will mount. | | clientId | string | ✅ | Provide clientId as ext. | | theme | {} object | ⚙️ Optional | Provide theme object with your org design system colors. | | data | {accessToken: string;hipId: string;oid?: string;identifier?: string;identifier_type?: string;consent_id?: string;flow?: string;linkToOrgIcon?: string;orgIconUrl?: string;skipABHAEnable?: boolean;} | ⚙️ Optional | Configuration data for initializing the ABHA flow. - accessToken: Pass the access token you have generated from Connect Login API without the word Bearer. - hipId: Pass the HFR ID you have. - oid: Pass oid of patient if available / needed in the flow. - identifier: Pass the login identifier value i.e. mobile number / aadhaar number / phr address / abha number.- identifier_type: Pass the type of identifier which you passed in identifier key i.e. "mobile" / "aadhaar_number" / "phr_address" / "abha_number" /. If not known pass undefined. - consent_id: Pass the consent_id of the consent request raised. - flow: Pass the type of flow for which you want to use SDK for i.e. abha-kyc for KYC flow / consent for Consent flow. - linkToOrgIcon: Public CDN URL of the icon representing “Link ABHA to your organisation” url should start with https://. Example- orgIconUrl: Public URL of your organization's logo. It is displayed in specific journey headers url should start with https://. Example- skipABHAEnable: Pass the boolean as true if you want Skip ABHA button to be enabled on login screen. keys with ? are optional and needs to be passed as per flow requirement. | | onSuccess | (params: TOnAbhaSuccessParams) => void | ✅ | Triggered when the user successfully creates or logs in to ABHA. | | onKYCSuccess | (params: TOnAbhaKycSuccessParams) => void | ⚙️ Optional | Triggered when the user KYC verified successfully. | onConsentSuccess | (params: TOnAbhaConsentSuccessParams) => void | ⚙️ Optional | Triggered when the consent flow completes successfully. | onError | (params: TOnAbhaFailureParams) => void | ✅ | Triggered when an error occurs during the ABHA flow.
| onAbhaClose | () => void | ✅ | Triggered when SDK closes.
| onSkipAbha | (params: TOnSkipABHA) => void | ⚙️ Optional | Triggered if the ABHA flow is skipped. |

Callback Parameters

onSuccess Callback

The onSuccess callback is triggered when the ABHA flow completes successfully. It returns verified user details and tokens, which can be used to log in or continue the user’s session.

Callback Signature:

onSuccess: (params: TOnAbhaSuccessParams) => void;

Type Definitions

type TOnAbhaSuccessParams = {
  response: TAuthVerifyV2Response;
};

type TAuthVerifyV2Response = {
  skip_state: number;
  method: AUTH_METHOD;
  data?: {
    tokens: {
      sess: string;
      refresh: string;
    };
    profile: TProfileRecord;
  };
  txn_id: string;
  error?: {
    code: number;
    message: string;
  };
};

enum AUTH_METHOD {
  EMAIL = 1,
  MOBILE = 2,
  ABHA = 7,
}

type TProfileRecord = {
  fln: string;
  fn: string;
  mn?: string;
  ln?: string;
  gen?: "M" | "F" | "O" | "U" | undefined; // 'male' | 'female' | 'other' | 'unknown'
  dob?: string;
  mobile?: string;
  email?: string;
  uuid?: string;
  bloodgroup?: "" | "A+" | "A-" | "B+" | "B-" | "O+" | "O-" | "AB+" | "AB-";
  pic?: string;
  as?: string;
  "dob-valid"?: boolean;
  "is-d"?: boolean;
  "is-d-s"?: boolean;
  "is-p"?: boolean;
  oid: string;
  at: string;
  type?: 1 | 2 | 3 | 4 | 5 | 6;
  "health-ids"?: Array<string>;
  abha_number?: string;
  kyc_verified?: boolean;
};

Parameters | Key | Type | Description | | ---------- | ----------------------- | ---------------------------------------------------------------------------------------------------------- | | response | TAuthVerifyV2Response | The complete ABHA verification response, containing session tokens, user profile, and transaction details. |

Example:

const onSuccess = (params) => {
  console.log("ABHA Success:", params.response);

  const abhaNumber = params.response.data?.profile?.abha_number;
  const userName = params.response.data?.profile?.name;

  alert(`Welcome ${userName}! Your ABHA Number: ${abhaNumber}`);

  // Optionally pass data to native bridge if available
  if (window.EkaAbha) {
    window.EkaAbha.onAbhaSuccess(JSON.stringify(params));
  }
};

onKYCSuccess Callback

The onKYCSuccess callback is triggered when the ABHA KYC flow completes successfully. It returns a confirmation message indicating that the KYC has been verified.

Callback Signature:

onKYCSuccess: (params: TOnAbhaKycSuccessParams) => void;

Type Definitions

type TOnAbhaKycSuccess = string;

Parameters | | Type | Description | | ---------- | ----------------------- | ---------------------------------------------------------------------------------------------------------- | | TOnAbhaKycSuccess | string | A confirmation message from SDK post KYC verification |

Example:

const onKYCSuccess = (params) => {
  console.log("KYC verification Success:", params);

  alert("KYC was verified successfully!");

  // Optionally pass data to native bridge if available
  if (window.EkaAbha) {
    window.EkaAbha.onAbhaKYCSuccess(params);
  }
};

onConsentSuccess Callback

The onConsentSuccess callback is triggered when the ABHA Consent flow completes successfully. It returns a confirmation message indicating that the Consent flow ended successfully.

Callback Signature:

onConsentSuccess: (params: TOnAbhaConsentSuccessParams) => void;

Type Definitions

type TOnAbhaConsentSuccessParams = string;

Parameters | | Type | Description | | ---------- | ----------------------- | ---------------------------------------------------------------------------------------------------------- | | TOnAbhaConsentSuccessParams | string | A confirmation message from SDK post Consent flow completion |

Example:

const onConsentSuccess = (params) => {
  console.log("Consent Flow completed:", params);

  alert("Consent flow completed successfully!");

  // Optionally pass data to native bridge if available
  if (window.EkaAbha) {
    window.EkaAbha.onAbhaConsentSuccess(params);
  }
};

onError Callback

The onError callback is triggered whenever an ABHA flow fails or is interrupted. It provides details about the failure through structured parameters, allowing you to handle or forward the error appropriately (for example, to native apps or monitoring tools).

Callback Signature:

onError: (params: TOnAbhaFailureParams) => void;

Type Definitions

type TOnAbhaFailureParams = {
  error?: string;
  response?: TAuthVerifyV2Response;
};

type TAuthVerifyV2Response = {
  skip_state: number;
  method: AUTH_METHOD;
  data?: {
    tokens: {
      sess: string;
      refresh: string;
    };
    profile: TProfileRecord;
  };
  txn_id: string;
  error?: {
    code: number;
    message: string;
  };
};

enum AUTH_METHOD {
  EMAIL = 1,
  MOBILE = 2,
  ABHA = 7,
}

type TProfileRecord = {
  fln: string;
  fn: string;
  mn?: string;
  ln?: string;
  gen?: "M" | "F" | "O" | "U" | undefined; // 'male' | 'female' | 'other' | 'unknown'
  dob?: string;
  mobile?: string;
  email?: string;
  uuid?: string;
  bloodgroup?: "" | "A+" | "A-" | "B+" | "B-" | "O+" | "O-" | "AB+" | "AB-";
  pic?: string;
  as?: string;
  "dob-valid"?: boolean;
  "is-d"?: boolean;
  "is-d-s"?: boolean;
  "is-p"?: boolean;
  oid: string;
  at: string;
  type?: 1 | 2 | 3 | 4 | 5 | 6;
  "health-ids"?: Array<string>;
  abha_number?: string;
  kyc_verified?: boolean;
};

Parameters | Key | Type | Description | | ---------- | ------------------------ | ---------------------------------------------------------------- | | error | string? | Short description of the failure or error message. | | response | TAuthVerifyV2Response? | Partial or full API response object returned from ABHA services. |

Example:

const onError = (params) => {
  console.error("ABHA Error:", params);

  if (params.response?.error?.code === 1001) {
    alert("Authentication failed. Please try again.");
  } else if (params.error === "NETWORK_ERROR") {
    alert("Please check your internet connection.");
  } else {
    alert("Something went wrong. Please retry.");
  }

  // Forward the error to native handler if available
  if (window.EkaAbha) {
    window.EkaAbha.onAbhaFailure(JSON.stringify(params));
  }
};

onAbhaClose Callback

The onAbhaClose callback is triggered when the ABHA SDK flow gets closed.

Callback Signature:

onAbhaClose: () => void;

Example:

const onAbhaClose = () => {
  console.log("ABHA SDK Closed");
};

onSkipAbha Callback

The onSkipAbha callback is triggered when the ABHA SDK flow is skipped. The callback is functional when skipABHAEnable is set to true in the data parameter while initializing the SDK.

Callback Signature:

onSkipAbha: (params: TOnSkipABHA) => void;

Example:

const onSkipAbha = (params) => {
  console.log("ABHA SDK Skipped:", params);
};

Type Definitions

 type IdentifierType = "mobile" | "aadhaar_number" | "abha_number" | "phr_address";

 type TOnSkipABHA = {
  identifier?: string;
  identifier_type?: IdentifierType[]; // No default value here
};

Parameters | Key | Type | Description | | ---------- | ------------------------ | ---------------------------------------------------------------- | | identifier | string? | It will be login identifier value filled by user. | | identifier_type | IdentifierType[]? | It will be type of login identifier. |

Suggest Handling -Always log the full error response (params) for debugging. -Display friendly error messages for known error.code values. -If params.response is present, inspect response.error.message for more detail. -If integrating with native apps, forward the serialized error object:

window.EkaAbha.onAbhaFailure(JSON.stringify(params));

Customizing the Theme

The ABHA SDK supports full color-token overriding. You can pass a theme object during initialization to match your application's branding.

Default Theme Colors

If no theme is provided, the SDK uses the following default values:

const defaultAbhaColors = {
  semantic: {
    error: '#BD0F0F',
    warning: '#FCB069',
    success: '#27B961',
  },
  primary: {
    brand: '#6B5CE0', // Main buttons, radios, and active states
  },
  surface: {
    base: '#FFFFFF',      // Background of pages
    subtle: '#F2F4F7',    // Card backgrounds
    muted: '#E4E7EC',     // Dividers and borders
    strong: '#BEC5D0',
    success: '#D5F6E2',   // Success background alerts
    neutral: '#0000000D',
    danger: '#DD3F3F',
    abhaCard: '#232477',  // Specific background for the ABHA ID card
  },
  content: {
    primary: '#111B31',   // Heading and main text
    secondary: '#4B596D', // Subtext
    muted: '#9EA8B8',     // Disabled or placeholder text
    success: '#1B7E43',   // Success text
    enabled:"#ffffff",    // enabled button text color  
  },
  qrCodeColors: {
      fgColor: '#000000', // Color of the QR code dots
      bgColor: '#FFFFFF'  // Background of the QR code
  }
};

Overriding the theme

To customize the look, add the theme key to your initAbhaApp configuration:

window.initAbhaApp({
  containerId: "sdk_container",
  clientId: "ext",
  theme: {
    primary: {
      brand: '<your_org_primary_color', // brand color
    },
    semantic: {
      error: '<your_semantic_error_color>',
      warning: '<your_semantic_warning_color>',
      success: '<your_semantic_success_color>',
    },
    surface: {
      base: '<your_base_color>',      // Background of pages
      subtle: '<your_subtle_color>',    // Card backgrounds
      muted: '<your_muted_color>',     // Dividers and borders
      strong: '<your_strong_color>',
      success: '<your_success_color>',   // Success background alerts
      neutral: '<your_neutral_color>',
      danger: '<your_danger_color>',
      abhaCard: '<your_abhaCard_color>',  // Specific background for the ABHA ID card
    },
    content: {
      primary: '<your_content_primary_color>',   // Heading and main text
      secondary: '<your_content_secondary_color>', // Subtext
      muted: '<your_content_muted_color>',     // Disabled or placeholder text
      success: '<your_content_success_color>',   // Success text
      enabled:"<enabled_button_text_color>",    // enabled button text color
    },
    qrCodeColors: {
      fgColor: '<your_qrcode_dot_color>', // Color of the QR code dots
      bgColor: '<your_qrcode_bg_color>'  // Background of the QR code
    }
  },
  data: {
    orgIconUrl: "https://your-domain.com/logo.png",
    // ... rest of your data
  },
  onSuccess: (params) => { /* ... */ },
  onError: (params) => { /* ... */ }
  // ... other methods of initAbhaApp fn
});

Container Styling

Ensure your container has sufficient space:

<div
  id="sdk_container"
  style="width: 100%; height: 600px; border: 1px solid #ddd;"
></div>

Troubleshooting

Common Issues

1. SDK Not Rendering

Problem: Nothing appears in the container.

Solution:

Ensure containerId matches an existing HTML element.
Verify the SDK JS and CSS are correctly loaded.
Check browser console for errors.

2. APIs Not Being Called

Problem: API requests are not triggered after the SDK is mounted.

Solution:

Ensure that the accessToken is passed correctly (do not include the Bearer prefix) and that the token has not expired.
To prevent CORS-related issues, ensure that your domain is whitelisted.

3. Callback Not Triggered

Problem: onSuccess, onError, onKYCSuccess, onConsentSuccess, onAbhaClose isn’t firing.

Solution:

Make sure callbacks are passed as valid functions.
Avoid race conditions (e.g., calling before SDK fully loads).

4. Styling Issues

Problem: SDK content appears misaligned or clipped.

Solution:

Give your container a fixed height (e.g., 600px).
Ensure no parent element uses overflow: hidden.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ABHA SDK Implementation

Overview

Installation

Prerequisites

Setup

Core Functions

1. initAbhaApp

Callback Parameters

onSuccess Callback

onKYCSuccess Callback

onConsentSuccess Callback

onError Callback

onAbhaClose Callback

onSkipAbha Callback

Customizing the Theme

Default Theme Colors

Overriding the theme

Container Styling

Troubleshooting

Common Issues

1. SDK Not Rendering

2. APIs Not Being Called

3. Callback Not Triggered

4. Styling Issues