Assessment SDK (WLD)

A developer-friendly, fully whitelabeled SDK that lets you seamlessly integrate professional DISC behavioral assessments into any web application. Empower your platform with deep personality insights while maintaining your own brand identity—all with just a few lines of code.

📦 Installation

You can integrate the Assessment SDK in two primary ways: via NPM (for modern build pipelines) or via CDN (for direct browser usage).

Method 1: NPM Installation

Recommended for React, Vue, Angular, or any project using a bundler (Webpack, Vite, Rollup).

npm install wld-assessment-sdk
# or
yarn add wld-assessment-sdk

Method 2: CDN Link

Ideal for simple HTML pages or legacy projects without a build step.

<script src="https://unpkg.com/wld-assessment-sdk/dist/sdk/assessment-sdk.umd.cjs"></script>

🚀 Quick Start & Integration

The SDK provides multiple ways to initialize and interact with the assessments.

A. Integration via NPM (ES Modules)

Best for modern JavaScript/TypeScript applications.

import AssessmentSDK from 'wld-assessment-sdk';

const sdk = AssessmentSDK.init({
  apiKey: 'import.meta.env.VITE_WLD_API_KEY' // Recommended: use environment variables
});

B. Integration via NPM (CommonJS)

For older Node.js environments or build setups using require.

const AssessmentSDK = require('wld-assessment-sdk');

const sdk = AssessmentSDK.init({
  apiKey: 'import.meta.env.VITE_WLD_API_KEY'
});

C. Integration via CDN (Global Object)

The SDK is automatically attached to the window object.

// Access via window.AssessmentSDK
const sdk = window.AssessmentSDK.init({
  apiKey: 'YOUR_API_KEY' // ⚠️ Environment variables are not available when using CDN directly.
});

🖥️ Display Modes

Once initialized, you can choose how the assessment appears to the user.

1. Iframe Mode (Embedded)

Embed the assessment directly into your page layout within a specified container.

sdk.show({
  containerId: 'my-assessment-div', // The ID of your <div>
  name: 'John Doe',
  email: '[email protected]',
  userExternalId: 'unique_user_id',
  onComplete: () => console.log('Assessment Finished!')
});

2. Popup Mode (Separate Window)

Open the assessment in a new browser window. This is useful if you want to keep your main application state intact.

sdk.open({
  name: 'John Doe',
  email: '[email protected]',
  userExternalId: 'unique_user_id',
  width: 900,
  height: 700
});

⚛️ React Integration Example

import React, { useEffect, useRef } from 'react';
import AssessmentSDK from 'wld-assessment-sdk';

export const DiscAssessment = () => {
  const isInitialized = useRef(false);

  useEffect(() => {
    if (!isInitialized.current) {
      // Use your framework's env prefix (e.g., REACT_APP_, VITE_, NEXT_PUBLIC_)
      const sdk = AssessmentSDK.init({ apiKey: 'import.meta.env.VITE_WLD_API_KEY' });
      
      sdk.show({
        containerId: 'disc-container',
        name: 'Alex Rivera',
        email: '[email protected]',
        userExternalId: 'emp_99',
        onStart: (msg) => console.log("Started:", msg),
        onProgress: (p) => console.log(`Progress: ${p.percentage}%`),
        onError: (err) => console.error(`Error [${err.code}]: ${err.message}`),
        onSaveAnswer: (data) => console.log(`Saved answer for ${data.question.questionText}`),
        onComplete: (msg) => alert(msg),
        onExit: (msg) => console.log("User Exited:", msg)
      });

      isInitialized.current = true;
    }
  }, []);

  return (
    <div style={{ padding: '20px' }}>
      <h2>Complete Your Profile</h2>
      <div id="disc-container" style={{ border: '1px solid #ddd' }} />
    </div>
  );
};

⚙️ API Reference

🛠️ Methods Overview

• AssessmentSDK.init(config): Initializes the SDK with your API key.
• sdk.show(options): Embeds an iframe in a specific container.
• sdk.open(options): Opens a popup window.
• sdk.destroy(): Removes iframe and cleans up all event listeners.
• sdk.getAssessmentUrl(options): Returns the assessment URL string (Promise).

AssessmentSDK.init(config)

| Param | Type | Required | Description | | :--- | :--- | :--- | :--- | | apiKey | string | Yes | Your SDK API key. |

sdk.show(options) / sdk.open(options)

| Param | Type | Required | Description | | :--- | :--- | :--- | :--- | | name | string | No | User's display name. | | email | string | No | User's email address. | | userExternalId | string | Yes* | Your external user ID (for tracking). | | url | string | No | Bypass API and load a specific assessment URL. | | containerId | string | Yes (show)| The target element ID for the iframe. | | width | string\|num| No | Width (default: 100% / 900px). | | height | string\|num| No | Height (default: 600px / 700px). | | onComplete | function | No | Returns a completion message string. | | onClose | function | No | Returns a window closure message string. | | onSaveAnswer| function | No | Returns full question & answer details. | | onStart | function | No | Triggered when the user clicks 'Start'. Returns a message. | | onProgress | function | No | Triggered after every answer. Returns progress object. | | onExit | function | No | Triggered when user logs out/exits. Returns a message. | | onError | function | No | Triggered on failures (Auth, API, etc). Returns error object. |

* Required if no url is provided.

🔒 Data Privacy: Any PII (like name and email) passed to the SDK is secured with database-level encryption and is strictly private. This data is never visible to unauthorized parties or shared externally.

🏗️ Event Payloads

onSaveAnswer

{
  question: { questionId: string; questionText: string; },
  answer: { optionId: string; optionText: string; }
}

onProgress

{
  current: number;    // Number of questions answered
  total: number;      // Total questions in assessment
  percentage: number; // Percentage complete (0-100)
}

onError

{
  code: string;    // See possible codes below
  message: string; // Human readable error message
  details?: any;   // Extra debugging info if available
}

Possible Error Codes (err.code):

• "INIT_ERROR": The SDK failed to initialize before the assessment could load.
• "UNAUTHORIZED": Authentication failed or the user's session expired (e.g., invalid API key).
• "QUESTION_LOAD_FAILED": The assessment loaded, but failed to fetch the question data.
• "ANSWER_SAVE_FAILED": The user selected an answer, but it failed to save to the database.
• "RESULT_LOAD_FAILED": The assessment was completed, but the final results page failed to load.

🧩 Troubleshooting

Assessment not loading

Ensure:

• apiKey is valid
• containerId exists in the DOM
• Your domain is allowed for embedding

iframe container not found

Make sure the container element exists before calling sdk.show().

Example:

<div id="my-assessment-div"></div>

Popup blocked

Some browsers block popups. Ensure the sdk.open() call happens inside a user action (e.g., inside an onClick event handler).

🌐 Browser Support

The SDK supports all modern browsers:

| Browser | Supported | |--------|----------| | Chrome | ✅ | | Firefox | ✅ | | Safari | ✅ | | Edge | ✅ |

Minimum supported versions follow the latest two major releases.

💬 Support & License

Support For integration issues or questions:

• Email: [email protected]
• Website: https://whitelabeldisc.com

License ISC © psingh