Plugins Overview

Extend SDK functionality with built-in and custom plugins

Overview

Plugins extend the Refine SDK with additional functionality. The SDK includes three built-in plugins:

Plugin	Purpose
DebugPlugin	Development logging and validation
ConsentPlugin	GDPR-compliant consent management
AutoTrackPlugin	Automatic 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