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> |
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 |
prepareEventMessagepublic
Parameters
| Name | Type |
|---|---|
props | EventMessage |
Examples
Returns
| Type |
|---|
Promise<{
distinctId: string;
event: string;
properties: PostHogEventProperties;
options: PostHogCaptureOptions;
}> |