ELU Analytics for the web

Capture product events, connect activity to users and organizations, evaluate feature flags, and record sessions according to your ELU privacy settings.

Use one installation method per page: the ELU script or the NPM client. Both use your ELU site key. Keep account credentials and server secrets out of browser code.

Script installation

Copy the Web snippet from your ELU integration settings into your site's <head>. Keep the supplied URL and site key:

<script async src="https://elu.dev/v1/YOUR_SITE_KEY.js"></script>

The script initializes ELU for that site. Do not call init(). After the loader has run, use window.elu:

window.elu?.capture('checkout_started', { source: 'pricing_page' })
window.elu?.identify('user_123', { plan: 'pro' })

The script loads asynchronously. Optional chaining prevents an error if it has not loaded, but does not queue that call. Connect important early calls to the script's load event, or use the NPM client below. Once the loader has created window.elu, state-changing calls can wait for SDK startup; getters may still return undefined.

NPM installation

Install the package and use the site key from your ELU project's Web settings.

npm install @elu-labs/analytics-browser@latest

The page itself must use HTTPS, including during local development. Serve your local app with a certificate trusted by your browser, or use a trusted HTTPS preview. Initialization stays paused on HTTP localhost; HTTPS collection endpoints alone are not sufficient.

Initialize once in browser code after your consent manager permits analytics, and reuse the returned client:

import { createEluClient } from '@elu-labs/analytics-browser'

const elu = createEluClient('YOUR_SITE_KEY')

elu.capture('checkout_started', { source: 'pricing_page' })

For an ELU collection instance on your own domain, set its HTTPS URL:

const elu = createEluClient('YOUR_SITE_KEY', {
    api_host: 'https://analytics.example.com',
})

The instance must serve site configuration and the events, flags and replay endpoints that configuration authorizes. Its recorder assets use the same base URL unless you supply assets_host. Cloud defaults need no host options. Both options accept an absolute HTTPS URL with an optional path prefix, such as https://analytics.example.com/elu. Endpoints are placed under that prefix; credentials, queries, fragments and irregular paths are refused. The selected URLs cannot change after the first successful client initialization on a page. A served configuration cannot redirect requests to another origin or outside the selected path prefix.

Self-hosted instance

With a custom api_host, the client makes no request to any ELU Cloud origin:

If the recorder host does not deliver the recorder, for example because a network filter or a Content Security Policy blocks only that host, the client fetches the same file once from the events host, at /static/elu-owned/sdk/recorder/<sha256>.js under https://ingest.elu.dev or your api_host. Its bytes must match the pinned digest.

The client uses ELU-owned storage for identity and consent. Existing ELU state is retained; a visitor without it receives a fresh identity under the site's opt_out_capturing_by_default and respect_dnt settings. Earlier SDK storage and rollback synchronization are no longer supported.

A page can load the instance's script directly:

<script src="https://analytics.example.com/static/elu.js"></script>
<script>_eluSdk.init('YOUR_PROJECT_TOKEN', { api_host: 'https://analytics.example.com' })</script>

init starts the same client as the snippet and publishes window.elu when the page has none. It requires an explicit api_host and an HTTPS page. The installation guide describes page options, shared identity and consent.

When canvas capture is on (the page's session_recording.captureCanvas ?? your instance's setting) and the instance does not hide images and media, the recorder also sends canvas pixels as replay frames. It starts a Web Worker from a blob: URL, so a Content Security Policy must allow worker-src blob: (or script-src blob:) as well as connect-src for your instance. Without it, canvas is left out and the rest of the replay continues. A WebGL canvas created before recording starts needs preserveDrawingBuffer: createEluClient supplies it for contexts created after it is called (unless the page turns canvas off), as the instance's install snippet does, so create the client before your map or chart.

Canvas frames are pictures, so text masking, input masking and mask selectors do not apply to them: text drawn into a canvas is recorded as pixels even when all text is masked. A block rule, or hiding images and media, keeps a canvas out of replay.

When replay network capture is on (the page's capture_performance and session_recording.recordHeaders/recordBody ?? your instance's setting), the recorder adds the page's resource and navigation timings and, as selected, the method, status, headers and bodies of fetch and XMLHttpRequest requests. Credential headers are always recorded as redacted; large, binary and sensitive-looking bodies are replaced by a note; requests to your instance are never recorded. Replay masking does not apply to these rows, and capture_network_requests does not control them.

