Admission AI SDK

A robust, client-side JavaScript SDK to track user engagement and capture parent leads on school websites, wrapping the Admission AI Platform backend APIs.

Features

• Anonymous Identity: Automatically creates and manages a permanent, unique visitor UUID (admission_ai_visitor_id) using browser local storage.
• Session Lifecycles: Monitors transient session activity (admission_ai_session_id) with automatic 30-minute inactivity timeouts and extends session lifespan on user actions.
• Automatic Event Tracking: Unobtrusively tracks page views, button clicks, links, downloads, scroll depths (50% and 90%), page exit metrics, and time-on-page.
• Single Page Application (SPA) Support: Automatically intercepts History API state transitions (pushState, replaceState, and popstate) to record virtual page navigations.
• Lead Capture Submission: Automatically attaches session information, visitor IDs, browser environment traits, and metadata to lead registration requests to /api/parents.
• Fault Tolerance: Captures all internal network and execution failures silently to prevent interrupting host scripts unless debug is activated.

Project Structure

admission-ai-sdk/
├── dist/
│   ├── admission-ai-sdk.min.js      # Production-ready minified bundle
│   └── admission-ai-sdk.min.js.map  # Sourcemap for debugging
├── examples/
│   ├── html/
│   │   └── index.html               # Plain HTML demo page
│   └── react/
│       └── Demo.jsx                 # React demo integration component
├── src/
│   ├── api.js                       # Axios API client wrapper with interceptors
│   ├── config.js                    # Global configuration state and logger
│   ├── constants.js                 # Shared constants and storage keys
│   ├── index.js                     # Global entry point
│   ├── session.js                   # Session tracker and duration calculator
│   ├── storage.js                   # Fault-tolerant browser storage utility
│   ├── tracker.js                   # Core event capturing and binding engine
│   ├── utils.js                     # User agent detectors and debounce helpers
│   └── visitor.js                   # Unique visitor identity manager
├── package.json                     # NPM configuration & dependencies
└── rollup.config.js                 # Rollup compilation bundler rules

Installation & Setup

CDN (Browser Integration)

Include the minified script tag in your website header or footer:

<script src="https://cdn.company.com/admission-ai-sdk.min.js"></script>

Initialize the global instance:

<script>
  AdmissionAI.init({
    apiUrl: "https://api.schoolsite.com", // Base URL of the Express server
    schoolId: "school_001",              // School identifier
    apiKey: "your-api-key-here",          // Authentication key
    debug: true                           // Print logs to console
  });
</script>

ES Modules (NPM / Package Manager)

Import and initialize the module in your modern client application bundle:

import AdmissionAI from 'admission-ai-sdk';

AdmissionAI.init({
  apiUrl: "https://api.schoolsite.com",
  schoolId: "school_001",
  apiKey: "your-api-key-here",
  debug: false
});

API Reference

Configuration Parameters

The init(options) call accepts the following object properties:

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | apiUrl | String | 'http://localhost:3000' | Base URL of the Express server. Trailing slashes are cleaned automatically. | | schoolId | String | '' | Custom identifier representing the school site. | | apiKey | String | '' | Authentication key attached to outgoing API requests. | | debug | Boolean | false | When true, errors and operations are logged to the console. When false, fails silently. |

Public Methods

AdmissionAI.init(options)

Configures the SDK parameters, resolves visitor identity, verifies session states, and binds global document listeners.

AdmissionAI.track(params)

Manually logs custom actions to the database. Resolves to a promise.

AdmissionAI.track({
  eventType: "fees_viewed", // Must be one of the accepted EVENT_TYPES
  metadata: {
    grade: "Grade 11",
    curriculum: "IB"
  }
});

AdmissionAI.captureLead(leadData)

Submits parent registration form fields. Returns a Promise carrying the backend response.

AdmissionAI.captureLead({
  name: "John Doe",
  email: "[email protected]",
  phone: "+1234567890",
  city: "San Francisco",
  grade: "Grade 5",
  curriculum: "CBSE"
});

AdmissionAI.identify(userId, traits)

Binds a unique logged-in identifier (like email or student code) and related properties to all future event logs during the session.

AdmissionAI.identify("parent_user_102", {
  portalUsername: "john_doe_parent",
  membership: "Alumni"
});

AdmissionAI.getVisitorId()

Returns the persistent anonymous visitor UUID string (admission_ai_visitor_id).

AdmissionAI.getSessionId()

Returns the transient session UUID string (admission_ai_session_id).

AdmissionAI.reset()

Clears all SDK credentials, identity tokens, and session details from the browser.

Tracking Mechanics

Supported Event Types

The backend accepts the following event types. The SDK maps automatic client interactions to these values:

• website_opened: Broadcast once per session on page load.
• page_view: Triggered on standard load and virtual route navigation.
• button_click: Logged when buttons or text links are clicked.
• brochure_download: Broadcast when a PDF link click is intercepted.
• scroll_50: Logged when the visitor scrolls past 50% height.
• scroll_90: Logged when the visitor scrolls past 90% height.
• curriculum_viewed / fees_viewed / faq_expanded: Shared custom events.
• enquiry_submitted: Broadcast automatically upon successful lead capture.

Environmental Payloads

The SDK captures browser context automatically. Every request dispatched to /api/events carries the following structure:

{
  "visitorId": "uuid-v4-string",
  "eventType": "page_view",
  "page": "/admissions/fees",
  "metadata": {
    "sessionId": "session-uuid-v4",
    "schoolId": "school_001",
    "timestamp": "2026-07-17T17:00:00.000Z",
    "referrer": "https://google.com",
    "browser": "Chrome",
    "device": "Desktop",
    "userId": "parent_user_102",          // If identified
    "userTraits": { "membership": "Alumni" } // If identified
  }
}