Full Configuration
import { Refine } from '@refine-ai/sdk';
const refine = new Refine({
// Required
apiKey: 'your-api-key',
organizationId: 'org-uuid',
catalogId: 'catalog-uuid',
// Optional
applicationType: 'web',
debug: false,
// Event tracking configuration
events: {
enabled: true,
batchSize: 10,
flushInterval: 5000,
maxQueueSize: 1000,
maxRetries: 3,
persistence: 'localStorage',
sessionTimeout: 30 * 60 * 1000
},
// Privacy configuration
privacy: {
respectDoNotTrack: false,
anonymizeIp: false,
requireConsent: false
},
// Global error handler
onError: (error) => {
console.error('Refine error:', error);
}
});
Required Options
Your Refine API key. Obtain from Dashboard → Settings → API Keys.
Your organization UUID. Find at Dashboard → Settings → Organization.
The catalog to search. Find at Dashboard → Catalogs.
Optional Options
Application type identifier. Values: 'web', 'mobile', 'server'.
Enable debug logging. Logs all requests, responses, and events to the console.
onError
(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.
events: {
enabled: true,
batchSize: 10,
flushInterval: 5000,
maxQueueSize: 1000,
maxRetries: 3,
persistence: 'localStorage',
sessionTimeout: 30 * 60 * 1000
}
Enable or disable event tracking entirely.
Number of events to batch before sending. Lower values = more frequent requests but fresher data.
Maximum time (ms) between flushes, regardless of batch size.
Maximum events to queue. Oldest events are dropped when exceeded.
Retry attempts for failed event submissions.
events.persistence
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
Session timeout in milliseconds. Default is 30 minutes (30 * 60 * 1000).
Privacy Configuration
GDPR and privacy-related options.
privacy: {
respectDoNotTrack: false,
anonymizeIp: false,
requireConsent: false
}
privacy.respectDoNotTrack
When true, disables tracking if the browser’s Do Not Track setting is enabled.
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
const refine = new Refine({
apiKey: process.env.REFINE_API_KEY,
organizationId: process.env.REFINE_ORG_ID,
catalogId: process.env.REFINE_CATALOG_ID,
debug: process.env.NODE_ENV === 'development',
events: {
enabled: process.env.NODE_ENV === 'production',
persistence: process.env.NODE_ENV === 'production'
? 'localStorage'
: 'memory'
}
});
GDPR Compliance
import { Refine, ConsentPlugin } from '@refine-ai/sdk';
const refine = new Refine({
apiKey: process.env.REFINE_API_KEY,
organizationId: 'org_abc123',
catalogId: 'cat_xyz789',
privacy: {
respectDoNotTrack: true,
anonymizeIp: true,
requireConsent: true
}
});
const consentPlugin = new ConsentPlugin({
required: true,
onConsentRequired: () => {
showConsentBanner();
}
});
refine.use(consentPlugin);
// When user grants consent
function handleConsentGranted() {
consentPlugin.grant();
}
High-Volume Sites
For high-traffic applications, increase batch size and queue limits:
const refine = new Refine({
apiKey: process.env.REFINE_API_KEY,
organizationId: 'org_abc123',
catalogId: 'cat_xyz789',
events: {
batchSize: 50,
flushInterval: 10000,
maxQueueSize: 5000,
maxRetries: 5
}
});
Server-Side Rendering
For SSR environments where localStorage isn’t available:
const refine = new Refine({
apiKey: process.env.REFINE_API_KEY,
organizationId: 'org_abc123',
catalogId: 'cat_xyz789',
applicationType: 'server',
events: {
persistence: 'memory'
}
});
Updating Configuration
The SDK doesn’t support runtime configuration changes. Create a new instance if you need different settings:
// Don't do this
refine.config.debug = true; // ❌ Won't work
// Do this instead
const debugRefine = new Refine({
...baseConfig,
debug: true
});
Next Steps
