@cognior/iap-sdk

v0.2.8

Published

4 days ago

Intelligent Adoption Platform (IAP) JavaScript/TypeScript SDK for creating guided user experiences, tours, tooltips, modals, and surveys across web applications

0High
0Medium
0Low

cogniorai

cognior-satheesh

intelligent-adoption digital-adoption user-onboarding guided-tours tooltips modals user-experience sdk cognior

Intelligent Adoption Platform (IAP) SDK

A framework-agnostic JavaScript/TypeScript SDK for creating interactive user flows, onboarding experiences, tooltips, modals, surveys, and walkthroughs in web applications.

This README is for end users integrating the SDK from the npm registry.

Overview

The DAP SDK enables developers to create guided user experiences driven by backend-defined Flow JSON configurations. It provides a comprehensive suite of UI components and interaction patterns that help users navigate and learn your application.

Architecture: Backend Flow Engine → DAP SDK → Interactive UI Components

Typical Use Cases

User Onboarding: Step-by-step guided tours for new users
Feature Discovery: Interactive tooltips and hotspots highlighting new features
Contextual Help: Smart assistance based on user location and behavior
Surveys & Feedback: In-app surveys and micro-surveys for user insights
Task Guidance: Walkthrough workflows and complex processes
Knowledge Base: Embedded help content and documentation

Features

Core Capabilities

✅ Step-based Flow System: Linear and AnyOrder execution models
✅ Mandatory vs Optional Steps: Flexible flow completion requirements
✅ Advanced Trigger System: DOM, Input, Lifecycle, and Time-based triggers
✅ Rule-based Branching: Dynamic flow paths based on user input
✅ Multi-page Support: Seamless flows across SPAs and traditional pages
✅ Real-time Analytics: Comprehensive telemetry and user behavior tracking
✅ One-time vs Recurring: Configurable flow frequency and targeting

UI Components

Modals: Rich content modals with dragging, resizing, and accessibility
Tooltips: Contextual help tooltips with smart positioning
Popovers: Interactive popovers with custom content
Banners: Page-level announcements and notifications
Hotspots: Visual indicators for interactive elements
Surveys: Inline and modal survey components
Walkthroughs: Multi-step guided tours
Task Lists: Interactive checklists and progress tracking

Browser & Platform Support

Modern Browsers: Chrome 80+, Firefox 75+, Safari 13+, Edge 80+
SPA Compatibility: React, Angular, Vue, Svelte, and vanilla JavaScript
MPA Support: Traditional multi-page applications
Mobile: Responsive design with touch support
Accessibility: WCAG 2.1 AA compliant components

Install

npm install @cognior/iap-sdk
# or
yarn add @cognior/iap-sdk

What you need to integrate

1) A configuration endpoint (`configUrl`) (required)

You must provide a URL that returns the IAP configuration JSON.

Example response:

{
  "organizationid": "your-org-id",
  "siteid": "your-site-id",
  "apikey": "your-api-key",
  "apiurl": "https://api.yourcompany.com",
  "enableDraggableModals": true
}

2) Initialization in your app (required)

Initialize once (typically on app startup) and pass configUrl.

Usage (recommended): ES Modules (Webpack/Vite/Rollup)

import { init, setUser } from "@cognior/iap-sdk";

await init({
  configUrl: "https://api.yourcompany.com/config",
  debug: false
});

// Optional: set user context for targeting and analytics
setUser({
  id: "user_123",
  role: "admin",
  email: "[email protected]",
  attributes: {
    department: "engineering"
  }
});

Usage: CommonJS

const { init, setUser } = require("@cognior/iap-sdk");

init({
  configUrl: "https://api.yourcompany.com/config"
}).then(() => {
  setUser({ id: "user_123" });
});

Usage: Script tag (UMD)

If you can’t use bundlers/modules, you can load the UMD build and access the global variable.

<!doctype html>
<html>
  <head>
    <script src="https://unpkg.com/@cognior/iap-sdk@latest/dist/index.umd.js"></script>
  </head>
  <body>
    <script>
      window.addEventListener("DOMContentLoaded", async () => {
        await window.DAP.init({
          configUrl: "https://api.yourcompany.com/config",
          debug: false
        });

        window.DAP.setUser({
          id: "user_123",
          role: "user"
        });
      });
    </script>
  </body>
</html>

Note: the UMD build exposes a global DAP variable (as shown above). This is part of the runtime API.

API (common integration points)

`init(opts)` (required)

Initializes the SDK.

init(opts: {
  configUrl: string;
  debug?: boolean;
  screenId?: string;
  user?: {
    id: string;
    role?: string;
    email?: string;
    attributes?: Record<string, string>;
  };
}): Promise<void>;

User context (optional but recommended)

Use user context to enable personalized experiences and better analytics.

import { setUser, updateUser, getUser, clearUser } from "@cognior/iap-sdk";

setUser({ id: "user_123", role: "admin" });

updateUser({
  attributes: { subscription_tier: "pro" }
});

console.log(getUser());

clearUser(); // on logout

Integration guidance

Single Page Apps (React/Angular/Vue/etc.)

Initialize once on app startup.
Set/clear user context when auth state changes.

Multi Page Apps

Initialize on each page load (e.g., DOMContentLoaded).

Selector best practices (for experiences that target elements)

Use stable selectors where possible (e.g., data-* attributes) to avoid breakage when CSS classes change.

<button data-iap="onboarding-next">Next</button>

Build outputs (what you get when installed)

dist/index.esm.js — ES Module build
dist/index.cjs.js — CommonJS build
dist/index.umd.js — UMD build (script tag / global)
dist/index.d.ts — TypeScript definitions

License

See LICENSE.