posthog-cap v1.1.0

@capawesome/capacitor-posthog

Unofficial Capacitor plugin for PostHog.^1

Installation

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

Android

Variables

This plugin will use the following project variables (defined in your app's variables.gradle file):

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

Configuration

No configuration required for this plugin.

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',
    host: 'https://eu.i.posthog.com',
    sessionRecording: true,
    sessionRecordingConfig: {
      maskAllTextInputs: true,
      maskAllImages: true,
      maskAllSandboxedViews: true,
      captureNetworkTelemetry: true,
      screenshotMode: false,
      debouncerDelay: 1.0
    }
  });
};

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

API

• alias(...)
• capture(...)
• flush()
• getFeatureFlag(...)
• getSessionId()
• group(...)
• identify(...)
• isFeatureEnabled(...)
• register(...)
• reloadFeatureFlags()
• reset()
• screen(...)
• setup(...)
• 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

flush()

flush() => Promise<void>

Flush all events in the queue.

Only available on Android and iOS.

Since: 6.0.0

getFeatureFlag(...)

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

Get the value of a feature flag.

Returns: Promise<GetFeatureFlagResult>

Since: 7.0.0

getSessionId()

getSessionId() => Promise<GetSessionIdResult>

Get the current session ID.

Only available on Android and iOS.

Returns: Promise<GetSessionIdResult>

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

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

setup(...)

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

Setup the PostHog SDK with the provided options.

Attention: This method should be called before any other method.

Since: 6.0.0

unregister(...)

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

Remove a super property.

Since: 6.0.0

Interfaces

AliasOptions

CaptureOptions

GetFeatureFlagResult

GetFeatureFlagOptions

GetSessionIdResult

GroupOptions

IdentifyOptions

IsFeatureEnabledResult

IsFeatureEnabledOptions

RegisterOptions

ScreenOptions

SetupOptions

SessionRecordingConfig

UnregisterOptions

Type Aliases

Record

Construct a type with a set of properties K of type T

{

}

Changelog

See CHANGELOG.md.

License

See LICENSE.

Session Recording

This plugin supports PostHog's Session Recording feature on iOS. Session Recording allows you to capture and replay user sessions to understand how users interact with your app.

Enabling Session Recording

To enable Session Recording, set the sessionRecording option to true when calling setup:

await Posthog.setup({
  apiKey: 'YOUR_API_KEY',
  host: 'https://eu.i.posthog.com',
  sessionRecording: true
});

Configuring Session Recording

You can customize the behavior of Session Recording by providing a sessionRecordingConfig object:

await Posthog.setup({
  apiKey: 'YOUR_API_KEY',
  host: 'https://eu.i.posthog.com',
  sessionRecording: true,
  sessionRecordingConfig: {
    // Mask all text inputs (default: true)
    maskAllTextInputs: true,
    // Mask all images (default: true)
    maskAllImages: true,
    // Mask all sandboxed system views (default: true)
    maskAllSandboxedViews: true,
    // Capture network telemetry (default: true)
    captureNetworkTelemetry: true,
    // Use screenshot mode instead of wireframe mode (default: false)
    // Note: Screenshots may contain sensitive information
    screenshotMode: false,
    // Debouncer delay in seconds (default: 1.0)
    debouncerDelay: 1.0
  }
});

Privacy Considerations

Session Recording captures user interactions with your app, which may include sensitive information. Consider the following privacy measures:

• Use the masking options to hide sensitive content
• Inform users about session recording in your privacy policy
• Be cautious when enabling screenshot mode, as it captures actual screenshots instead of wireframes

Platform Support

Session Recording is currently only supported on iOS. When used on other platforms, the session recording options will be ignored.

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