Skip to main content

Install the JavaScript SDK

This page covers installing the SDK: the environment prep it needs, the snippet to paste, and how to confirm it works. For what the SDK is and how its two interfaces fit together, see the JavaScript SDK overview.

Prerequisites​

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

1. Domain whitelisting​

By default, Positive User 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.

DirectiveRequired Domains
script-srchttps://*.user.com, https://media.user.com, https://widget.user.com
connect-srchttps://*.user.com, wss://*.user.com (for WebSockets)
img-srchttps://*.user.com, https://media.user.com, https://static.user.com, https://media.tenor.com
frame-srchttps://*.user.com
media-srchttps://*.user.com

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.

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.

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

<!-- Positive User 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 > Workspace 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.

The snippet above sets the minimum — your API key. The same window.civchat object also accepts initial contact attributes and callbacks; see Configuration (window.civchat) for the full property list.

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 contact identification data.

Using React, Vue or Angular? The checks above only confirm the initial page load. In a single-page application, route changes are not tracked until you call UE.pageHit() on navigation — without it, every page view after the first is silently missing. See Single-page applications.

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.