Skip to main content

Full Configuration

Required Options

string
required
Your Refine API key. Obtain from Dashboard → Settings → API Keys.
string
required
Your organization UUID. Find at Dashboard → Settings → Organization.
string
required
The catalog to search. Find at Dashboard → Catalogs.

Optional Options

string
default:"web"
Application type identifier. Values: 'web', 'mobile', 'server'.
boolean
default:"false"
Enable debug logging. Logs all requests, responses, and events to the console.
(error: RefineError) => void
Global error handler called for all SDK errors. Useful for centralized error reporting.

Events Configuration

Control how events are batched, stored, and transmitted.
boolean
default:"true"
Enable or disable event tracking entirely.
number
default:"10"
Number of events to batch before sending. Lower values = more frequent requests but fresher data.
number
default:"5000"
Maximum time (ms) between flushes, regardless of batch size.
number
default:"1000"
Maximum events to queue. Oldest events are dropped when exceeded.
number
default:"3"
Retry attempts for failed event submissions.
string
default:"localStorage"
Where to persist the event queue. Options:
  • 'localStorage' — Survives page refreshes (browser only)
  • 'sessionStorage' — Cleared on tab close
  • 'memory' — No persistence (lost on refresh)
  • 'none' — Disable persistence
number
default:"1800000"
Session timeout in milliseconds. Default is 30 minutes (30 * 60 * 1000).

Privacy Configuration

GDPR and privacy-related options.
boolean
default:"false"
When true, disables tracking if the browser’s Do Not Track setting is enabled.
boolean
default:"false"
When true, IP addresses are anonymized before storage.
When true, event tracking is paused until consent is granted via the ConsentPlugin.

Configuration Patterns

Development vs Production

GDPR Compliance

High-Volume Sites

For high-traffic applications, increase batch size and queue limits:

Server-Side Rendering

For SSR environments where localStorage isn’t available:

Updating Configuration

The SDK doesn’t support runtime configuration changes. Create a new instance if you need different settings:

Next Steps

Text Search

Start searching

Plugins

Extend SDK functionality