posthog-js
Version:
Posthog-js allows you to automatically capture usage and send events to PostHog.
138 lines (137 loc) • 6.78 kB
TypeScript
import { PostHog } from '../../../posthog-core';
import { CaptureResult, SessionRecordingPersistedConfig, SessionStartReason } from '../../../types';
import { EventTriggerMatching, LinkedFlagMatching, URLTriggerMatching, SessionRecordingStatus, TriggerType } from './triggerMatching';
export declare function encodeSamplingDecision(sessionId: string, isSampled: boolean): string;
export declare function decodeSamplingDecision(storedValue: unknown, sessionId: string): boolean | null;
/**
* Shared context that strategies need to access from the recorder
*/
export interface RecordingStrategyContext {
instance: PostHog;
sessionId: string;
isSampled: boolean | null;
rrwebError: boolean;
urlTriggerMatching: URLTriggerMatching;
eventTriggerMatching: EventTriggerMatching;
linkedFlagMatching: LinkedFlagMatching;
remoteConfig: SessionRecordingPersistedConfig | undefined;
}
/**
* Strategy interface for handling different recording trigger configurations
*/
export interface RecordingStrategy {
/**
* Initialize the strategy with remote config
*/
onRemoteConfig(config: SessionRecordingPersistedConfig): void;
/**
* Get the current recording status
*/
getStatus(context: RecordingStrategyContext): SessionRecordingStatus;
/**
* Get the minimum duration for this session (if any)
*/
getMinimumDuration(sessionId: string): number | null;
/**
* Check URL triggers on each navigation
* Note: URL is read from window.location.href internally
*/
checkUrlTriggers(sessionId: string, onPause: () => void, onResume: () => void, onActivate: (triggerType: TriggerType, matchDetail?: string) => void): void;
/**
* Setup event trigger listeners
*/
setupEventTriggerListeners(onEvent: (callback: (event: CaptureResult) => void) => () => void, sessionId: string, onActivate: (triggerType: TriggerType, matchDetail?: string) => void): (() => void) | undefined;
/**
* Make sampling decisions for the session
*/
makeSamplingDecisions(sessionId: string): void;
/**
* Ensure a sampling decision exists for this session, re-deciding from the strategy's own
* config when it is missing (e.g. wiped by posthog.reset()). No-op when sampling isn't configured.
*/
ensureSamplingDecision(sessionId: string): void;
/**
* Called after the initial buffer flush (performance optimization hook)
*/
onFlushComplete(): void;
/**
* Clean up persistence keys for conditional recording
*/
clearConditionalRecordingPersistence(): void;
/**
* Update session properties with active trigger information
*/
updateActiveTriggers(sessionId: string): void;
/**
* Check if triggers are in pending state (waiting for activation)
*/
hasPendingTriggers(sessionId: string): boolean;
/**
* Describe trigger conditions that are currently waiting for activation without persisting debug state.
*/
getPendingTriggerConditions(sessionId: string): string[];
/**
* Stop and cleanup the strategy
*/
stop(): void;
}
/**
* V1 Strategy: Legacy trigger matching with global URL/Event/Flag triggers
*/
export declare class V1RecordingStrategy implements RecordingStrategy {
private readonly _instance;
private readonly _urlTriggerMatching;
private readonly _eventTriggerMatching;
private readonly _linkedFlagMatching;
private readonly _reportStarted;
private readonly _tryTakeFullSnapshot;
private readonly _onTriggerActivated;
private _triggerStatusMatcher;
private _removeEventTriggerCaptureHook;
private _sampleRate;
private _recordingStatusFunction;
constructor(_instance: PostHog, _urlTriggerMatching: URLTriggerMatching, _eventTriggerMatching: EventTriggerMatching, _linkedFlagMatching: LinkedFlagMatching, _reportStarted: (reason: SessionStartReason, payload?: Record<string, any>) => void, _tryTakeFullSnapshot: () => void, _onTriggerActivated: () => void);
onRemoteConfig(config: SessionRecordingPersistedConfig): void;
getStatus(context: RecordingStrategyContext): SessionRecordingStatus;
getMinimumDuration(sessionId: string): number | null;
checkUrlTriggers(sessionId: string, onPause: () => void, onResume: () => void, onActivate: (triggerType: TriggerType, matchDetail?: string) => void): void;
setupEventTriggerListeners(onEvent: (callback: (event: CaptureResult) => void) => () => void, sessionId: string, onActivate: (triggerType: TriggerType, matchDetail?: string) => void): (() => void) | undefined;
makeSamplingDecisions(sessionId: string): void;
ensureSamplingDecision(sessionId: string): void;
onFlushComplete(): void;
clearConditionalRecordingPersistence(): void;
updateActiveTriggers(sessionId: string): void;
hasPendingTriggers(sessionId: string): boolean;
getPendingTriggerConditions(sessionId: string): string[];
stop(): void;
}
/**
* V2 Strategy: Trigger groups with per-group sampling and union behavior
*/
export declare class V2TriggerGroupStrategy implements RecordingStrategy {
private readonly _instance;
private readonly _urlTriggerMatching;
private readonly _reportStarted;
private readonly _tryAddCustomEvent;
private readonly _onTriggerActivated;
private _triggerGroupMatchers;
private _triggerGroupSamplingResults;
private _hasCompletedInitialFlush;
private _removeEventTriggerCaptureHook;
constructor(_instance: PostHog, _urlTriggerMatching: URLTriggerMatching, _reportStarted: (reason: SessionStartReason, payload?: Record<string, any>) => void, _tryAddCustomEvent: (tag: string, payload: any) => void, _onTriggerActivated: (triggerType?: TriggerType) => void);
onRemoteConfig(config: SessionRecordingPersistedConfig): void;
getStatus(context: RecordingStrategyContext): SessionRecordingStatus;
getMinimumDuration(sessionId: string): number | null;
checkUrlTriggers(sessionId: string, onPause: () => void, onResume: () => void, onActivate: (triggerType: TriggerType, matchDetail?: string) => void): void;
setupEventTriggerListeners(onEvent: (callback: (event: CaptureResult) => void) => () => void, sessionId: string, onActivate: (triggerType: TriggerType, matchDetail?: string) => void): (() => void) | undefined;
makeSamplingDecisions(sessionId: string): void;
ensureSamplingDecision(sessionId: string): void;
onFlushComplete(): void;
clearConditionalRecordingPersistence(): void;
updateActiveTriggers(sessionId: string): void;
hasPendingTriggers(sessionId: string): boolean;
getPendingTriggerConditions(sessionId: string): string[];
stop(): void;
private _checkGroupLevelProperties;
private _setupTriggerGroups;
}