Browser SDK

@biqli/analytics runs only in browsers and accepts only a biqli_pk_... publishable key.

npm install @biqli/analytics

import {BiqliAnalytics} from '@biqli/analytics';

const biqli = new BiqliAnalytics({
  publishableKey: 'biqli_pk_xxxxxxxxx',
});

For a site without a package manager, load https://biq.li/sdk/dist/auto.global.js with a data-publishable-key attribute. See the HTML guide.

Configuration

Option	Type	Default	Description
`publishableKey`	`string`	Required	Workspace browser key beginning with `biqli_pk_`
`apiHost`	`string`	`https://biq.li`	API host or fixed reverse-proxy base
`clickId`	`string`	None	Known initial click ID
`attributionModel`	`'first-click' \| 'last-click'`	`last-click`	How a new eligible click replaces stored attribution
`cookieOptions`	`CookieOptions`	See below	First-party attribution cookie configuration
`queryParameters`	`string[]`	`['bq_id']`	URL parameters checked for attribution
`outboundDomains`	`string[]`	`[]`	Exact or wildcard destinations to decorate
`manualStart`	`boolean`	`false`	Delay lifecycle listeners and queue flushing
`consent`	`boolean`	`true`	Initial consent state
`requestTimeoutMs`	`number`	`10000`	Request timeout, clamped from 1,000 to 60,000 ms
`clientName`	`string`	`@biqli/analytics`	Diagnostic client header
`clientVersion`	`string`	SDK version	Diagnostic version header
`queue`	`RetryQueueOptions`	See below	Browser retry queue limits
`fetch`	`typeof fetch`	Browser `fetch`	Custom Fetch-compatible transport

Option	Default	Description
`domain`	Current host only	Optional shared cookie domain
`path`	`/`	Cookie path
`sameSite`	`lax`	`strict`, `lax`, or `none`
`expiresInDays`	`90`	Lifetime clamped from 1 to 365 days

The SDK writes bq_id as a first-party cookie. If the browser rejects that cookie, it uses controlled local-storage fallback where available.

Retry queue defaults

Option	Default
`maxSize`	100 records
`maxAgeMs`	7 days
`maxAttempts`	8
`baseDelayMs`	1,000 ms
`maxDelayMs`	5 minutes
`flushIntervalMs`	15 seconds

Instance methods

Method	Result	Purpose
`start()`	`this`	Start capture, navigation handlers, and queue flushing
`stop()`	`this`	Stop lifecycle handlers without clearing attribution
`teardown()`	`void`	Stop this instance
`setConsent(granted)`	`void`	Grant or withdraw consent; withdrawal clears attribution and queued events
`hasConsent()`	`boolean`	Return current consent state
`getClickId()`	`string \| null`	Read eligible stored attribution
`setClickId(clickId)`	`void`	Store a validated click ID using the configured model
`clearClickId()`	`void`	Clear cookie, fallback storage, and in-memory attribution
`decorateUrl(url)`	`string`	Add `bq_id` to an allowed outbound destination
`trackClick(input)`	`Promise<ClickResponse \| QueuedEvent>`	Create an optional client click
`trackLead(input)`	`Promise<EventResponse \| QueuedEvent>`	Create a client lead
`trackSale(input)`	`Promise<SaleResponse \| QueuedEvent>`	Create a client sale
`flush()`	`Promise<void>`	Attempt delivery of due queued events

storeStripeSession() is available for Biqli’s browser-to-Stripe attribution adapter. New custom payment implementations should normally persist bq_id in their own backend and send sales with the server SDK.

Tracking inputs

Client click

Field	Type	Required	Meaning
`domain`	`string`	Yes	Biqli short-link hostname without a protocol
`key`	`string`	Yes	Short-link alias or generated key
`url`	`string`	No	Current page URL; defaults to `location.href`
`referrer`	`string \| null`	No	Referring URL; defaults to `document.referrer`
`eventId`	`string`	No	Stable identity for an idempotent retry

Shared customer identity

Every lead and sale accepts these fields:

Field	Type	Required	Meaning
`customerExternalId`	`string`	Yes	Stable customer ID from your application
`customerName`	`string`	No	Display name
`customerEmail`	`string`	No	Valid email address
`customerAvatar`	`string`	No	Avatar URL
`clickId`	`string`	No	Explicit attribution click; otherwise the SDK uses its stored click
`metadata`	JSON object	No	Non-sensitive business metadata
`occurredAt`	`string`	No	ISO 8601 UTC event time ending in `Z`

Lead-specific fields are eventName (required), eventId, and eventQuantity (default 1). Sale-specific fields are amount (required integer minor units), currency, eventName, paymentProcessor, invoiceId, eventId, and leadEventName. Use a stable lead eventId. For a sale, use stable paymentProcessor and invoiceId values whenever they exist.

Results and errors

A successful tracking call returns the created or replayed event, customer, click, link, and request_id. During a retryable browser outage it can instead return:

{
  queued: true,
  eventId: 'stable-event-identity',
}

Rejected calls throw BiqliError with code, status, requestId, details, and retryable properties. A queued result is not proof that the server has received the event; it means the SDK will retry within its configured queue limits.

Module helpers

import {
  inject,
  getInjectedInstance,
  teardownInjectedInstance,
} from '@biqli/analytics';

inject() replaces and tears down the previous injected instance. Use the class directly when your application owns instance lifecycle.

React exports

import {BiqliProvider, useBiqli} from '@biqli/analytics/react';

The hook exposes the SDK, tracking methods, click ID access, consent control, and URL decoration. It must be called under BiqliProvider.

Global script API

The automatic script exposes:

Biqli.init                 Biqli.getInstance
Biqli.trackClick           Biqli.trackLead
Biqli.trackSale            Biqli.getClickId
Biqli.setClickId           Biqli.clearClickId
Biqli.setConsent           Biqli.decorateUrl
Biqli.storeStripeSession   Biqli.teardown

See the browser quickstart, HTML guide, and React guide.

GETTING STARTED

SDKs

BIQLI LINKS API

Configuration

Retry queue defaults

Instance methods

Tracking inputs

Client click

Shared customer identity

Results and errors

Module helpers

React exports

Global script API

​Configuration

​Cookie options

​Retry queue defaults

​Instance methods

​Tracking inputs

​Client click

​Shared customer identity

​Results and errors

​Module helpers

​React exports

​Global script API

Configuration

Cookie options

Retry queue defaults

Instance methods

Tracking inputs

Client click

Shared customer identity

Results and errors

Module helpers

React exports

Global script API