SDK API Reference

The complete reference for the lucia-sdk browser library. New to the SDK? Start with the Quickstart.

Browser-only

lucia-sdk is a client-side library — it requires a browser (window). There's no server-side or React Native build; call it from the browser, or from Client Components when using Next.js.

Installation

Option 1 — CDN script tag

Works with both single-page and multi-page apps.

Auto-initialization (recommended) — the SDK initializes itself when you provide data-api-key:

<script
  src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"
  data-api-key="your-api-key-here"
></script>

Manual initialization:

<script src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"></script>
<script>
  LuciaSDK.init({ apiKey: 'your-api-key-here' });
</script>

Option 2 — npm / yarn

npm install lucia-sdk
# or
yarn add lucia-sdk

import LuciaSDK from 'lucia-sdk';

await LuciaSDK.init({ apiKey: 'your-api-key-here' });

Configuration

LuciaSDK.init(config) accepts:

Option	Type	Required	Description
apiKey	string	✅	Your Lucia API key, from the dashboard.
debug	boolean	—	Log SDK activity and errors to the console.
testENV	boolean	—	Route events to the staging environment (https://staging.api.clickinsights.xyz) instead of production.
debugURL	string	—	Override the event endpoint with a custom URL (internal use).
autoTrackClicks	boolean | AutoTrackClicksConfig	—	Enable automatic click tracking. See Auto-tracking.

interface Config {
  apiKey: string;
  debug?: boolean;
  testENV?: boolean;
  debugURL?: string;
  autoTrackClicks?: boolean | {
    enabled?: boolean;
    selectors?: string[]; // CSS selectors to track
    ignore?: string[];    // CSS selectors to ignore
  };
}

By default, events are sent to https://api.luciaprotocol.com. If your site uses a Content-Security-Policy, allowlist that host — see Troubleshooting → CSP.

Methods

Every tracking method returns a Promise. They're safe to fire-and-forget (a failed event won't throw into your UI), or await them to sequence work after the event is sent.

init(config)

LuciaSDK.init(config: Config): Promise<LuciaSDKInstance>

Initializes the SDK. Can be skipped when using the CDN with the data-api-key attribute. Calling any other method before init throws "LuciaSDK not initialized."

pageView(page)

LuciaSDK.pageView(page: string): Promise<void>

Records a page view. Fires automatically on first load; call it manually on SPA route changes. → Page View

trackConversion(eventTag, amount, eventDetails)

LuciaSDK.trackConversion(eventTag: string, amount: number, eventDetails: object): Promise<void>

Records a conversion (purchase, signup, lead) with a value and arbitrary details. → Track Conversion

buttonClick(button, metadata?)

LuciaSDK.buttonClick(button: string, metadata?: ClickEventMetadata): Promise<void>

Records a click on a named element. metadata is optional:

interface ClickEventMetadata {
  elementType?: string;              // e.g. "button"
  text?: string;                     // visible label
  href?: string | null;             // for links
  meta?: Record<string, string>;    // your own key/values
}

→ Button Click

userInfo(user, userInfo)

LuciaSDK.userInfo(user: string, userInfo: object): Promise<void>

Associates events with a known person (email, user ID, or wallet) plus any profile fields, so sessions resolve into one identity. → User Information

sendWalletInfo(walletAddress, optionsOrChainId?, walletName?)

LuciaSDK.sendWalletInfo(
  walletAddress: string,
  optionsOrChainId?: WalletInfoOptions | number | string,
  walletName?: string,
): Promise<void>

Links a connected wallet to the customer profile. The second argument can be a numeric chainId or a WalletInfoOptions object:

interface WalletInfoOptions {
  provider?: string;
  providerRdns?: string;  // EIP-6963 reverse-DNS id, e.g. "io.metamask"
  connectorType?: string;
  chainId?: number;
}

// Simple form
LuciaSDK.sendWalletInfo('0x8f…21', 1, 'MetaMask');

// With options
LuciaSDK.sendWalletInfo('0x8f…21', { chainId: 1, providerRdns: 'io.metamask' });

→ Wallet Information

trackUserAcquisition(userId, acquisitionData?)

LuciaSDK.trackUserAcquisition(userId: string, acquisitionData?: object): Promise<void>

Records how a user was acquired (the first-touch source/campaign for that user).

checkMetaMaskConnection()

LuciaSDK.checkMetaMaskConnection(): boolean

Returns whether MetaMask is currently connected — useful for re-sending wallet info on page load without prompting the user.

VERSION

LuciaSDK.VERSION: string

The SDK version string.

Auto-tracking attributes

Enable zero-config click tracking with data-auto-track-clicks="true" on the script tag (or autoTrackClicks: true in init). Script-tag attributes:

Attribute	Description
data-api-key	Required. Your Lucia API key (also triggers auto-init).
data-debug-url	Custom event endpoint (internal use).
data-auto-track-clicks	"true" / "false" — enable automatic click tracking.
data-track-selectors	Comma-separated CSS selectors to track.

Element-level control:

Attribute	Description
data-lucia-track="id"	Track this element under a stable identifier.
data-lucia-meta-*="value"	Attach metadata to the tracked click (e.g. data-lucia-meta-variant="primary").
data-lucia-ignore	Never track this element.

By default, auto-tracking covers <button>, <a href>, role="button", and any element with data-lucia-track — and automatically skips password/credit-card fields. → Button Click

Wallet detection

For web3 sites, the SDK ships EIP-6963 helpers to pick the right provider when a visitor has multiple wallets installed:

import { detectEvmProvider, detectSolanaProvider } from 'lucia-sdk';

Recognized wallets include MetaMask, Phantom, Coinbase Wallet, Rabby, Trust, OKX, Rainbow, Zerion, Argent, Ledger, Safe, Exodus, Backpack, Solflare, and more.

Exported utilities

Beyond the main object, the package exports helper functions for advanced use:

Export	Purpose
getUtmParams()	Read UTM parameters from the current URL.
getBrowserData()	Collect the browser/device signals the SDK uses.
detectEvmProvider() / detectSolanaProvider()	EIP-6963 wallet provider detection.

Lower-level helpers are also exported (safeAccess, filterObject, getCanvasFingerprint, isTouchEnabled, getApplePayAvailable, getContrastPreference, getColorGamut) for custom integrations.