@capawesome/capacitor-posthog¶

Unofficial Capacitor plugin for PostHog.¹

Deliver Live Updates to your Capacitor app with Capawesome Cloud

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Compatibility¶

Plugin Version	Capacitor Version	Status
8.x.x	>=8.x.x	Active support
7.x.x	7.x.x	Deprecated

Installation¶

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills

Then use the following prompt:

 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-posthog` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capawesome/capacitor-posthog posthog-js
npx cap sync

Android¶

Variables¶

If needed, you can define the following project variable in your app’s variables.gradle file to change the default version of the dependency:

$androidxCoreKtxVersion version of androidx.core:core-ktx (default: 1.13.1)
$posthogVersion version of com.posthog:posthog-android (default: 3.27.2)

This can be useful if you encounter dependency conflicts with other plugins in your project.

Configuration¶

Prop	Type	Description	Default	Since
`apiKey`	`string`	The API key of your PostHog project.		7.1.0
`apiHost`	`string`	The API host of your PostHog instance or reverse proxy.	`'https://us.i.posthog.com'`	8.3.0
`host`	`string`	The API host of your PostHog instance. Deprecated alias for `apiHost`.	`'https://us.i.posthog.com'`	7.1.0
`uiHost`	`string`	The PostHog UI host used when `apiHost` points to a reverse proxy. Only available on Web.		8.3.0
`enableSessionReplay`	`boolean`	Whether to enable session recording automatically.	`false`	7.3.0
`sessionReplayConfig`	`SessionReplayOptions`	Session recording configuration options.		7.3.0

Examples¶

In capacitor.config.json:

{
  "plugins": {
    "Posthog": {
      "apiKey": 'phc_g8wMenebiIQ1pYd5v9Vy7oakn6MczVKIsNG5ZHCspdy',
      "apiHost": 'https://eu.i.posthog.com',
      "host": 'https://eu.i.posthog.com',
      "uiHost": 'https://eu.posthog.com',
      "enableSessionReplay": undefined,
      "sessionReplayConfig": undefined
    }
  }
}

In capacitor.config.ts:

/// <reference types="@capawesome/capacitor-posthog" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    Posthog: {
      apiKey: 'phc_g8wMenebiIQ1pYd5v9Vy7oakn6MczVKIsNG5ZHCspdy',
      apiHost: 'https://eu.i.posthog.com',
      host: 'https://eu.i.posthog.com',
      uiHost: 'https://eu.posthog.com',
      enableSessionReplay: undefined,
      sessionReplayConfig: undefined,
    },
  },
};

export default config;

Demo¶

A working example can be found here: robingenz/capacitor-plugin-demo

Usage¶

import { Posthog } from '@capawesome/capacitor-posthog';

const alias = async () => {
  await Posthog.alias({
    alias: 'new-distinct-id',
  });
};

const capture = async () => {
  await Posthog.capture({
    event: 'event',
    properties: {
      key: 'value',
    },
  });
};

const flush = async () => {
  await Posthog.flush();
};

const group = async () => {
  await Posthog.group({
    type: 'group',
    key: 'key',
    groupProperties: {
      key: 'value',
    },
  });
};

const identify = async () => {
  await Posthog.identify({
    distinctId: 'distinct-id',
    userProperties: {
      key: 'value',
    },
  });
};

const register = async () => {
  await Posthog.register({
    key: 'super-property',
    value: 'super-value',
  });
};

const reset = async () => {
  await Posthog.reset();
};

const screen = async () => {
  await Posthog.screen({
    screenTitle: 'screen',
    properties: {
      key: 'value',
    },
  });
};

const setup = async () => {
  await Posthog.setup({
    apiKey: 'YOUR_API_KEY',
    apiHost: 'https://eu.i.posthog.com',
  });
};

const unregister = async () => {
  await Posthog.unregister({
    key: 'super-property',
  });
};

API¶

alias(...)
capture(...)
flush()
getDistinctId()
getFeatureFlag(...)
getFeatureFlagPayload(...)
group(...)
identify(...)
isFeatureEnabled(...)
isOptOut()
optIn()
optOut()
register(...)
reloadFeatureFlags()
reset()
screen(...)
setup(...)
startSessionRecording()
stopSessionRecording()
unregister(...)
Interfaces
Type Aliases

alias(...)¶

alias(options: AliasOptions) => Promise<void>

Assign another distinct ID to the current user.

Param	Type
`options`	`AliasOptions`

Since: 6.0.0

capture(...)¶

capture(options: CaptureOptions) => Promise<void>

Capture an event.

Param	Type
`options`	`CaptureOptions`

Since: 6.0.0

flush()¶

flush() => Promise<void>

Flush all events in the queue.

Only available on Android and iOS.

Since: 6.0.0

getDistinctId()¶

getDistinctId() => Promise<GetDistinctIdResult>

Get the current distinct ID.

Returns: Promise<GetDistinctIdResult>

Since: 8.2.0

getFeatureFlag(...)¶

getFeatureFlag(options: GetFeatureFlagOptions) => Promise<GetFeatureFlagResult>

Get the value of a feature flag.

Param	Type
`options`	`GetFeatureFlagOptions`

Returns: Promise<GetFeatureFlagResult>

Since: 7.0.0

getFeatureFlagPayload(...)¶

getFeatureFlagPayload(options: GetFeatureFlagPayloadOptions) => Promise<GetFeatureFlagPayloadResult>

Get the payload of a feature flag.

Param	Type
`options`	`GetFeatureFlagPayloadOptions`

Returns: Promise<GetFeatureFlagPayloadResult>

Since: 7.1.0

group(...)¶

group(options: GroupOptions) => Promise<void>

Associate the events for that user with a group.

Param	Type
`options`	`GroupOptions`

Since: 6.0.0

identify(...)¶

identify(options: IdentifyOptions) => Promise<void>

Identify the current user.

Param	Type
`options`	`IdentifyOptions`

Since: 6.0.0

isFeatureEnabled(...)¶

isFeatureEnabled(options: IsFeatureEnabledOptions) => Promise<IsFeatureEnabledResult>

Check if a feature flag is enabled.

Param	Type
`options`	`IsFeatureEnabledOptions`

Returns: Promise<IsFeatureEnabledResult>

Since: 7.0.0

isOptOut()¶

isOptOut() => Promise<IsOptOutResult>

Check if the user has opted out of capturing.

Returns: Promise<IsOptOutResult>

Since: 8.1.0

optIn()¶

optIn() => Promise<void>

Opt in to event capturing.

Since: 8.1.0

optOut()¶

optOut() => Promise<void>

Opt out of event capturing.

On Web with cookielessMode: 'on_reject': switches to cookieless anonymous tracking. On iOS/Android: stops all event capturing entirely.

Since: 8.1.0

register(...)¶

register(options: RegisterOptions) => Promise<void>

Register a new super property. This property will be sent with every event.

Param	Type
`options`	`RegisterOptions`

Since: 6.0.0

reloadFeatureFlags()¶

reloadFeatureFlags() => Promise<void>

Reload the feature flags.

Since: 7.0.0

reset()¶

reset() => Promise<void>

Reset the current user's ID and anonymous ID.

Since: 6.0.0

screen(...)¶

screen(options: ScreenOptions) => Promise<void>

Send a screen event.

Only available on Android and iOS.

Param	Type
`options`	`ScreenOptions`

Since: 6.0.0

setup(...)¶

setup(options: SetupOptions) => Promise<void>

Setup the PostHog SDK with the provided options.

Attention: This method should be called before any other method. Alternatively, on Android and iOS, you can configure this plugin in your Capacitor Configuration file. In this case, you must not call this method.

Param	Type
`options`	`SetupOptions`

Since: 6.0.0

startSessionRecording()¶

startSessionRecording() => Promise<void>

Start session recording.

Since: 7.3.0

stopSessionRecording()¶

stopSessionRecording() => Promise<void>

Stop session recording.

Since: 7.3.0

unregister(...)¶

unregister(options: UnregisterOptions) => Promise<void>

Remove a super property.

Param	Type
`options`	`UnregisterOptions`

Since: 6.0.0

Interfaces¶

AliasOptions¶

Prop	Type	Description	Since
`alias`	`string`	The new distinct ID to assign to the current user.	6.0.0

CaptureOptions¶

Prop	Type	Description	Since
`event`	`string`	The name of the event to capture.	6.0.0
`properties`	`Record<string, any>`	The properties to send with the event.	6.0.0

GetDistinctIdResult¶

Prop	Type	Description	Since
`distinctId`	`string`	The current distinct ID.	8.2.0

GetFeatureFlagResult¶

Prop	Type	Description	Since
`value`	`string \| boolean \| null`	The value of the feature flag. If the feature flag does not exist, the value will be `null`.	7.0.0

GetFeatureFlagOptions¶

Prop	Type	Description	Since
`key`	`string`	The key of the feature flag.	7.0.0

GetFeatureFlagPayloadResult¶

Prop	Type	Description	Since
`value`	`JsonType`	The value of the feature flag payload.	7.1.0

GetFeatureFlagPayloadOptions¶

Prop	Type	Description	Since
`key`	`string`	The key of the feature flag.	7.1.0

GroupOptions¶

Prop	Type	Description	Since
`type`	`string`	The group type.	6.0.0
`key`	`string`	The group key.	6.0.0
`groupProperties`	`Record<string, any>`	The properties to send with the group event.	6.0.0

IdentifyOptions¶

Prop	Type	Description	Since
`distinctId`	`string`	The distinct ID of the user.	6.0.0
`userProperties`	`Record<string, any>`	The person properties to set.	6.0.0

IsFeatureEnabledResult¶

Prop	Type	Description	Since
`enabled`	`boolean`	Whether the feature flag is enabled. If the feature flag does not exist, the value will be `false`.	7.0.0

IsFeatureEnabledOptions¶

Prop	Type	Description	Since
`key`	`string`	The key of the feature flag.	7.0.0

IsOptOutResult¶

Prop	Type	Description	Since
`optedOut`	`boolean`	Whether the user has opted out of capturing.	8.1.0

RegisterOptions¶

Prop	Type	Description	Since
`key`	`string`	The name of the super property.	6.0.0
`value`	`any`	The value of the super property.	6.0.0

ScreenOptions¶

Prop	Type	Description	Since
`screenTitle`	`string`	The name of the screen.	6.0.0
`properties`	`Record<string, any>`	The properties to send with the screen event.	6.0.0

SetupOptions¶

Prop	Type	Description	Default	Since
`apiKey`	`string`	The API key of your PostHog project.		6.0.0
`apiHost`	`string`	The API host of your PostHog instance or reverse proxy. If both `apiHost` and `host` are provided, `apiHost` takes precedence.	`'https://us.i.posthog.com'`	8.3.0
`host`	`string`	The API host of your PostHog instance. Deprecated alias for `apiHost`.	`'https://us.i.posthog.com'`	6.0.0
`uiHost`	`string`	The PostHog UI host used when `apiHost` points to a reverse proxy. Only available on Web.		8.3.0
`cookielessMode`	`'always' \| 'on_reject'`	Cookieless tracking mode. - `'always'`: Always use cookieless tracking with server-side anonymous hash. - `'on_reject'`: Normal tracking until `optOut()` is called, then switches to cookieless. Only available on Web. Requires cookieless mode to be enabled in PostHog project settings.		8.1.0
`enableSessionReplay`	`boolean`	Whether to enable session recording automatically.	`false`	7.3.0
`optOut`	`boolean`	Whether to opt out of capturing by default. User must call `optIn()` to enable capturing.	`false`	8.1.0
`sessionReplayConfig`	`SessionReplayOptions`	Session replay configuration options.		7.3.0

SessionReplayOptions¶

Prop	Type	Description	Default	Since
`screenshotMode`	`boolean`	Enable screenshot mode for session recordings. WARNING: This may capture sensitive information.	`false`	7.3.0
`maskAllTextInputs`	`boolean`	Mask all text input fields in session recordings.	`true`	7.3.0
`maskAllImages`	`boolean`	Mask all images in session recordings.	`true`	7.3.0
`maskAllSandboxedViews`	`boolean`	Mask all sandboxed system views (iOS-specific).	`true`	7.3.0
`captureNetworkTelemetry`	`boolean`	Capture network telemetry in session recordings.	`false`	7.3.0
`debouncerDelay`	`number`	Debounce delay for session recording snapshots (in seconds).	`1.0`	7.3.0

UnregisterOptions¶

Prop	Type	Description	Since
`key`	`string`	The name of the super property to remove.	6.0.0

Type Aliases¶

JsonType¶

string | number | boolean | null | { [key: string]: JsonType; } | JsonType[]

Advanced¶

Reverse Proxy¶

For PostHog managed reverse proxy, set apiHost to your proxy URL and uiHost to your PostHog app host (https://us.posthog.com or https://eu.posthog.com). host remains supported as a deprecated alias for apiHost. uiHost is only available on Web.

Changelog¶

See CHANGELOG.md.

License¶

See LICENSE.

This project is not affiliated with, endorsed by, sponsored by, or approved by PostHog, Inc. or any of their affiliates or subsidiaries. ↩

@capawesome/capacitor-posthog¶

Newsletter¶

Compatibility¶

Installation¶

Android¶

Variables¶

Configuration¶

Examples¶

Demo¶

Usage¶

API¶

alias(...)¶

capture(...)¶

flush()¶

getDistinctId()¶

getFeatureFlag(...)¶

getFeatureFlagPayload(...)¶

group(...)¶

identify(...)¶

isFeatureEnabled(...)¶

isOptOut()¶

optIn()¶

optOut()¶

register(...)¶

reloadFeatureFlags()¶

reset()¶

screen(...)¶

setup(...)¶

startSessionRecording()¶

stopSessionRecording()¶

unregister(...)¶

Interfaces¶

AliasOptions¶

CaptureOptions¶

GetDistinctIdResult¶

GetFeatureFlagResult¶

GetFeatureFlagOptions¶

GetFeatureFlagPayloadResult¶

GetFeatureFlagPayloadOptions¶

GroupOptions¶

IdentifyOptions¶

IsFeatureEnabledResult¶

IsFeatureEnabledOptions¶

IsOptOutResult¶

RegisterOptions¶

ScreenOptions¶

SetupOptions¶

SessionReplayOptions¶

UnregisterOptions¶

Type Aliases¶

JsonType¶

Advanced¶

Reverse Proxy¶

Changelog¶

License¶