` with this ID is created and appended to `document.body`. |
| `accessToken` | `string` | ✅ | Short-lived Bearer token for authenticating API calls to Eka's backend. Generate a fresh token from your backend on each widget load. Do not include the `Bearer` prefix. |
| `clientId` | `string` | ⚙️ Optional | Client identifier for your application. Pass `"ext"` for web integrations. Defaults to `"ext"`. |
| `hideEkaSidePanel` | `boolean` | ⚙️ Optional | Hide the decorative illustration panel shown on larger screens. Defaults to `false`. Set to `true` when embedding in a narrow modal or a mobile WebView. |
| `showDashboardOnSuccess` | `boolean` | ⚙️ Optional | If `true`, navigates to the ABDM dashboard after HFR registration is complete. If `false`, the widget unmounts itself after firing `onAbdmOnboardSuccess`. Defaults to `true`. |
| `onAbdmMountSuccess` | `(params: TOnAbdmMountSuccess) => void` | ⚙️ Optional | Fired immediately after the widget mounts successfully. |
| `onAbdmOnboardSuccess` | `(params: TOnAbdmOnboardSuccess) => void` | ✅ | Fired when HPR and HFR registration both complete. Contains the new HPR ID and HFR Facility ID. |
| `onAbdmDashboardClose` | `(params: TOnAbdmDashboardClose) => void` | ✅ | Fired when the user closes the widget via the back button or when `unmountABDMDashboard` is called. |
| `onAbdmDashboardError` | `(params: TOnAbdmDashboardError) => void` | ✅ | Fired if the widget fails to mount or encounters a fatal error. |
### 2. unmountABDMDashboard
Programmatically unmounts the widget and cleans up the React root.
```js theme={null}
window.abdmDashboardUnmount("abdm-dashboard-root");
```
Returns `true` if the widget was found and unmounted, `false` if no mounted widget was found at the given element ID.
***
## Callback Parameters
### onAbdmMountSuccess Callback
Fired immediately after the widget mounts and renders successfully into the container.
**Callback Signature:**
```typescript theme={null}
onAbdmMountSuccess: (params: TOnAbdmMountSuccess) => void;
```
**Type Definition:**
```typescript theme={null}
type TOnAbdmMountSuccess = {
clientId?: string;
};
```
**Parameters:**
| Key | Type | Description |
| ---------- | --------- | ---------------------------------------------- |
| `clientId` | `string?` | The `clientId` passed to `mountABDMDashboard`. |
**Example:**
```javascript theme={null}
const onAbdmMountSuccess = (params) => {
console.log("NHPR SDK mounted:", params);
// params.clientId → "ext"
// Show the container now that the widget is ready
document.getElementById("abdm-dashboard-root").style.display = "block";
};
```
***
### onAbdmOnboardSuccess Callback
Fired when the full HPR + HFR onboarding flow completes successfully. This is the primary callback — use it to persist the HPR ID and HFR Facility ID to your backend.
**Callback Signature:**
```typescript theme={null}
onAbdmOnboardSuccess: (params: TOnAbdmOnboardSuccess) => void;
```
**Type Definition:**
```typescript theme={null}
type TOnAbdmOnboardSuccess = {
clientId?: string;
facilityId?: string;
createdHprId?: string;
};
```
**Parameters:**
| Key | Type | Description |
| -------------- | --------- | ------------------------------------------------------------------------------------------------------------- |
| `clientId` | `string?` | The `clientId` passed to `mountABDMDashboard`. |
| `facilityId` | `string?` | The HFR Facility ID assigned by ABDM to the registered clinic. Store this against the clinic in your backend. |
| `createdHprId` | `string?` | The doctor's new HPR ID in the format `username@hpr.abdm`. Store this against the doctor in your backend. |
**Example:**
```javascript theme={null}
const onAbdmOnboardSuccess = (params) => {
console.log("Onboarding complete:", params);
const { facilityId, createdHprId } = params;
// Persist to your backend
fetch("/api/abdm/save-registration", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ facilityId, createdHprId }),
});
// Unmount and hide the widget
window.abdmDashboardUnmount("abdm-dashboard-root");
// Optionally pass to native bridge if running in a WebView
if (window.EkaAbdm) {
window.EkaAbdm.onAbdmOnboardSuccess(JSON.stringify(params));
}
};
```
***
### onAbdmDashboardClose Callback
Fired when the user explicitly closes the widget (by clicking the back/close button) or when `unmountABDMDashboard` is called programmatically.
**Callback Signature:**
```typescript theme={null}
onAbdmDashboardClose: (params: TOnAbdmDashboardClose) => void;
```
**Type Definition:**
```typescript theme={null}
type TOnAbdmDashboardClose = {
clientId: string;
};
```
**Parameters:**
| Key | Type | Description |
| ---------- | -------- | ------------------------------------------------------------------------------------------------ |
| `clientId` | `string` | The `clientId` passed to `mountABDMDashboard`. Falls back to `"default-client"` if not provided. |
**Example:**
```javascript theme={null}
const onAbdmDashboardClose = (params) => {
console.log("NHPR SDK closed:", params);
// Hide or remove the container from the UI
const container = document.getElementById("abdm-dashboard-root");
if (container) container.style.display = "none";
// Optionally pass to native bridge if running in a WebView
if (window.EkaAbdm) {
window.EkaAbdm.onAbdmClose(JSON.stringify(params));
}
};
```
***
### onAbdmDashboardError Callback
Fired if the widget fails to mount or encounters a fatal error during initialisation.
**Callback Signature:**
```typescript theme={null}
onAbdmDashboardError: (params: TOnAbdmDashboardError) => void;
```
**Type Definition:**
```typescript theme={null}
type TOnAbdmDashboardError = {
clientId?: string;
};
```
**Parameters:**
| Key | Type | Description |
| ---------- | --------- | --------------------------------------------- |
| `clientId` | `string?` | The `clientId` passed to `mountABDMDashboard` |
**Example:**
```javascript theme={null}
const onAbdmDashboardError = (params) => {
console.error("NHPR SDK error:", params);
alert("Something went wrong while loading the onboarding widget. Please try again.");
// Forward to native bridge if running in a WebView
if (window.EkaAbdm) {
window.EkaAbdm.onAbdmError(JSON.stringify(params));
}
};
```
**Suggested handling:**
* Always log the full `params` for debugging.
* Display a user-friendly retry prompt — the most common causes are an expired `accessToken` or a network failure.
* Generate a fresh `accessToken` from your backend before retrying `mountABDMDashboard`.
***
## Onboarding Flow (M4)
The widget is a linear multi-step flow. Each step is a full-screen state — the user cannot jump ahead.
### Screen reference
| Step | Screen | What happens |
| ---- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | **Create** | Doctor enters their 12-digit Aadhaar number. An OTP is dispatched to the Aadhaar-linked mobile on submit. |
| 2 | **Verify OTP** | Doctor enters the OTP received on their Aadhaar-linked mobile number to complete identity verification. |
| 3 | **Setup HPR** | Doctor sets a unique HPR ID (ABDM-suggested IDs are shown as chips), practice type, email, password, and pincode. Real-time availability check runs on HPR ID input. |
| 4 | **HPR Successful** | Confirmation that the HPR ID has been created. The flow auto-advances to clinic verification. |
| 5 | **Verify Clinic** | Doctor selects a suggested ABDM facility or registers a new clinic with type, sub-type, medicine type, and facility details. |
| 6 | **HFR Successful** | HFR registration is confirmed. `onAbdmOnboardSuccess` fires with `createdHprId` and `facilityId`. |
### Practice types
| Code | Name |
| ---- | --------------- |
| 1 | Modern Medicine |
| 2 | Dentist |
| 3 | Ayurveda |
| 4 | Unani |
| 5 | Siddha |
| 6 | Homeopathy |
| 89 | Sowa-Rigpa |
### HPR password requirements
The widget validates the password live as the doctor types. All rules must pass before the form can be submitted:
* At least 8 characters
* At least one uppercase letter
* At least one lowercase letter
* At least one number
* At least one special character
***
## OTP Auto-Read (Mobile WebView)
If your application embeds the widget in a mobile WebView that supports OTP interception, forward the OTP to the widget:
```js theme={null}
// Call this from your Android/iOS bridge when an OTP SMS is intercepted
window.onOtpAutoRead({ success: true, otp: "123456" });
```
The widget pre-fills the OTP input automatically and does not require the doctor to type it.
***
## Container Styling
Ensure your container has sufficient height for the widget to render correctly:
```html theme={null}
```
For full-screen modal use cases, set the container to `100vw` / `100vh` and pass `hideEkaSidePanel: true` to disable the side illustration panel on smaller viewports.
***
## API Reference
The widget communicates with Eka's backend. All requests include your `accessToken` as a Bearer token in the `Authorization` header.
| Method | Endpoint | Purpose |
| ------ | ----------------------------- | -------------------------------------------------- |
| `POST` | `/abdm/v1/hpr/aadhaar/otp` | Initiate Aadhaar OTP for HPR identity verification |
| `POST` | `/abdm/v1/hpr/aadhaar/verify` | Verify the Aadhaar OTP |
| `POST` | `/abdm/v1/hpr/mobile/verify` | Verify the mobile OTP |
| `POST` | `/abdm/v1/hpr/id/available` | Check if a chosen HPR ID is available |
| `POST` | `/abdm/v1/hpr/create` | Create the HPR entry with ID and credentials |
| `POST` | `/abdm/v1/hfr/create` | Register the clinic as a new HFR facility |
| `POST` | `/abdm/v1/hfr/link` | Link the clinic to an existing HFR facility |
**Base URLs:**
| Environment | Base URL |
| ----------- | -------------------------- |
| Production | `https://api.eka.care` |
| Development | `https://api.dev.eka.care` |
***
## Troubleshooting
### Common Issues
#### 1. SDK Not Rendering
**Problem**: Nothing appears in the container.
**Solution**:
* Ensure `elementId` matches an existing HTML element ID.
* Verify the SDK JS and CSS files are loaded before calling `mountABDMDashboard`.
* Check the browser console for errors.
#### 2. APIs Not Being Called
**Problem**: API requests are not triggered after the SDK is mounted.
**Solution**:
* Ensure `accessToken` is passed correctly and has not expired — generate a fresh token from your backend on each mount.
* Ensure your domain is whitelisted with Eka Care to prevent CORS errors.
#### 3. Callbacks Not Firing
**Problem**: `onAbdmOnboardSuccess`, `onAbdmDashboardClose`, or `onAbdmDashboardError` are not being called.
**Solution**:
* Confirm callbacks are passed as valid functions, not strings or undefined.
* Avoid calling `unmountABDMDashboard` before the SDK has finished its flow — this will silently stop all further callbacks.
#### 4. Styling Issues
**Problem**: SDK content appears misaligned or clipped.
**Solution**:
* Give your container a fixed height (e.g., `600px`) or `100vh` for full-screen.
* Ensure no parent element applies `overflow: hidden` that would clip the widget.
* Pass `hideEkaSidePanel: true` on narrow viewports (under 768 px).
***
## Frequently Asked Questions
An HPR (Health Professional Registry) ID is a unique digital identity for healthcare professionals in India's ABDM ecosystem. It is required for a doctor to participate in ABDM-enabled workflows such as linking patient health records and issuing digital prescriptions.
HFR (Healthcare Facility Registry) registers a clinic or hospital within ABDM. It is required for the clinic to act as a Health Information Provider (HIP) and exchange records through the ABDM network. The NHPR SDK handles both HPR and HFR registration in a single flow.
Store both in your backend against the respective doctor and clinic records. The `facilityId` is the HFR ID assigned by ABDM to the clinic. The `createdHprId` is the doctor's new HPR ID in the format `username@hpr.abdm`. You will need these IDs for subsequent ABDM API calls.
Pass `hideEkaSidePanel: true` to collapse the side illustration panel for narrow screens. Wire up your native OTP-intercept handler to call `window.onOtpAutoRead({ success: true, otp: '...' })` so the OTP field is filled automatically.
The current M4 flow creates a new HPR ID via Aadhaar-based identity verification. If the doctor already has an HPR ID registered with ABDM, contact Eka support to enable the existing-HPR linking flow for your integration.