Skip to main content

​
Overview

Plugins extend the Refine SDK with additional functionality. The SDK includes three built-in plugins:
PluginPurpose
DebugPluginDevelopment logging and validation
ConsentPluginGDPR-compliant consent management
AutoTrackPluginAutomatic event tracking

​
Using Plugins

Register plugins with refine.use(): 
import { Refine, DebugPlugin, ConsentPlugin, AutoTrackPlugin } from '@refine-ai/sdk';

const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY,
  organizationId: 'org_abc123',
  catalogId: 'cat_xyz789'
});

// Add plugins
refine.use(new DebugPlugin({ logEvents: true }));
refine.use(new ConsentPlugin({ required: true }));
refine.use(new AutoTrackPlugin({ pageViews: true }));

​
Plugin Order

Plugins execute in registration order. For most cases, the recommended order is: 
// 1. Debug first (logs everything)
refine.use(new DebugPlugin({ logEvents: true }));

// 2. Consent second (gates all tracking)
refine.use(new ConsentPlugin({ required: true }));

// 3. AutoTrack last (depends on consent)
refine.use(new AutoTrackPlugin({ pageViews: true }));

​
Quick Reference

​
DebugPlugin

Log events and validate parameters during development: 
import { DebugPlugin } from '@refine-ai/sdk';

refine.use(new DebugPlugin({
  logEvents: true,      // Log all events to console
  validateEvents: true, // Warn about invalid events
  dryRun: false         // If true, don't send events
}));

​
ConsentPlugin

Gate tracking behind user consent: 
import { ConsentPlugin } from '@refine-ai/sdk';

const consentPlugin = new ConsentPlugin({
  required: true,
  onConsentRequired: () => {
    showConsentBanner();
  }
});

refine.use(consentPlugin);

// When user grants consent
consentPlugin.grant();

// When user denies consent
consentPlugin.deny();

​
AutoTrackPlugin

Automatically track common events: 
import { AutoTrackPlugin } from '@refine-ai/sdk';

refine.use(new AutoTrackPlugin({
  pageViews: true,
  clicks: {
    selector: '[data-refine-item]',
    extractItemId: (el) => el.dataset.refineItem
  },
  viewability: {
    enabled: true,
    threshold: 0.5,
    duration: 1000
  }
}));

​
Combining Plugins

Typical production setup: 
import { 
  Refine, 
  DebugPlugin, 
  ConsentPlugin, 
  AutoTrackPlugin 
} from '@refine-ai/sdk';

const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY,
  organizationId: 'org_abc123',
  catalogId: 'cat_xyz789',
  privacy: {
    requireConsent: true
  }
});

// Development: enable debug logging
if (process.env.NODE_ENV === 'development') {
  refine.use(new DebugPlugin({
    logEvents: true,
    validateEvents: true
  }));
}

// Production: consent management
const consentPlugin = new ConsentPlugin({
  required: true,
  onConsentRequired: () => {
    document.getElementById('consent-banner')?.classList.remove('hidden');
  }
});
refine.use(consentPlugin);

// Auto-tracking with consent gate
refine.use(new AutoTrackPlugin({
  pageViews: true,
  viewability: { enabled: true, threshold: 0.5, duration: 1000 }
}));

// Consent UI handlers
document.getElementById('accept-cookies')?.addEventListener('click', () => {
  consentPlugin.grant();
  document.getElementById('consent-banner')?.classList.add('hidden');
});

document.getElementById('decline-cookies')?.addEventListener('click', () => {
  consentPlugin.deny();
  document.getElementById('consent-banner')?.classList.add('hidden');
});

​
Next Steps

Debug Plugin

Development tools

Consent Plugin

Privacy compliance

Auto Track Plugin

Automatic tracking