@capawesome/capacitor-posthog
v8.1.0TypeScript
Unofficial Capacitor plugin for PostHog SDK.
0/weekUpdated 1 months agoMITUnpacked: 171.9 KB
Published by Robin Genz
npm install @capawesome/capacitor-posthog@capawesome/capacitor-posthog
Unofficial Capacitor plugin for PostHog.[^1]
Compatibility
| Plugin Version | Capacitor Version | Status |
| -------------- | ----------------- | -------------- |
| 8.x.x | >=8.x.x | Active support |
| 7.x.x | 7.x.x | Deprecated |
Installation
``bash`
npm install @capawesome/capacitor-posthog posthog-js
npx cap sync
$3
#### 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 |
| host | string | The host of your PostHog instance. | 'https://us.i.posthog.com' | 7.1.0 |
| enableSessionReplay | boolean | Whether to enable session recording automatically. | false | 7.3.0 |
| sessionReplayConfig | SessionReplayOptions | Session recording configuration options. | | 7.3.0 |
$3
In capacitor.config.json:
`json`
{
"plugins": {
"Posthog": {
"apiKey": 'phc_g8wMenebiIQ1pYd5v9Vy7oakn6MczVKIsNG5ZHCspdy',
"host": 'https://eu.i.posthog.com',
"enableSessionReplay": undefined,
"sessionReplayConfig": undefined
}
}
}
In capacitor.config.ts:
`ts
///
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
plugins: {
Posthog: {
apiKey: 'phc_g8wMenebiIQ1pYd5v9Vy7oakn6MczVKIsNG5ZHCspdy',
host: 'https://eu.i.posthog.com',
enableSessionReplay: undefined,
sessionReplayConfig: undefined,
},
},
};
export default config;
`
Demo
A working example can be found here: robingenz/capacitor-plugin-demo
Usage
`typescript
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',
});
};
const unregister = async () => {
await Posthog.unregister({
key: 'super-property',
});
};
`
API
* alias(...)
* capture(...)
* flush()
* getFeatureFlag(...)
* getFeatureFlagPayload(...)
* group(...)
* identify(...)
* isFeatureEnabled(...)
* isOptOut()
* optIn()
* optOut()
* register(...)
* reloadFeatureFlags()
* reset()
* screen(...)
* setup(...)
* startSessionRecording()
* stopSessionRecording()
* unregister(...)
* Interfaces
* Type Aliases
$3
`typescript`
alias(options: AliasOptions) => Promise
Assign another distinct ID to the current user.
| Param | Type |
| ------------- | ----------------------------------------------------- |
| options | AliasOptions |
Since: 6.0.0
--------------------
$3
`typescript`
capture(options: CaptureOptions) => Promise
Capture an event.
| Param | Type |
| ------------- | --------------------------------------------------------- |
| options | CaptureOptions |
Since: 6.0.0
--------------------
$3
`typescript`
flush() => Promise
Flush all events in the queue.
Only available on Android and iOS.
Since: 6.0.0
--------------------
$3
`typescript`
getFeatureFlag(options: GetFeatureFlagOptions) => Promise
Get the value of a feature flag.
| Param | Type |
| ------------- | ----------------------------------------------------------------------- |
| options | GetFeatureFlagOptions |
Returns: Promise<GetFeatureFlagResult>
Since: 7.0.0
--------------------
$3
`typescript`
getFeatureFlagPayload(options: GetFeatureFlagPayloadOptions) => Promise
Get the payload of a feature flag.
| Param | Type |
| ------------- | ------------------------------------------------------------------------------------- |
| options | GetFeatureFlagPayloadOptions |
Returns: Promise<GetFeatureFlagPayloadResult>
Since: 7.1.0
--------------------
$3
`typescript`
group(options: GroupOptions) => Promise
Associate the events for that user with a group.
| Param | Type |
| ------------- | ----------------------------------------------------- |
| options | GroupOptions |
Since: 6.0.0
--------------------
$3
`typescript`
identify(options: IdentifyOptions) => Promise
Identify the current user.
| Param | Type |
| ------------- | ----------------------------------------------------------- |
| options | IdentifyOptions |
Since: 6.0.0
--------------------
$3
`typescript`
isFeatureEnabled(options: IsFeatureEnabledOptions) => Promise
Check if a feature flag is enabled.
| Param | Type |
| ------------- | --------------------------------------------------------------------------- |
| options | IsFeatureEnabledOptions |
Returns: Promise<IsFeatureEnabledResult>
Since: 7.0.0
--------------------
$3
`typescript`
isOptOut() => Promise
Check if the user has opted out of capturing.
Returns: Promise<IsOptOutResult>
Since: 8.1.0
--------------------
$3
`typescript`
optIn() => Promise
Opt in to event capturing.
Since: 8.1.0
--------------------
$3
`typescript`
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
--------------------
$3
`typescript`
register(options: RegisterOptions) => Promise
Register a new super property. This property will be sent with every event.
| Param | Type |
| ------------- | ----------------------------------------------------------- |
| options | RegisterOptions |
Since: 6.0.0
--------------------
$3
`typescript`
reloadFeatureFlags() => Promise
Reload the feature flags.
Since: 7.0.0
--------------------
$3
`typescript`
reset() => Promise
Reset the current user's ID and anonymous ID.
Since: 6.0.0
--------------------
$3
`typescript`
screen(options: ScreenOptions) => Promise
Send a screen event.
Only available on Android and iOS.
| Param | Type |
| ------------- | ------------------------------------------------------- |
| options | ScreenOptions |
Since: 6.0.0
--------------------
$3
`typescript`
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 |
Since: 6.0.0
--------------------
$3
`typescript`
startSessionRecording() => Promise
Start session recording.
Since: 7.3.0
--------------------
$3
`typescript`
stopSessionRecording() => Promise
Stop session recording.
Since: 7.3.0
--------------------
$3
`typescript`
unregister(options: UnregisterOptions) => Promise
Remove a super property.
| Param | Type |
| ------------- | --------------------------------------------------------------- |
| options | UnregisterOptions |
Since: 6.0.0
--------------------
$3
#### 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 |
#### 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 |
| 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
| | hostboolean | Whether to enable session recording automatically. | false | 7.3.0 |
| | optOutstring | The host of your PostHog instance. | 'https://us.i.posthog.com' | 6.0.0 |
| | optIn()boolean | Whether to opt out of capturing by default. User must call to enable capturing. | sessionReplayConfigfalse | 8.1.0 |
| | 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 |
$3
#### JsonType
string | number | boolean | null | { [key: string]: JsonType; } | JsonType[]
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.