@getfluxly/browser

The official GetFluxly browser analytics SDK. Captures page views, clicks, form submits, rage clicks, page leave, and unhandled JS errors, and exposes explicit track, identify, and page calls.

• Runtime: evergreen browsers. No IE.
• Module formats: ESM (npm) + IIFE (CDN).
• Types: shipped in dist/types.
• Zero runtime dependencies.

Install

Bundled apps (recommended)

npm install @getfluxly/browser

import { initGFlux } from "@getfluxly/browser";

const gflux = initGFlux({
  apiKey: "gflux_pub_live_xxx",
  apiHost: "https://api.getfluxly.com",
});

gflux?.page();

Side-effect boot

For when you want the SDK to read window.__GFLUX__ and boot itself.

window.__GFLUX__ = {
  apiKey: "gflux_pub_live_xxx",
  apiHost: "https://api.getfluxly.com",
};

import "@getfluxly/browser/auto";

Script tag

Always pin a specific version and supply an SRI hash so a CDN compromise cannot inject code into your site. The integrity value below is generated at release time; copy it from the GitHub release notes for the version you are pinning.

<script>
  window.__GFLUX__ = {
    apiKey: "gflux_pub_live_xxx",
    apiHost: "https://api.getfluxly.com"
  };
</script>
<script
  src="https://cdn.jsdelivr.net/npm/@getfluxly/[email protected]/dist/gflux.iife.js"
  integrity="sha384-PLACEHOLDER"
  crossorigin="anonymous">
</script>

To generate the SRI hash yourself for any version:

curl -sL https://cdn.jsdelivr.net/npm/@getfluxly/[email protected]/dist/gflux.iife.js \
  | openssl dgst -sha384 -binary | openssl base64 -A

Script tag without inline config

<script
  src="https://cdn.jsdelivr.net/npm/@getfluxly/[email protected]/dist/gflux.iife.js"
  integrity="sha384-PLACEHOLDER"
  crossorigin="anonymous"
  data-project="gflux_pub_live_xxx"
  data-host="https://api.getfluxly.com">
</script>

Use data attributes when a strict CSP blocks inline scripts.

Pre-boot queue

The /auto and CDN builds install window.gflux immediately. Calls made before DOMContentLoaded are queued and replayed after the real client boots.

Queued and replayed in order:

• gflux.track(...)
• gflux.identify(...)
• gflux.page(...)

Control calls win over old queued work:

• gflux.optOut() clears earlier queued tracking calls and queues the opt-out.
• gflux.reset() clears earlier queued tracking calls and queues the reset.
• gflux.destroy() clears earlier queued tracking calls and queues destroy.

API

SDK_VERSION

The SDK version shipped by the package, kept in sync with package.json at build time.

import { SDK_VERSION } from "@getfluxly/browser";

gflux.track(eventName, properties?)

Send a custom event.

gflux.track("checkout_completed", {
  order_id: "ord_456",
  total_usd: 149.99,
});

gflux.identify(externalId, traits?)

Link the current anonymous visitor to a known user.

gflux.identify("user_42", {
  email: "[email protected]",
  plan: "pro",
});

identify stitches earlier anonymous activity to the known user. Events buffered before identify are replayed with the new external_id and replayed: true when consent allows replay.

In implicit consent mode, identify also grants consent. In explicit consent mode, identify stores the user id, but buffered events wait until optIn().

Call reset() on logout or account switch before identifying another user.

gflux.page(properties?)

Send an explicit page view. This uses the same page_view event as automatic page capture and inherits url, path, title, referrer, referrer_domain, and utm automatically.

gflux.page({
  section: "pricing",
});

Manual page() still works when autocapture.pageviews is off.

gflux.optIn()

Grant consent and flush buffered events.

gflux.optIn();

gflux.optOut()

Persist an opt-out, drop buffered events, and block future events until optIn() or reset().

gflux.optOut();

gflux.reset()

Clear the anonymous id, identified user, traits, and consent state. Call this on logout.

gflux.reset();

gflux.destroy()

Tear down listeners and flush in-flight requests. Returns a promise that resolves once the transport has drained.

await gflux.destroy();

Await this if you want delivery guarantees for in-flight events before tearing down the host page (for example, before navigating in a single-page test harness).

gflux.__debug()

Return the current buffer size, dropped-event counters, resolver config, and current consent decision. Use when investigating why an event did not arrive — drop counts surface things like sampling, autocapture toggles, and consent rejections.

gflux.__debug();
// {
//   bufferSize: 3,
//   bufferDropped: 0,
//   dropCounts: { sampled: 12 },
//   resolverConfig: { dntMode, gpcMode, consentMode, region },
//   decision: { decision: "track" }
// }

Autocapture

| Event | Trigger | Main properties | | --- | --- | --- | | page_view | Initial load and SPA navigation | url, path, title, referrer, referrer_domain, utm | | autocapture_click | Clicks on links, buttons, [role="button"], inputs, or [data-gf] | tag, text, href, id, classes, selector, path, data_gf | | autocapture_form | Form submit | form_id, form_name, action, method, field_count, path | | page_leave | visibilitychange hidden, beforeunload, and SPA navigation | path, time_on_page_ms | | rage_click | 3+ clicks within 1s on the same interactive element | tag, text, href, id, classes, selector, path, click_count, window_ms | | js_error | Uncaught browser error | source, message, name, filename, lineno, colno, stack, path | | unhandled_rejection | Unhandled promise rejection | message, name, stack, path |

