Frequency Plugin

Manages impression tracking and frequency capping using persistent storage.

Configuration

const experiences = createInstance({
  frequency: {
    enabled: true,           // Enable frequency tracking (default: true)
    storage: 'local'         // 'local' | 'session' | 'memory' (default: 'local')
  }
});

Experience-Level Frequency

Define frequency caps per experience:

experiences.register('welcome', {
  type: 'banner',
  content: { message: 'Welcome!' },
  frequency: {
    max: 3,                 // Maximum impressions
    per: 'session'          // 'session' | 'day' | 'week'
  }
});

API Methods

`frequency.getImpressionCount(experienceId, period?)`

Get impression count for an experience.

const count = experiences.frequency.getImpressionCount('welcome', 'session');
console.log(`Shown ${count} times this session`);

Parameters:

experienceId: string - Experience to check
period?: 'session' | 'day' | 'week' - Time period (optional)

Returns: number

`frequency.recordImpression(experienceId)`

Manually record an impression.

experiences.frequency.recordImpression('welcome');

`frequency.reset(experienceId?)`

Reset impression counts.

// Reset specific experience
experiences.frequency.reset('welcome');
 
// Reset all experiences
experiences.frequency.reset();

How It Works

Impressions are recorded when experiences:shown event is emitted
Storage persists counts in localStorage (or sessionStorage/memory)
Evaluation checks counts before showing experiences
Dismissals do NOT count as impressions

Storage Keys

Frequency data is stored with namespaced keys:

experiences.frequency.session:welcome = 3
experiences.frequency.day:2024-12-25:welcome = 1
experiences.frequency.week:2024-W52:welcome = 5

Inline Debug