When console recording is on (the page's enable_recording_console_log ?? your instance's setting), the recorder also records the page's console.* calls and uncaught errors in the replay, as the earlier script did: each entry keeps its level, a stack trace and the serialized arguments, at most ten strings of 2,000 characters. The console is patched only while a replay session is recording and restored when it stops. Masking settings do not apply to console entries: what a page logs is recorded whatever the text rule, as it was for the earlier script. A DOM node logged to the console is recorded as its selector path, never its markup, and a logged input, composition or keyboard event carries no typed text, so blocked or masked text and input values do not leave the page that way. The page's enable_recording_console_log decides: true records console even where the instance does not ask for it, false never does; omitted, the instance's setting decides. The same precedence, page option ?? project grant, applies to every automatic collector, and a page-enabled one runs with the same masking and bounds as a granted one. A replay starts with a full snapshot of the page and takes a fresh one at the first change after every session_recording.full_snapshot_interval_millis of activity, five minutes unless the page says otherwise. Each checkpoint begins a new replay chunk, so seeking lands on one and a player that cannot apply an incremental change is whole again at the next. A chunk never carries more than 5,000 events, whatever its size in bytes.

The package exports createEluClient and the TypeScript type EluClient. ESM and CommonJS root imports are supported. Importing the package does not initialize analytics. Call the factory only in a browser, never while rendering on the server. In a component framework, retain one client for the page rather than creating one on every render or mount. The NPM client does not create window.elu; keep the returned object.

Initialization options

The script loader chooses its startup options; changing NPM options does not configure a script installation. Replay and privacy settings come from ELU; a page can only add to them. Elements with the elu-mask class have their text masked, elu-no-capture are recorded as placeholders, and inputs with elu-ignore-input have their changes left out, whatever the instance's rules say. A session_recording member the recorder cannot honour (a RegExp class outside the exact-class shape /^(a|b)$/, a selector that does not parse or is left open by an unclosed comment, string, bracket or parenthesis or a trailing backslash) keeps replay off on that page rather than recording what it asked to hide, and the runtime names the option once in the console; maskTextFn and maskInputFn are not run, and the content they would have rewritten is masked as below. There is no set_config() or per-request endpoint override on this client: the earlier script's names are accepted on the returned object for pages written against it, set_config() is ignored with a console warning, and startSessionRecording() / stopSessionRecording() switch the page's recorder within what the instance allows. See earlier script methods.

Web Vitals and optional performance samples

When Web Vitals are on (the page's capture_performance ?? your ELU project's captureWebVitals), each page reports its Core Web Vitals (LCP, FCP, CLS and INP, or the metrics the project lists) as one or more $web_vitals events carrying the values, their ratings and the page location only. Metrics that settle early are sent together after a short delay; CLS and INP are also sent while the page is visible, each time they change, because capture stops once a page is hidden. A page that first paints while hidden reports no paint timings. The page's option decides in both directions: capture_performance: true or { web_vitals: true } turns them on even where the project does not grant them (every metric, narrowed by web_vitals_allowed_metrics), { web_vitals: false } or capture_performance: false turns them off; omitted, the project decides, and web_vitals_allowed_metrics narrows its metrics.

Performance sampling is off when neither your ELU site configuration nor local initialization options enable it. For the NPM client, you can opt in explicitly:

const elu = createEluClient('YOUR_SITE_KEY', {
    capture_performance: {
        memory: true,
        long_tasks: true,
        sample_interval_ms: 30_000,
    },
})

The TypeScript options type is PerformanceCaptureConfig. Each local setting overrides its remote counterpart; true enables both metrics and false disables both, along with Web Vitals. A capture_performance value that is neither a boolean nor an object turns the samples off. The interval defaults to 30 seconds, with a five-second minimum. If a renewed site configuration omits performance settings, previous remote opt-ins end; explicit local overrides still require valid capture authority.

Samples use the normal $performance_sample event queue. Memory measurements are available only when the browser exposes heap statistics; long-task measurements require PerformanceObserver support. Unsupported measurements are omitted. Collection pauses while the page is hidden and discards the old measurement window when identity, consent or capture configuration changes. Opt-out, blocked capture and expired configuration prevent sampling.

A final sample on hide or navigation is best-effort. Browser lifecycle and consent checks still apply; closing a tab or process can prevent enqueue or delivery. This feature does not guarantee an unload sample or process-death recovery.

Identify users and organizations

Use your application's stable internal ID, not an email address, name or phone number. Identify after sign-in and before related custom events:

elu.identify('user_123', { plan: 'pro' }, { signup_source: 'website' })
elu.group('organization', 'org_456', { plan: 'pro' })
elu.capture('project_created', { template: 'blank' })

