PostHog Node.js SDK
SDK Version:
PostHog
Initialization methods
PostHogpublic
Initialize a new PostHog client instance.
Parameters
| Name | Type |
|---|---|
apiKey | string |
Your PostHog project API key | |
options? | PostHogOptions |
Configuration options for the client | |
Examples
Returns
| Type |
|---|
any |
debugpublic
Enable or disable debug logging.
Parameters
| Name | Type |
|---|---|
enabled? | boolean |
Whether to enable debug logging | |
Examples
Returns
| Type |
|---|
void |
getLibraryVersionpublic
Get the library version from package.json.
Examples
Returns
| Type |
|---|
string |
getPersistedPropertypublic
Get a persisted property value from memory storage.
Parameters
| Name | Type |
|---|---|
key | PostHogPersistedProperty |
The property key to retrieve | |
Examples
Returns
| Type | |
|---|---|
| Union of | any |
undefined |
setPersistedPropertypublic
Set a persisted property value in memory storage.
Parameters
| Name | Type |
|---|---|
key | PostHogPersistedProperty |
The property key to set | |
value | any | null |
The value to store (null to remove) | |
Examples
Returns
| Type |
|---|
void |
Capture methods
Examples
Returns
| Type |
|---|
void |
captureImmediatepublic
Capture an event immediately (synchronously).
Parameters
| Name | Type |
|---|---|
props | EventMessage |
The event properties | |
Examples
Returns
| Type |
|---|
Promise<void> |
Context methods
getContextpublic
Get the current context data.
Examples
Returns
| Type | |
|---|---|
| Union of | ContextData |
undefined |
withContextpublic
Run a function with specific context that will be applied to all events captured within that context. It propagates the context to all subsequent calls down the call stack. Context properties like tags and sessionId will be automatically attached to all events. By default, nested contexts inherit from parent contexts. Use { fresh: true } to start with a clean context.
Parameters
| Name | Type |
|---|---|
data | Partial<ContextData> |
Context data to apply (sessionId, distinctId, properties, enableExceptionAutocapture) | |
fn | () => T |
Function to run with the context | |
options? | ContextOptions |
Context options (fresh: true to start with clean context instead of inheriting) | |
Examples
Returns
| Type |
|---|
T |
Error tracking methods
captureExceptionpublic
Capture an error exception as an event.
Parameters
| Name | Type |
|---|---|
error | unknown |
The error to capture | |
distinctId? | string |
Optional user distinct ID | |
additionalProperties? | Record<string | number, any> |
Optional additional properties to include | |
Examples
Returns
| Type |
|---|
void |
captureExceptionImmediatepublic
Capture an error exception as an event immediately (synchronously).
Parameters
| Name | Type |
|---|---|
error | unknown |
The error to capture | |
distinctId? | string |
Optional user distinct ID | |
additionalProperties? | Record<string | number, any> |
Optional additional properties to include | |
Examples
Returns
| Type |
|---|
Promise<void> |
Feature flags methods
getAllFlagspublic
Get all feature flag values for a specific user.
Parameters
| Name | Type |
|---|---|
distinctId | string |
The user's distinct ID | |
options? | {
groups?: Record<string, string>;
personProperties?: Record<string, string>;
groupProperties?: Record<string, Record<string, string>>;
onlyEvaluateLocally?: boolean;
disableGeoip?: boolean;
flagKeys?: string[];
} |
Optional configuration for flag evaluation | |
Examples
Returns
| Type |
|---|
Promise<Record<string, FeatureFlagValue>> |
getAllFlagsAndPayloadspublic
Get all feature flag values and payloads for a specific user.
Parameters
| Name | Type |
|---|---|
distinctId | string |
The user's distinct ID | |
options? | {
groups?: Record<string, string>;
personProperties?: Record<string, string>;
groupProperties?: Record<string, Record<string, string>>;
onlyEvaluateLocally?: boolean;
disableGeoip?: boolean;
flagKeys?: string[];
} |
Optional configuration for flag evaluation | |
Examples
Returns
| Type |
|---|
Promise<PostHogFlagsAndPayloadsResponse> |
getFeatureFlagpublic
Get the value of a feature flag for a specific user.
Parameters
| Name | Type |
|---|---|
key | string |
The feature flag key | |
distinctId | string |
The user's distinct ID | |
options? | {
groups?: Record<string, string>;
personProperties?: Record<string, string>;
groupProperties?: Record<string, Record<string, string>>;
onlyEvaluateLocally?: boolean;
sendFeatureFlagEvents?: boolean;
disableGeoip?: boolean;
} |
Optional configuration for flag evaluation | |
Examples
Returns
| Type | |
|---|---|
| Union of | Promise<FeatureFlagValue |
undefined> |
getFeatureFlagPayloadpublic
Get the payload for a feature flag.
Parameters
| Name | Type |
|---|---|
key | string |
The feature flag key | |
distinctId | string |
The user's distinct ID | |
matchValue? | FeatureFlagValue |
Optional match value to get payload for | |
options? | {
groups?: Record<string, string>;
personProperties?: Record<string, string>;
groupProperties?: Record<string, Record<string, string>>;
onlyEvaluateLocally?: boolean;
sendFeatureFlagEvents?: boolean;
disableGeoip?: boolean;
} |
Optional configuration for flag evaluation | |
Examples
Returns
| Type | |
|---|---|
| Union of | Promise<JsonType |
undefined> |
getRemoteConfigPayloadpublic
Get the remote config payload for a feature flag.
Parameters
| Name | Type |
|---|---|
flagKey | string |
The feature flag key | |
Examples
Returns
| Type | |
|---|---|
| Union of | Promise<JsonType |
undefined> |
isFeatureEnabledpublic
Check if a feature flag is enabled for a specific user.
Parameters
| Name | Type |
|---|---|
key | string |
The feature flag key | |
distinctId | string |
The user's distinct ID | |
options? | {
groups?: Record<string, string>;
personProperties?: Record<string, string>;
groupProperties?: Record<string, Record<string, string>>;
onlyEvaluateLocally?: boolean;
sendFeatureFlagEvents?: boolean;
disableGeoip?: boolean;
} |
Optional configuration for flag evaluation | |
Examples
Returns
| Type | |
|---|---|
| Union of | Promise<boolean |
undefined> |
isLocalEvaluationReadypublic
Check if local evaluation of feature flags is ready.
Examples
Returns
| Type |
|---|
boolean |
reloadFeatureFlagspublic
Reload feature flag definitions from the server for local evaluation.
Examples
Returns
| Type |
|---|
Promise<void> |
waitForLocalEvaluationReadypublic
Wait for local evaluation of feature flags to be ready.
Parameters
| Name | Type |
|---|---|
timeoutMs? | number |
Timeout in milliseconds (default: 30000) | |
Examples
Returns
| Type |
|---|
Promise<boolean> |
Identification methods
aliaspublic
Create an alias to link two distinct IDs together.
Parameters
| Name | Type |
|---|---|
data | {
distinctId: string;
alias: string;
disableGeoip?: boolean;
} |
The alias data containing distinctId and alias | |
Examples
Returns
| Type |
|---|
void |
aliasImmediatepublic
Create an alias to link two distinct IDs together immediately (synchronously).
Parameters
| Name | Type |
|---|---|
data | {
distinctId: string;
alias: string;
disableGeoip?: boolean;
} |
The alias data containing distinctId and alias | |
Examples
Returns
| Type |
|---|
Promise<void> |
getCustomUserAgentpublic
Get the custom user agent string for this client.
Examples
Returns
| Type |
|---|
string |
groupIdentifypublic
Create or update a group and its properties.
Parameters
| Name | Type |
|---|---|
{ groupType, groupKey, properties, distinctId, disableGeoip } | GroupIdentifyMessage |
Examples
Returns
| Type |
|---|
void |
identifypublic
Identify a user and set their properties.
Parameters
| Name | Type |
|---|---|
{ distinctId, properties, disableGeoip } | IdentifyMessage |
Examples
Returns
| Type |
|---|
void |
identifyImmediatepublic
Identify a user and set their properties immediately (synchronously).
Parameters
| Name | Type |
|---|---|
{ distinctId, properties, disableGeoip } | IdentifyMessage |
Examples
Returns
| Type |
|---|
Promise<void> |
Privacy methods
disablepublic
Disable the PostHog client (opt-out).
Examples
Returns
| Type |
|---|
Promise<void> |
enablepublic
Enable the PostHog client (opt-in).
Examples
Returns
| Type |
|---|
Promise<void> |
Other methods
getLibraryIdpublic
Examples
Returns
| Type |
|---|
string |
initializeContextpublic
Examples
Returns
| Type |
|---|
PostHogContext |
prepareEventMessagepublic
Parameters
| Name | Type |
|---|---|
props | EventMessage |
Examples
Returns
| Type |
|---|
Promise<{
distinctId: string;
event: string;
properties: PostHogEventProperties;
options: PostHogCaptureOptions;
}> |