Skip to main content

JavaScript SDK

The Positive User JavaScript SDK is a client-side JavaScript library (widget.js) that facilitates bidirectional communication between your application and the Positive User platform. It is the foundational layer for analytics tracking, contact identification, and the Chat Widget interface.

What the SDK does​

The JavaScript SDK serves three core responsibilities when loaded in a browser environment:

  1. Tracking: Automatically captures anonymous page views, device fingerprints, and contact session activity.
  2. Identification: Resolves contact identity via cookies (__ca__chat) or explicit authentication (User ID/Email), and switches tracking between anonymous and known contact profiles.
  3. Engagement: Injects and renders the Positive User Widget, which can display pop-ups, automations, and — if enabled — a live chat interface.

It is designed as a lightweight, standalone library injected directly into your website's source code.

Capabilities & scope​

Understanding the boundaries of the SDK ensures correct implementation.

What it CAN do​

  • Auto-Tracking: Automatically tracks page visits (Page Hits) and technical metadata (Browser, OS, IP-based location).
  • Cookie Management: Generates and manages the __ca__chat cookie to persist contact identity across sessions.
  • Dynamic Injection: Asynchronously loads the Chat Widget iframe and UI components based on dashboard settings.
  • Event Handling: Provides methods to send Custom events and Product events to Positive User.

What it CANNOT do​

  • Server-Side Rendering (SSR): The SDK is strictly a client-side tool. It relies on window and document objects and cannot run in Node.js environments (e.g., Next.js server components).
  • Offline Queueing: Events triggered while the contact is offline are not queued; a reliable internet connection is required for data transmission.
  • SPA Routing (Automatic): While it tracks the initial load, Single Page Applications (React, Vue, Angular) require specific configuration to track route changes. See Single-page applications.

The two interfaces​

The SDK uses two distinct global objects. Understanding the difference is key to preventing race conditions.

window.civchat (Configuration)​

This is a static configuration object. You define it before the script loads. It is used only during initialization to pass your API Key and initial contact attributes.

UE & userengage (Runtime API)​

These are the runtime interfaces available after the SDK has loaded.

  • UE: The global object containing state methods (e.g., UE.pageHit()).
  • userengage(): The global function used to trigger events (e.g., userengage('event.my_event')).
  • Reference: All methods

Where to start​

  1. Installation — prerequisites, the script snippet, and how to verify the SDK loaded.
  2. Configuration — every window.civchat property and callback.
  3. Contact identification — turn anonymous traffic into known contacts.
  4. Custom events — send behavioral data to Positive User.
  5. All methods — the full runtime API reference.