Use init() to configure the Userorbit browser SDK once when your application is ready to load it. This reference covers the main installation, identity, and collection options, plus their limits.

Basic initialization

import userorbit from "userorbit-js";

await userorbit.init({
  accountId: "YOUR_ACCOUNT_ID",
});
JavaScript

Run this in the browser. In an application that requires permission before loading analytics or engagement tools, your application owns that loading decision.

The Account ID is the public installation identifier. Do not put a Userorbit API key, signing secret, or application access token in browser initialization.

Installation and identity options

Option Value Behavior when omitted
accountId String from your workspace installation Required; no default workspace is selected.
apiHost API base URL Uses https://api.userorbit.com. Change only to the host agreed for your installation.
cdnHost Runtime base URL, when using the userorbit-js loader Uses https://cdn.userorbit.com. A custom API host does not automatically change runtime delivery.
userId Non-empty string or number Can reuse a stored browser identity or generate one. If email is supplied without a user ID, it can be used as the identity.
email, name Strings No new value is supplied by these options. Omitting a field is not a request to erase a previously stored value.
attributes Object of custom profile fields Adds no new fields. Keep attributes small and limited to your use case.
errorHandler Function receiving an SDK error SDK errors use the default console handling.

Use an explicit stable userId when identifying a person, rather than relying on email fallback. For subsequent authentication changes, use identify() as described in the User identity API reference.

cdnHost belongs to the package loader. An already loaded runtime is not moved to a new host by changing this option. Custom hosts require a complete deployment and networking configuration; these fields alone do not establish a supported proxy or self-hosted installation.

Collection and in-app controls

Option If omitted What false changes
analytics.enabled Analytics initialization is allowed when a project and runtime feature access are available. Disables initialization of the SDK's analytics client.
sessionReplay.enabled Recording is allowed to proceed only when the server's recording configuration, audience, and other eligibility checks permit it. Prevents replay recording through this SDK control.
inApp.enabled In-app behavior is enabled. Disables in-app action triggers and related automatic listeners and route detection.

For example, disable replay at initial load while leaving other configuration unchanged:

await userorbit.init({
  accountId: "YOUR_ACCOUNT_ID",
  sessionReplay: { enabled: false },
});
JavaScript

Setting an option to true does not bypass workspace access, server feature settings, recording audience, sampling, or quota. Review recording settings in Userorbit as well as your application code.

These switches have separate scopes. Turning off analytics does not mean that the widget, identity updates, in-app features, storage, and all network traffic stop. Turning off in-app behavior is not an analytics opt-out. They are not substitutes for a complete consent and withdrawal implementation.

Theme and language

theme accepts light, dark, or system. When both theme and widget.theme are supplied during initialization, the top-level theme takes precedence.

locale and language can provide language configuration. Choose values supported by the content and widget you intend to display, and verify the resulting language with a test user.

For display updates after initialization, the public setConfig() method accepts theme, position, locale, and language. It is not a general setter for analytics, sessionReplay, or identity:

await userorbit.setConfig({ theme: "dark" });
JavaScript

Use the dedicated widget documentation for opening views, positioning, and other display options.

Initialization and verification

Initialize once from a persistent application integration. Repeating init() after the runtime is initialized skips core initialization; it does not apply a fresh configuration. reset() refreshes the current identity and is not a way to clear a visitor's identity. logout() clears SDK configuration but retains the browser distinct ID and does not guarantee that an active replay stops. Validate sign-out and recording together; neither method is a consent-withdrawal API.

The package loader and core SDK queue work asynchronously. An awaited method returning is not proof of successful server delivery. Verify a test contact, a known event in Analytics → Live Events, and the expected recording or experience behavior.

When troubleshooting, check both the installed package version and the loaded runtime request. The userorbit-js package loads a separate browser runtime, so the package version alone does not identify all runtime behavior.

See SDK Troubleshooting Reference and Configure Session Replay privacy and retention.

Was this helpful?