// On sign-out:
elu.reset()

The third argument to identify sets person properties only if absent. Use setPersonProperties for later changes. group associates subsequent activity with that group type; resetGroups clears group associations.

reset() begins a new anonymous identity and clears super properties, groups and flag context. It keeps the device ID ($device_id) unless called as reset(true), and preserves the visitor's opt-out choice. Identity reset is not consent to resume capture; use your consent manager for that decision.

Consent and privacy

If consent is required before any SDK activity, wait to load the script or call createEluClient until consent is granted. Initialization can open browser storage and request configuration; opting out afterward cannot undo those initial actions.

For an initialized client:

elu.opt_out_capturing()

// Only when the visitor explicitly opts back in:
elu.opt_in_capturing({ captureEventName: false })

Calling opt_in_capturing() without options also requests an $opt_in event. Opt-out suppresses capture, flag evaluation and replay. It does not delete data already delivered to ELU.

Keep passwords, payment details, tokens and sensitive personal data out of event properties, IDs and exception messages. Replay masking does not sanitize arbitrary custom event properties.

Session replay is activated separately for each project. Contact ELU support if it is unavailable; installing the package does not enable recording. Replay also requires consent, a site configuration that permits it, and an eligible browser and session. Review the site's input, text, image and blocked-element settings in ELU; do not assume all visible text and images are masked by default.

Masking in replay always means length-preserving *. A masked text node keeps its whitespace and has every other character replaced by *, and a masked input value becomes one * per character, so Team settings is recorded as **** ******** and a seven-character password as *******. Masked content is never blanked or dropped: the replay keeps the page's layout, and nothing of the original leaves the page except its length. HTML comments are always masked the same way. Blocking is the separate rule that removes content: a blocked element is recorded as an empty placeholder of the same size, and blocked images keep no src.

Feature flags

Flags load asynchronously. undefined means no usable value is available; handle it separately from an explicit false:

const unsubscribe = elu.onFeatureFlags((_keys, _variants, context) => {
    if (context?.errorsLoading) return
    const enabled = elu.isFeatureEnabled('new_checkout', { defaultValue: false })
    // Render the new checkout only when enabled === true.
})

// When the component is disposed:
unsubscribe()

Use getFeatureFlag for a boolean or string variant, getFeatureFlagPayload for its JSON payload, or getFeatureFlagResult for { key, enabled, variant, payload }. Flag reads can report exposure; pass { send_event: false } to a flag/feature read when you do not want that exposure event. Use reloadFeatureFlags() to request new values. Feature flags are not a server-side authorization boundary.

Once an evaluation has loaded, every event carries it: $feature/<key> with each evaluated flag's value and $active_feature_flags with the keys whose value is truthy. These are derived from the loaded evaluation, never stored as super properties, so reset() and an identity change clear them until the next evaluation lands; a super-property change (register, register_once, unregister) keeps the loaded evaluation, served until its own expiry or the next evaluation without a new request, so a read or an event in the same turn still sees it; an event's own property of the same name wins, and the stamps fit inside the capture property budget. $feature_flag_called also names the evaluation it reports: $feature_flag_request_id, $feature_flag_evaluated_at (milliseconds since the Unix epoch) and $used_bootstrap_value, true while the value came from the cached evaluation rather than a response received on this page. A value is reported once per flag key and value for the anonymous visitor, across page loads (the ledger is kept in localStorage per site key, as the 1.409.5 bundle kept $flag_call_reported): identify() keeps it and reset() starts a new one. Flags are evaluated again on every configuration renewal (at most five minutes apart).

Other common operations

elu.register({ app_area: 'dashboard' }) // Properties on later events
elu.register_once({ first_campaign: 'docs' })
elu.unregister('app_area')
elu.setPersonProperties({ plan: 'business' })
elu.captureException(new Error('Upload failed'), { operation: 'upload' })

capture() returns no delivery receipt or Promise. Confirm integration with a non-sensitive test event in ELU; a script download or method return alone does not prove ingestion.

License

ELU contributions are available under the MIT License, including commercial use, modification, and redistribution.

Third-party portions retain their original Apache-2.0, MIT, or ISC terms and attribution in THIRD_PARTY_NOTICES.txt. ELU's MIT terms do not replace those upstream terms. Include LICENSE, NOTICE-ELU, and THIRD_PARTY_NOTICES.txt when redistributing the SDK. Published npm versions retain the terms included in their archives.