# Getting started with JavaScript SDK

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

# Intoduction

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

1. Tracking: Automatically captures anonymous page views, device fingerprints, and user session activity.
2. Identification: Resolves user identity via cookies (__ca__chat) or explicit authentication (User ID/Email), merging anonymous history with known user profiles.
3. Engagement: Injects and renders the User.com Chat Widget, enabling real-time communication, pop-ups, and automations.

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 user identity across sessions.
• Dynamic Injection: Asynchronously loads the Chat Widget iframe and UI components based on dashboard settings.
• Event Handling: Sends Custom Events (e.g., "Product Added", "Form Submitted") to User.com triggers.

# 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 user 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 SPA Documentation.

# Prerequisites

Before implementing the code, ensure your environment is configured to allow the SDK to communicate with User.com servers.

# 1. Domain whitelisting

By default, User.com allows connection from any domain (*). However, for security, we strongly recommend restricting this to your specific domains.

1. Go to Settings > Setup & Integrations > Integration Settings.
2. Add your production and staging domains (e.g., example.com and staging.example.com).
3. Critical: If you use www, add it explicitly (e.g., www.example.com).
4. Remove the wildcard (*) entry once your domains are added.

# 2. Content Security Policy (CSP)

If your application uses a strictly defined Content Security Policy, you must allow the following directives to prevent the browser from blocking the widget.

# 3. Third-party optimizations

• Cloudflare Rocket Loader: The SDK script tag requires the data-cfasync="false" attribute to prevent Cloudflare from deferring the load incorrectly.

# Configuration concepts

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 user attributes.

• Role: Setup & Auth
• Timing: Define before widget.js loads.

# 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')).

# Implementation

To install the SDK, inject the following snippet into your application's HTML.

# Basic snippet

Place this code immediately before the closing </body> tag.

<!-- User.com SDK Configuration -->
<script data-cfasync="false" type="text/javascript">
  window.civchat = {
    apiKey: "YOUR_API_KEY"
  };
</script>

<!-- User.com SDK Loader -->
<script data-cfasync="false" type="text/javascript" src="https://YOUR_SUBDOMAIN.user.com/widget.js"></script>

# Implementation details

1. YOUR_API_KEY: Found in Settings > Worksspace Settings > API & Integrations > Setup & Integrations.
2. YOUR_SUBDOMAIN: You must use your specific application subdomain (e.g., app.user.com). Generic URLs will not route data correctly.
3. data-cfasync="false": Required to bypass Rocket Loader.

# Verification

After installation, verify the integration using the Browser Developer Tools.

# 1. Console verification

Open the browser console (F12) and type:

civchat

Success: Returns an object containing your apiKey and an assigned userKey. Failure: Returns undefined (Script did not load).

# 2. Network verification

Go to the Network tab and filter for chatping. Refresh the page.

• Look for: A request to https://<your-subdomain>.user.com/api/v2/user-chatping/
• Status: 200 OK
• Payload: The response will contain user identification data.

# 3. Troubleshooting common errors

# HTTP 400 Bad Request

If the Network tab shows a 400 error for the user-chatping request, check the response body.

• Cause: Typically an invalid or malformed apiKey.
• Example Response: {"apiKey":["...invalid length..."]}
• Fix: Verify the API Key in your dashboard matches window.civchat.

# Chat widget not appearing

• Check settings: Ensure the widget is not globally disabled in Customer Service > Chat widget.
• Check CSP: Look for red "Content Security Policy" errors in the Console.