--- description: Unofficial Capacitor plugin for PostHog SDK to track user interactions and events in your app with support for Android, iOS, and Web. title: Capacitor PostHog Plugin for Android, iOS & Web - Capawesome image: https://capawesome.io/docs/assets/images/social/sdks/capacitor/posthog.png --- [Skip to content ](#capacitor-posthog-plugin) [πŸ–₯️ Introducing the **Capacitor Electron Platform** β€” build desktop apps for macOS, Windows, and Linux. Free & open source. ](/blog/announcing-the-capacitor-electron-platform/) * [ SDKs ](/docs/sdks/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ Gyroscope ](/docs/sdks/capacitor/gyroscope/) * [ Haptics ](/docs/sdks/capacitor/haptics/) * [ Home Indicator ](/docs/sdks/capacitor/home-indicator/) * [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/) * [ Install Referrer ](/docs/sdks/capacitor/install-referrer/) * [ Intercom ](/docs/sdks/capacitor/intercom/) * [ Intune ](/docs/sdks/capacitor/intune/) * [ Keep Awake ](/docs/sdks/capacitor/keep-awake/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Light Sensor ](/docs/sdks/capacitor/light-sensor/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Localization ](/docs/sdks/capacitor/localization/) * [ Mail Composer ](/docs/sdks/capacitor/mail-composer/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ Network ](/docs/sdks/capacitor/network/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ Node.js ](/docs/sdks/capacitor/nodejs/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Passkeys ](/docs/sdks/capacitor/passkeys/) * [ Password Autofill ](/docs/sdks/capacitor/password-autofill/) * [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/) * [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Permissions ](/docs/sdks/capacitor/permissions/) * [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/) * [ PixLive ](/docs/sdks/capacitor/pixlive/) * PostHog [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Configuration ](#configuration) * [ Demo ](#demo) * [ Usage ](#usage) * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Advanced ](#advanced) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ License ](#license) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/) * [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Root Detection ](/docs/sdks/capacitor/root-detection/) * [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screen Reader ](/docs/sdks/capacitor/screen-reader/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/) * [ Shake ](/docs/sdks/capacitor/shake/) * [ Silent Mode ](/docs/sdks/capacitor/silent-mode/) * [ SIM ](/docs/sdks/capacitor/sim/) * [ SMS Composer ](/docs/sdks/capacitor/sms-composer/) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ System WebView ](/docs/sdks/capacitor/system-webview/) * [ Tauri ](/docs/sdks/capacitor/tauri/) * [ Text Interaction ](/docs/sdks/capacitor/text-interaction/) * [ Text Zoom ](/docs/sdks/capacitor/text-zoom/) * [ Thermal State ](/docs/sdks/capacitor/thermal-state/) * [ Toast ](/docs/sdks/capacitor/toast/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Volume ](/docs/sdks/capacitor/volume/) * [ Wallet ](/docs/sdks/capacitor/wallet/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ YouTube Player ](/docs/sdks/capacitor/youtube-player/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories * [ Configuration ](#configuration) * [ Demo ](#demo) * [ Usage ](#usage) * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Advanced ](#advanced) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ License ](#license) # Capacitor PostHog Plugin[ΒΆ](#capacitor-posthog-plugin "Permanent link") Unofficial Capacitor plugin for [PostHog](https://posthog.com/).[1](#fn:1) [ ![Deliver Live Updates to your Capacitor app with Capawesome Cloud](../../../assets/external/cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.69628c3f.png) ](https://cloud.capawesome.io/) ## Use Cases[ΒΆ](#use-cases "Permanent link") 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[ΒΆ](#compatibility "Permanent link") | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 8.x.x | \>=8.x.x | Active support | | 7.x.x | 7.x.x | Deprecated | ## Installation[ΒΆ](#installation "Permanent link") You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: `[](#%5F%5Fcodelineno-0-1)npx skills add capawesome-team/skills --skill capacitor-plugins ` Then use the following prompt: `` [](#%5F%5Fcodelineno-1-1) 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: `[](#%5F%5Fcodelineno-2-1)npm install @capawesome/capacitor-posthog posthog-js [](#%5F%5Fcodelineno-2-2)npx cap sync ` ### Android[ΒΆ](#android "Permanent link") #### Variables[ΒΆ](#variables "Permanent link") 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[ΒΆ](#configuration "Permanent link") | 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](#sessionreplayoptions) | Session recording configuration options. | | 7.3.0 | | **captureApplicationLifecycleEvents** | boolean | Whether to capture application lifecycle events. | true | 8.3.0 | | **autoCaptureExceptions** | boolean | Whether to automatically capture unhandled exceptions. | false | 8.5.0 | ### Examples[ΒΆ](#examples "Permanent link") In `capacitor.config.json`: `[](#%5F%5Fcodelineno-3-1){ [](#%5F%5Fcodelineno-3-2) "plugins": { [](#%5F%5Fcodelineno-3-3) "Posthog": { [](#%5F%5Fcodelineno-3-4) "apiKey": 'phc_g8wMenebiIQ1pYd5v9Vy7oakn6MczVKIsNG5ZHCspdy', [](#%5F%5Fcodelineno-3-5) "apiHost": 'https://eu.i.posthog.com', [](#%5F%5Fcodelineno-3-6) "host": 'https://eu.i.posthog.com', [](#%5F%5Fcodelineno-3-7) "uiHost": 'https://eu.posthog.com', [](#%5F%5Fcodelineno-3-8) "enableSessionReplay": undefined, [](#%5F%5Fcodelineno-3-9) "sessionReplayConfig": undefined, [](#%5F%5Fcodelineno-3-10) "captureApplicationLifecycleEvents": undefined, [](#%5F%5Fcodelineno-3-11) "autoCaptureExceptions": undefined [](#%5F%5Fcodelineno-3-12) } [](#%5F%5Fcodelineno-3-13) } [](#%5F%5Fcodelineno-3-14)} ` In `capacitor.config.ts`: `[](#%5F%5Fcodelineno-4-1)/// [](#%5F%5Fcodelineno-4-2) [](#%5F%5Fcodelineno-4-3)import { CapacitorConfig } from '@capacitor/cli'; [](#%5F%5Fcodelineno-4-4) [](#%5F%5Fcodelineno-4-5)const config: CapacitorConfig = { [](#%5F%5Fcodelineno-4-6) plugins: { [](#%5F%5Fcodelineno-4-7) Posthog: { [](#%5F%5Fcodelineno-4-8) apiKey: 'phc_g8wMenebiIQ1pYd5v9Vy7oakn6MczVKIsNG5ZHCspdy', [](#%5F%5Fcodelineno-4-9) apiHost: 'https://eu.i.posthog.com', [](#%5F%5Fcodelineno-4-10) host: 'https://eu.i.posthog.com', [](#%5F%5Fcodelineno-4-11) uiHost: 'https://eu.posthog.com', [](#%5F%5Fcodelineno-4-12) enableSessionReplay: undefined, [](#%5F%5Fcodelineno-4-13) sessionReplayConfig: undefined, [](#%5F%5Fcodelineno-4-14) captureApplicationLifecycleEvents: undefined, [](#%5F%5Fcodelineno-4-15) autoCaptureExceptions: undefined, [](#%5F%5Fcodelineno-4-16) }, [](#%5F%5Fcodelineno-4-17) }, [](#%5F%5Fcodelineno-4-18)}; [](#%5F%5Fcodelineno-4-19) [](#%5F%5Fcodelineno-4-20)export default config; ` ## Demo[ΒΆ](#demo "Permanent link") A working example can be found here: [robingenz/capacitor-plugin-demo](https://github.com/robingenz/capacitor-plugin-demo) ## Usage[ΒΆ](#usage "Permanent link") 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[ΒΆ](#set-up-the-sdk "Permanent link") Call `setup(...)` before any other method. Alternatively, on Android and iOS, you can configure the plugin in your Capacitor configuration file (see [Configuration](#configuration)); in that case, you must not call this method: `[](#%5F%5Fcodelineno-5-1)import { Posthog } from '@capawesome/capacitor-posthog'; [](#%5F%5Fcodelineno-5-2) [](#%5F%5Fcodelineno-5-3)const setup = async () => { [](#%5F%5Fcodelineno-5-4) await Posthog.setup({ [](#%5F%5Fcodelineno-5-5) apiKey: 'YOUR_API_KEY', [](#%5F%5Fcodelineno-5-6) apiHost: 'https://eu.i.posthog.com', [](#%5F%5Fcodelineno-5-7) }); [](#%5F%5Fcodelineno-5-8)}; ` ### Capture events[ΒΆ](#capture-events "Permanent link") Capture a custom event with optional properties: `[](#%5F%5Fcodelineno-6-1)import { Posthog } from '@capawesome/capacitor-posthog'; [](#%5F%5Fcodelineno-6-2) [](#%5F%5Fcodelineno-6-3)const capture = async () => { [](#%5F%5Fcodelineno-6-4) await Posthog.capture({ [](#%5F%5Fcodelineno-6-5) event: 'event', [](#%5F%5Fcodelineno-6-6) properties: { [](#%5F%5Fcodelineno-6-7) key: 'value', [](#%5F%5Fcodelineno-6-8) }, [](#%5F%5Fcodelineno-6-9) }); [](#%5F%5Fcodelineno-6-10)}; ` ### Track screen views[ΒΆ](#track-screen-views "Permanent link") Send a screen event with the title of the screen. Only available on Android and iOS: `[](#%5F%5Fcodelineno-7-1)import { Posthog } from '@capawesome/capacitor-posthog'; [](#%5F%5Fcodelineno-7-2) [](#%5F%5Fcodelineno-7-3)const screen = async () => { [](#%5F%5Fcodelineno-7-4) await Posthog.screen({ [](#%5F%5Fcodelineno-7-5) screenTitle: 'screen', [](#%5F%5Fcodelineno-7-6) properties: { [](#%5F%5Fcodelineno-7-7) key: 'value', [](#%5F%5Fcodelineno-7-8) }, [](#%5F%5Fcodelineno-7-9) }); [](#%5F%5Fcodelineno-7-10)}; ` ### Identify users[ΒΆ](#identify-users "Permanent link") 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(...)`: `[](#%5F%5Fcodelineno-8-1)import { Posthog } from '@capawesome/capacitor-posthog'; [](#%5F%5Fcodelineno-8-2) [](#%5F%5Fcodelineno-8-3)const identify = async () => { [](#%5F%5Fcodelineno-8-4) await Posthog.identify({ [](#%5F%5Fcodelineno-8-5) distinctId: 'distinct-id', [](#%5F%5Fcodelineno-8-6) userProperties: { [](#%5F%5Fcodelineno-8-7) key: 'value', [](#%5F%5Fcodelineno-8-8) }, [](#%5F%5Fcodelineno-8-9) }); [](#%5F%5Fcodelineno-8-10)}; [](#%5F%5Fcodelineno-8-11) [](#%5F%5Fcodelineno-8-12)const alias = async () => { [](#%5F%5Fcodelineno-8-13) await Posthog.alias({ [](#%5F%5Fcodelineno-8-14) alias: 'new-distinct-id', [](#%5F%5Fcodelineno-8-15) }); [](#%5F%5Fcodelineno-8-16)}; ` ### Associate users with a group[ΒΆ](#associate-users-with-a-group "Permanent link") Associate the events of the current user with a group, for example a company or a team: `[](#%5F%5Fcodelineno-9-1)import { Posthog } from '@capawesome/capacitor-posthog'; [](#%5F%5Fcodelineno-9-2) [](#%5F%5Fcodelineno-9-3)const group = async () => { [](#%5F%5Fcodelineno-9-4) await Posthog.group({ [](#%5F%5Fcodelineno-9-5) type: 'group', [](#%5F%5Fcodelineno-9-6) key: 'key', [](#%5F%5Fcodelineno-9-7) groupProperties: { [](#%5F%5Fcodelineno-9-8) key: 'value', [](#%5F%5Fcodelineno-9-9) }, [](#%5F%5Fcodelineno-9-10) }); [](#%5F%5Fcodelineno-9-11)}; ` ### Manage super properties[ΒΆ](#manage-super-properties "Permanent link") Register a super property that is sent with every event, and unregister it when it is no longer needed: `[](#%5F%5Fcodelineno-10-1)import { Posthog } from '@capawesome/capacitor-posthog'; [](#%5F%5Fcodelineno-10-2) [](#%5F%5Fcodelineno-10-3)const register = async () => { [](#%5F%5Fcodelineno-10-4) await Posthog.register({ [](#%5F%5Fcodelineno-10-5) key: 'super-property', [](#%5F%5Fcodelineno-10-6) value: 'super-value', [](#%5F%5Fcodelineno-10-7) }); [](#%5F%5Fcodelineno-10-8)}; [](#%5F%5Fcodelineno-10-9) [](#%5F%5Fcodelineno-10-10)const unregister = async () => { [](#%5F%5Fcodelineno-10-11) await Posthog.unregister({ [](#%5F%5Fcodelineno-10-12) key: 'super-property', [](#%5F%5Fcodelineno-10-13) }); [](#%5F%5Fcodelineno-10-14)}; ` ### Reset the user[ΒΆ](#reset-the-user "Permanent link") Reset the current user's ID and anonymous ID, for example after a logout: `[](#%5F%5Fcodelineno-11-1)import { Posthog } from '@capawesome/capacitor-posthog'; [](#%5F%5Fcodelineno-11-2) [](#%5F%5Fcodelineno-11-3)const reset = async () => { [](#%5F%5Fcodelineno-11-4) await Posthog.reset(); [](#%5F%5Fcodelineno-11-5)}; ` ### Flush queued events[ΒΆ](#flush-queued-events "Permanent link") Manually flush all events in the queue. Only available on Android and iOS: `[](#%5F%5Fcodelineno-12-1)import { Posthog } from '@capawesome/capacitor-posthog'; [](#%5F%5Fcodelineno-12-2) [](#%5F%5Fcodelineno-12-3)const flush = async () => { [](#%5F%5Fcodelineno-12-4) await Posthog.flush(); [](#%5F%5Fcodelineno-12-5)}; ` ## API[ΒΆ](#api "Permanent link") * [alias(...)](#alias) * [capture(...)](#capture) * [captureException(...)](#captureexception) * [flush()](#flush) * [getDistinctId()](#getdistinctid) * [getFeatureFlag(...)](#getfeatureflag) * [getFeatureFlagPayload(...)](#getfeatureflagpayload) * [group(...)](#group) * [identify(...)](#identify) * [isFeatureEnabled(...)](#isfeatureenabled) * [isOptOut()](#isoptout) * [optIn()](#optin) * [optOut()](#optout) * [register(...)](#register) * [reloadFeatureFlags()](#reloadfeatureflags) * [reset()](#reset) * [screen(...)](#screen) * [setup(...)](#setup) * [startSessionRecording()](#startsessionrecording) * [stopSessionRecording()](#stopsessionrecording) * [unregister(...)](#unregister) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) ### alias(...)[ΒΆ](#alias "Permanent link") `[](#%5F%5Fcodelineno-13-1)alias(options: AliasOptions) => Promise ` Assign another distinct ID to the current user. | Param | Type | | ----------- | ----------------------------- | | **options** | [AliasOptions](#aliasoptions) | **Since:** 6.0.0 --- ### capture(...)[ΒΆ](#capture "Permanent link") `[](#%5F%5Fcodelineno-14-1)capture(options: CaptureOptions) => Promise ` Capture an event. | Param | Type | | ----------- | --------------------------------- | | **options** | [CaptureOptions](#captureoptions) | **Since:** 6.0.0 --- ### captureException(...)[ΒΆ](#captureexception "Permanent link") `[](#%5F%5Fcodelineno-15-1)captureException(options: CaptureExceptionOptions) => Promise ` Capture an exception. | Param | Type | | ----------- | --------------------------------------------------- | | **options** | [CaptureExceptionOptions](#captureexceptionoptions) | **Since:** 8.5.0 --- ### flush()[ΒΆ](#flush "Permanent link") `[](#%5F%5Fcodelineno-16-1)flush() => Promise ` Flush all events in the queue. Only available on Android and iOS. **Since:** 6.0.0 --- ### getDistinctId()[ΒΆ](#getdistinctid "Permanent link") `[](#%5F%5Fcodelineno-17-1)getDistinctId() => Promise ` Get the current distinct ID. **Returns:** `Promise<[GetDistinctIdResult](#getdistinctidresult)>` **Since:** 8.2.0 --- ### getFeatureFlag(...)[ΒΆ](#getfeatureflag "Permanent link") `[](#%5F%5Fcodelineno-18-1)getFeatureFlag(options: GetFeatureFlagOptions) => Promise ` Get the value of a feature flag. | Param | Type | | ----------- | ----------------------------------------------- | | **options** | [GetFeatureFlagOptions](#getfeatureflagoptions) | **Returns:** `Promise<[GetFeatureFlagResult](#getfeatureflagresult)>` **Since:** 7.0.0 --- ### getFeatureFlagPayload(...)[ΒΆ](#getfeatureflagpayload "Permanent link") `[](#%5F%5Fcodelineno-19-1)getFeatureFlagPayload(options: GetFeatureFlagPayloadOptions) => Promise ` Get the payload of a feature flag. | Param | Type | | ----------- | ------------------------------------------------------------- | | **options** | [GetFeatureFlagPayloadOptions](#getfeatureflagpayloadoptions) | **Returns:** `Promise<[GetFeatureFlagPayloadResult](#getfeatureflagpayloadresult)>` **Since:** 7.1.0 --- ### group(...)[ΒΆ](#group "Permanent link") `[](#%5F%5Fcodelineno-20-1)group(options: GroupOptions) => Promise ` Associate the events for that user with a group. | Param | Type | | ----------- | ----------------------------- | | **options** | [GroupOptions](#groupoptions) | **Since:** 6.0.0 --- ### identify(...)[ΒΆ](#identify "Permanent link") `[](#%5F%5Fcodelineno-21-1)identify(options: IdentifyOptions) => Promise ` Identify the current user. | Param | Type | | ----------- | ----------------------------------- | | **options** | [IdentifyOptions](#identifyoptions) | **Since:** 6.0.0 --- ### isFeatureEnabled(...)[ΒΆ](#isfeatureenabled "Permanent link") `[](#%5F%5Fcodelineno-22-1)isFeatureEnabled(options: IsFeatureEnabledOptions) => Promise ` Check if a feature flag is enabled. | Param | Type | | ----------- | --------------------------------------------------- | | **options** | [IsFeatureEnabledOptions](#isfeatureenabledoptions) | **Returns:** `Promise<[IsFeatureEnabledResult](#isfeatureenabledresult)>` **Since:** 7.0.0 --- ### isOptOut()[ΒΆ](#isoptout "Permanent link") `[](#%5F%5Fcodelineno-23-1)isOptOut() => Promise ` Check if the user has opted out of capturing. **Returns:** `Promise<[IsOptOutResult](#isoptoutresult)>` **Since:** 8.1.0 --- ### optIn()[ΒΆ](#optin "Permanent link") `[](#%5F%5Fcodelineno-24-1)optIn() => Promise ` Opt in to event capturing. **Since:** 8.1.0 --- ### optOut()[ΒΆ](#optout "Permanent link") `[](#%5F%5Fcodelineno-25-1)optOut() => Promise ` 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 "Permanent link") `[](#%5F%5Fcodelineno-26-1)register(options: RegisterOptions) => Promise ` Register a new super property. This property will be sent with every event. | Param | Type | | ----------- | ----------------------------------- | | **options** | [RegisterOptions](#registeroptions) | **Since:** 6.0.0 --- ### reloadFeatureFlags()[ΒΆ](#reloadfeatureflags "Permanent link") `[](#%5F%5Fcodelineno-27-1)reloadFeatureFlags() => Promise ` Reload the feature flags. **Since:** 7.0.0 --- ### reset()[ΒΆ](#reset "Permanent link") `[](#%5F%5Fcodelineno-28-1)reset() => Promise ` Reset the current user's ID and anonymous ID. **Since:** 6.0.0 --- ### screen(...)[ΒΆ](#screen "Permanent link") `[](#%5F%5Fcodelineno-29-1)screen(options: ScreenOptions) => Promise ` Send a screen event. Only available on Android and iOS. | Param | Type | | ----------- | ------------------------------- | | **options** | [ScreenOptions](#screenoptions) | **Since:** 6.0.0 --- ### setup(...)[ΒΆ](#setup "Permanent link") `[](#%5F%5Fcodelineno-30-1)setup(options: SetupOptions) => Promise ` 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](#setupoptions) | **Since:** 6.0.0 --- ### startSessionRecording()[ΒΆ](#startsessionrecording "Permanent link") `[](#%5F%5Fcodelineno-31-1)startSessionRecording() => Promise ` Start session recording. **Since:** 7.3.0 --- ### stopSessionRecording()[ΒΆ](#stopsessionrecording "Permanent link") `[](#%5F%5Fcodelineno-32-1)stopSessionRecording() => Promise ` Stop session recording. **Since:** 7.3.0 --- ### unregister(...)[ΒΆ](#unregister "Permanent link") `[](#%5F%5Fcodelineno-33-1)unregister(options: UnregisterOptions) => Promise ` Remove a super property. | Param | Type | | ----------- | --------------------------------------- | | **options** | [UnregisterOptions](#unregisteroptions) | **Since:** 6.0.0 --- ### Interfaces[ΒΆ](#interfaces "Permanent link") #### AliasOptions[ΒΆ](#aliasoptions "Permanent link") | Prop | Type | Description | Since | | --------- | ------ | -------------------------------------------------- | ----- | | **alias** | string | The new distinct ID to assign to the current user. | 6.0.0 | #### CaptureOptions[ΒΆ](#captureoptions "Permanent link") | Prop | Type | Description | Since | | -------------- | ------------------- | -------------------------------------- | ----- | | **event** | string | The name of the event to capture. | 6.0.0 | | **properties** | Record | The properties to send with the event. | 6.0.0 | #### CaptureExceptionOptions[ΒΆ](#captureexceptionoptions "Permanent link") | Prop | Type | Description | Default | Since | | -------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------- | ----- | | **message** | string | The message of the exception. | | 8.5.0 | | **name** | string | The name of the exception. Used as the exception type for grouping. | 'Error' | 8.5.0 | | **stacktrace** | StackFrame\[\] | The stack trace of the exception. Can be generated from an Error using [stacktrace.js](https://www.stacktracejs.com/). | | 8.5.0 | | **properties** | Record | The properties to send with the exception. | | 8.5.0 | #### StackFrame[ΒΆ](#stackframe "Permanent link") | Prop | Type | Description | Since | | ---------------- | ------ | ---------------------------------- | ----- | | **functionName** | string | The name of the function. | 8.5.0 | | **fileName** | string | The name of the file. | 8.5.0 | | **lineNumber** | number | The line number within the file. | 8.5.0 | | **columnNumber** | number | The column number within the file. | 8.5.0 | #### GetDistinctIdResult[ΒΆ](#getdistinctidresult "Permanent link") | Prop | Type | Description | Since | | -------------- | ------ | ------------------------ | ----- | | **distinctId** | string | The current distinct ID. | 8.2.0 | #### GetFeatureFlagResult[ΒΆ](#getfeatureflagresult "Permanent link") | 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[ΒΆ](#getfeatureflagoptions "Permanent link") | Prop | Type | Description | Since | | ------- | ------ | ---------------------------- | ----- | | **key** | string | The key of the feature flag. | 7.0.0 | #### GetFeatureFlagPayloadResult[ΒΆ](#getfeatureflagpayloadresult "Permanent link") | Prop | Type | Description | Since | | --------- | --------------------- | -------------------------------------- | ----- | | **value** | [JsonType](#jsontype) | The value of the feature flag payload. | 7.1.0 | #### GetFeatureFlagPayloadOptions[ΒΆ](#getfeatureflagpayloadoptions "Permanent link") | Prop | Type | Description | Since | | ------- | ------ | ---------------------------- | ----- | | **key** | string | The key of the feature flag. | 7.1.0 | #### GroupOptions[ΒΆ](#groupoptions "Permanent link") | Prop | Type | Description | Since | | ------------------- | ------------------- | -------------------------------------------- | ----- | | **type** | string | The group type. | 6.0.0 | | **key** | string | The group key. | 6.0.0 | | **groupProperties** | Record | The properties to send with the group event. | 6.0.0 | #### IdentifyOptions[ΒΆ](#identifyoptions "Permanent link") | Prop | Type | Description | Since | | ------------------ | ------------------- | ----------------------------- | ----- | | **distinctId** | string | The distinct ID of the user. | 6.0.0 | | **userProperties** | Record | The person properties to set. | 6.0.0 | #### IsFeatureEnabledResult[ΒΆ](#isfeatureenabledresult "Permanent link") | 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[ΒΆ](#isfeatureenabledoptions "Permanent link") | Prop | Type | Description | Since | | ------- | ------ | ---------------------------- | ----- | | **key** | string | The key of the feature flag. | 7.0.0 | #### IsOptOutResult[ΒΆ](#isoptoutresult "Permanent link") | Prop | Type | Description | Since | | ------------ | ------- | -------------------------------------------- | ----- | | **optedOut** | boolean | Whether the user has opted out of capturing. | 8.1.0 | #### RegisterOptions[ΒΆ](#registeroptions "Permanent link") | 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[ΒΆ](#screenoptions "Permanent link") | Prop | Type | Description | Since | | --------------- | ------------------- | --------------------------------------------- | ----- | | **screenTitle** | string | The name of the screen. | 6.0.0 | | **properties** | Record | The properties to send with the screen event. | 6.0.0 | #### SetupOptions[ΒΆ](#setupoptions "Permanent link") | 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](#sessionreplayoptions) | Session replay configuration options. | | 7.3.0 | | **captureApplicationLifecycleEvents** | boolean | Whether to capture application lifecycle events. Only available on iOS and Android. | true | 8.3.0 | | **autoCaptureExceptions** | boolean | Whether to automatically capture unhandled exceptions. | false | 8.5.0 | #### SessionReplayOptions[ΒΆ](#sessionreplayoptions "Permanent link") | 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[ΒΆ](#unregisteroptions "Permanent link") | Prop | Type | Description | Since | | ------- | ------ | ----------------------------------------- | ----- | | **key** | string | The name of the super property to remove. | 6.0.0 | ### Type Aliases[ΒΆ](#type-aliases "Permanent link") #### JsonType[ΒΆ](#jsontype "Permanent link") `string | number | boolean | null | { [key: string]: [JsonType](#jsontype); } | JsonType[]` ## Advanced[ΒΆ](#advanced "Permanent link") ### Reverse Proxy[ΒΆ](#reverse-proxy "Permanent link") 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[ΒΆ](#faq "Permanent link") ### Do I have to call the `setup` method before using the plugin?[ΒΆ](#do-i-have-to-call-the-setup-method-before-using-the-plugin "Permanent link") 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](#configuration)). In that case, you must not call the `setup(...)` method. ### What is the difference between the `apiHost` and `host` options?[ΒΆ](#what-is-the-difference-between-the-apihost-and-host-options "Permanent link") 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?[ΒΆ](#how-do-i-use-the-plugin-with-a-reverse-proxy "Permanent link") 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](#reverse-proxy) section for more details. ### How do I enable session replay?[ΒΆ](#how-do-i-enable-session-replay "Permanent link") 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?[ΒΆ](#how-can-users-opt-out-of-tracking "Permanent link") 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?[ΒΆ](#can-i-use-this-plugin-with-ionic-react-vue-or-angular "Permanent link") 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[ΒΆ](#related-plugins "Permanent link") * [Analytics](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/): Unofficial Capacitor plugin for Firebase Analytics. * [Grafana Faro](https://capawesome.io/docs/sdks/capacitor/grafana-faro/): Unofficial Capacitor plugin for Grafana Faro to monitor your app. * [Formbricks](https://capawesome.io/docs/sdks/capacitor/formbricks/): Unofficial Capacitor plugin for Formbricks to run in-app surveys. ## Newsletter[ΒΆ](#newsletter "Permanent link") Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/). ## Changelog[ΒΆ](#changelog "Permanent link") See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/posthog/CHANGELOG.md). ## License[ΒΆ](#license "Permanent link") See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/posthog/LICENSE). --- 1. This project is not affiliated with, endorsed by, sponsored by, or approved by PostHog, Inc. or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text") July 8, 2026 Back to top ```json {"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/sdks/capacitor/posthog/#article", "headline": "Capacitor PostHog Plugin for Android, iOS & Web", "name": "Capacitor PostHog Plugin for Android, iOS & Web", "description": "Unofficial Capacitor plugin for PostHog SDK to track user interactions and events in your app with support for Android, iOS, and Web.", "inLanguage": "en", "url": "https://capawesome.io/docs/sdks/capacitor/posthog/", "mainEntityOfPage": "https://capawesome.io/docs/sdks/capacitor/posthog/", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "about": {"@id": "https://capawesome.io/docs/sdks/capacitor/posthog/#software"}}, {"@type": "SoftwareSourceCode", "@id": "https://capawesome.io/docs/sdks/capacitor/posthog/#software", "name": "Capacitor PostHog Plugin for Android, iOS & Web", "description": "Unofficial Capacitor plugin for PostHog SDK to track user interactions and events in your app with support for Android, iOS, and Web.", "url": "https://capawesome.io/docs/sdks/capacitor/posthog/", "programmingLanguage": "TypeScript", "runtimePlatform": "Capacitor", "codeRepository": "https://github.com/capawesome-team", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}}]} {"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "Do I have to call the setup method before using the plugin?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "What is the difference between the apiHost and host options?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "How do I use the plugin with a reverse proxy?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "How do I enable session replay?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "How can users opt out of tracking?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "Can I use this plugin with Ionic, React, Vue or Angular?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}], "url": "https://capawesome.io/docs/sdks/capacitor/posthog/"} ```