Capacitor PostHog Plugin

Unofficial Capacitor plugin for PostHog.[^1]

Use Cases

The PostHog plugin is typically used to understand how users interact with an app, for example:

• Product analytics: Capture custom events and screen views to analyze how users move through your app.
• User identification: Identify users with a distinct ID, assign aliases, and associate their events with groups.
• Feature flags: Roll out features gradually by checking feature flags and their payloads at runtime.
• Session replay: Record user sessions to understand usage patterns and debug issues.
• Error tracking: Capture exceptions manually or automatically to monitor the stability of your app.

Compatibility

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 --skill capacitor-plugins

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

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,
      "captureApplicationLifecycleEvents": undefined,
      "autoCaptureExceptions": 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,
      captureApplicationLifecycleEvents: undefined,
      autoCaptureExceptions: undefined,
    },
  },
};

export default config;

Demo

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

Usage

The following examples show how to set up the SDK, capture events, track screen views, identify users, associate users with a group, manage super properties, reset the user, and flush queued events.

Set up the SDK

Call setup(...) before any other method. Alternatively, on Android and iOS, you can configure the plugin in your Capacitor configuration file (see Configuration); in that case, you must not call this method:

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

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

Capture events

Capture a custom event with optional properties:

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

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

Track screen views

Send a screen event with the title of the screen. Only available on Android and iOS:

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

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

Identify users

Identify the current user with a distinct ID and set person properties. You can also assign another distinct ID to the current user using alias(...):

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

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

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

Associate users with a group

Associate the events of the current user with a group, for example a company or a team:

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

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

Manage super properties

Register a super property that is sent with every event, and unregister it when it is no longer needed:

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

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

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

Reset the user

Reset the current user's ID and anonymous ID, for example after a logout:

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

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

Flush queued events

Manually flush all events in the queue. Only available on Android and iOS:

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

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

API

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

alias(...)

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

Assign another distinct ID to the current user.

Since: 6.0.0

capture(...)

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

Capture an event.

Since: 6.0.0

captureException(...)

captureException(options: CaptureExceptionOptions) => Promise<void>

Capture an exception.

Since: 8.5.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.

Returns: Promise<GetFeatureFlagResult>

Since: 7.0.0

getFeatureFlagPayload(...)

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

Get the payload of a feature flag.

Returns: Promise<GetFeatureFlagPayloadResult>

Since: 7.1.0

getSessionId()

getSessionId() => Promise<GetSessionIdResult>

Get the current session ID.

Returns: Promise<GetSessionIdResult>

Since: 8.6.0

group(...)

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

Associate the events for that user with a group.

Since: 6.0.0

identify(...)

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

Identify the current user.

Since: 6.0.0

isFeatureEnabled(...)

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

Check if a feature flag is enabled.

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.

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.

Since: 6.0.0

setPersonProperties(...)

setPersonProperties(options: SetPersonPropertiesOptions) => Promise<void>

Set properties on the person associated with the current user.

Since: 8.6.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.

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.

Since: 6.0.0

Interfaces

AliasOptions

CaptureOptions

CaptureExceptionOptions

StackFrame

GetDistinctIdResult

GetFeatureFlagResult

GetFeatureFlagOptions

GetFeatureFlagPayloadResult

GetFeatureFlagPayloadOptions

GetSessionIdResult

GroupOptions

IdentifyOptions

IsFeatureEnabledResult

IsFeatureEnabledOptions

IsOptOutResult

RegisterOptions

ScreenOptions

SetPersonPropertiesOptions

SetupOptions

SessionReplayOptions

UnregisterOptions

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.

FAQ

Do I have to call the setup method before using the plugin?

Yes, the setup(...) method should be called before any other method. Alternatively, on Android and iOS, you can configure the plugin in your Capacitor configuration file (see Configuration). In that case, you must not call the setup(...) method.

What is the difference between the apiHost and host options?

The host option is a deprecated alias for apiHost. Both point to the API host of your PostHog instance or reverse proxy. If both options are provided, apiHost takes precedence, so new projects should only use apiHost.

How do I use the plugin with a reverse proxy?

Set the apiHost option to your proxy URL and the uiHost option to your PostHog app host, such as https://us.posthog.com or https://eu.posthog.com. Note that uiHost is only available on Web. See the Reverse Proxy section for more details.

How do I enable session replay?

Set the enableSessionReplay option to true in the setup(...) method or in your Capacitor configuration file, and fine-tune the recording behavior with the sessionReplayConfig option. You can also start and stop recording manually using the startSessionRecording() and stopSessionRecording() methods.

How can users opt out of tracking?

Call the optOut() method to stop event capturing and the optIn() method to re-enable it. You can check the current state with isOptOut() or opt users out by default with the optOut setup option. On Web with cookielessMode: 'on_reject', opting out switches to cookieless anonymous tracking instead of stopping capturing entirely.

Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

Related Plugins

• Analytics: Unofficial Capacitor plugin for Firebase Analytics.
• Crisp: Unofficial Capacitor plugin for the Crisp live chat and customer support platform.
• Formbricks: Unofficial Capacitor plugin for Formbricks to run in-app surveys.
• Grafana Faro: Unofficial Capacitor plugin for Grafana Faro to monitor your app.
• TikTok App Events: Unofficial Capacitor plugin for the TikTok App Events SDK.

Newsletter

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

Changelog

See CHANGELOG.md.

License

See LICENSE.

[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by PostHog, Inc. or any of their affiliates or subsidiaries.