Disable individual capture types:

initGFlux({
  apiKey: "gflux_pub_live_xxx",
  apiHost: "https://api.getfluxly.com",
  autocapture: {
    pageviews: true,
    clicks: true,
    forms: false,
    pageLeave: false,
    rageClicks: false,
    errors: true,
  },
});

Disable all autocapture:

initGFlux({
  apiKey: "gflux_pub_live_xxx",
  apiHost: "https://api.getfluxly.com",
  autocapture: false,
});

DOM Controls

Ignore a subtree

Use either attribute to stop autocapture and declarative capture inside a node.

<div data-gf-ignore>
  <button>Not captured</button>
</div>

<form data-gflux-ignore>
  <!-- not captured -->
</form>

Declarative events

Add a custom event directly in HTML.

<button
  data-gflux-event="checkout_started"
  data-gflux-prop-plan="pro"
  data-gflux-prop-items="2">
  Checkout
</button>

Supported aliases:

• data-gflux-event or data-gf-event
• data-gflux-prop-* or data-gf-prop-*
• data-gf-ignore or data-gflux-ignore

Property values are parsed as booleans, numbers, null, JSON objects, JSON arrays, or strings. Form values are not captured.

Privacy And Consent

The SDK resolves every event through this order:

1. Explicit opt-out blocks.
2. GPC blocks when gpcMode is "honor". For region: "us-ca" the SDK pins the effective mode to "honor" regardless of config — a local gpcMode: "ignore" cannot turn off GPC for California visitors.
3. Explicit opt-in tracks.
4. Explicit consent mode buffers until opt-in.
5. Honored DNT buffers until opt-in or identify.
6. Otherwise track.

Buffered events stay in memory only. They are not written to storage. When replayed, they are sent with replayed: true.

When remote config is enabled and consent is still auto, the SDK buffers early events until /v1/sdk-config returns or times out. This keeps the first page view and queued calls on the same consent decision as later events.

The remote config response is shape-validated and value-clamped — unknown fields, invalid enums, and out-of-range numbers are rejected with a logger warning instead of mutating the SDK's runtime behavior.

Strict CSP

The built-in consent banner injects a <style> tag, which requires 'unsafe-inline' in style-src by default. To run under a stricter policy, pass a nonce:

initGFlux({
  apiKey: "gflux_pub_live_xxx",
  apiHost: "https://api.getfluxly.com",
  consentBanner: {
    nonce: "REQUEST_CSP_NONCE",
  },
});

Or set a meta tag once per page:

<meta name="gflux-csp-nonce" content="REQUEST_CSP_NONCE">

The SDK reads the meta tag if no explicit nonce is passed.

Logging

By default the SDK warns to console.warn on misuse and transport rejections. Silence with logger: false, or supply a structured logger:

initGFlux({
  apiKey: "gflux_pub_live_xxx",
  apiHost: "https://api.getfluxly.com",
  logger: {
    warn: (msg, ctx) => myLogger.warn({ msg, ...ctx }),
  },
});

Configuration

| Key | Type | Default | Notes | | --- | --- | --- | --- | | apiKey | string | required | Browser publishable key (gflux_pub_...). | | apiHost | string | current origin | Use https://api.getfluxly.com for hosted GetFluxly. Validated with new URL() at boot. | | autocapture | false \| object | all on | Per-type toggles or false for all off. | | sampling | number | 100 | Percentage of anonymous events to keep. Identified events are never sampled. | | dntMode | "honor" \| "ignore" \| "auto" | "auto" | "auto" resolves from remote config, then falls back to "ignore". | | gpcMode | "honor" \| "ignore" | "honor" | GPC should stay honored in production. Overridden to "honor" whenever region resolves to "us-ca". | | consentMode | "implicit" \| "explicit" \| "auto" | "auto" | "auto" uses explicit consent for EU visitors. | | region | "auto" \| "eu" \| "us-ca" \| "us" \| "other" | "auto" | Usually fetched from /v1/sdk-config. "us-ca" is treated as CCPA scope: it pins gpcMode to "honor" regardless of the configured value (ignoring GPC in California is legally binding — Sephora was fined $1.2M). | | remoteConfig | boolean \| string | true | Fetch project runtime config at boot. | | bufferMaxEvents | number | 200 | Max in-memory buffered events (FIFO eviction). | | maskedSelectors | string[] | [] | Text under matching selectors is masked during capture. Snippet-only. Selectors are validated at boot; invalid ones are dropped. | | consentBanner | object | default copy | Built-in explicit-consent banner copy. Supports nonce for strict CSP. | | flushIntervalMs | number | 3000 | Background flush interval. | | flushQueueSize | number | 10 | Flush when queue reaches this size. | | maxRetries | number | 3 | Transport retries for transient failures (408, 425, 429, 5xx, network errors). 4xx client errors are not retried. | | logger | Logger \| boolean | console | Pass false to silence, or supply a custom logger. |

Storage

| Key | Purpose | | --- | --- | | gf_anon_id | Anonymous visitor id (localStorage primary, cookie fallback with Secure on HTTPS). | | gf_external_id | Last identified user id. | | gf_traits | Last identify traits. | | gf_consent | Explicit opt-in. | | gf_optout | Explicit opt-out. |

License

MIT