Hooks

Toggly SDK hooks let you react to feature flag lifecycle events by plugging in lightweight callbacks. Use hooks to integrate with analytics, session replay, error tracking, and monitoring services.

Available Hooks

All Toggly JavaScript SDKs that accept a hooks array share the same interface via @ops-ai/toggly-hooks-types (currently 1.4.x). That includes:

• Browser: vanilla JS, React, Angular, Vue, Svelte, Astro, Gatsby, Docusaurus
• Full-stack: Next.js, Remix, Nuxt
• Mobile: React Native
• Server: Node.js

Official analytics packages (@ops-ai/toggly-clarity-hook, @ops-ai/toggly-ga4-hook, @ops-ai/toggly-appinsights-hook) target browser runtimes where those third-party SDKs are loaded. Custom hooks that implement the interface can run on any SDK listed above.

Hooks are documented here and stay out of the create-app Technology Stack picker. They are add-ons to an SDK, not a stack of their own.

Hook Interface

interface Hook {
  getMetadata(): HookMetadata;
  beforeEvaluation?(
    flagKey: string,
    defaultValue?: boolean
  ): Promise<EvaluationSeriesData | void> | EvaluationSeriesData | void;
  afterEvaluation?(
    flagKey: string,
    data: EvaluationSeriesData | void,
    result: boolean
  ): Promise<void> | void;
  beforeIdentify?(identity: string): Promise<IdentitySeriesData | void> | IdentitySeriesData | void;
  afterIdentify?(identity: string, data: IdentitySeriesData | void): Promise<void> | void;
  afterRefresh?(flags: { [key: string]: boolean }): Promise<void> | void;
}

Lifecycle Events

Hook	Trigger	Use Case
beforeEvaluation	Before a feature flag is checked	Add context, timing data
afterEvaluation	After a feature flag is checked	Analytics, tracking, logging
beforeIdentify	Before user identity is set	Pre-identification setup
afterIdentify	After user identity is set	User tagging in analytics
afterRefresh	After flag definitions refresh from server	Sync state with external services

Official Hook Packages

Shared types for the hooks interface live in @ops-ai/toggly-hooks-types.

Package	Service	Description
@ops-ai/toggly-clarity-hook	Microsoft Clarity	Send feature flag events to Clarity session recordings
@ops-ai/toggly-ga4-hook	Google Analytics 4	Send feature flag events and user properties to GA4
@ops-ai/toggly-appinsights-hook	Azure Application Insights	Send feature flag telemetry and custom properties to App Insights

Registering Hooks

During Initialization

import { Toggly } from '@ops-ai/feature-flags-toggly';
import { ClarityHook } from '@ops-ai/toggly-clarity-hook';
import { GA4Hook } from '@ops-ai/toggly-ga4-hook';
import { AppInsightsHook } from '@ops-ai/toggly-appinsights-hook';

Toggly.init({
  appKey: 'your-app-key',
  environment: 'Production',
  hooks: [
    new ClarityHook(),
    new GA4Hook({ measurementId: 'G-XXXXXXXXXX' }),
    new AppInsightsHook({ setCustomProperties: true }),
  ]
});

At Runtime

// Add a hook
Toggly.addHook(new ClarityHook());
Toggly.addHook(new GA4Hook({ measurementId: 'G-XXXXXXXXXX' }));
Toggly.addHook(new AppInsightsHook());

// Remove a hook by name
Toggly.removeHook('clarity-hook');
Toggly.removeHook('ga4-hook');
Toggly.removeHook('appinsights-hook');

Writing Custom Hooks

You can create your own hooks by implementing the Hook interface:

import type { Hook, HookMetadata, EvaluationSeriesData } from '@ops-ai/toggly-hooks-types';

class MyAnalyticsHook implements Hook {
  getMetadata(): HookMetadata {
    return { name: 'my-analytics-hook' };
  }

  afterEvaluation(flagKey: string, _data: EvaluationSeriesData | void, result: boolean): void {
    myAnalytics.track('feature_evaluated', { flagKey, enabled: result });
  }
}

Best Practices

• Never throw errors - hooks should fail silently to avoid breaking the SDK
• Keep it fast - hooks are called on every evaluation; keep overhead minimal
• Use unique names - the getMetadata().name must be unique per registered hook
• Check availability - verify third-party SDKs are loaded before calling them