diff --git a/.changeset/tiny-birds-dream.md b/.changeset/tiny-birds-dream.md new file mode 100644 index 0000000000..4b309d4e5c --- /dev/null +++ b/.changeset/tiny-birds-dream.md @@ -0,0 +1,5 @@ +--- +'@posthog/core': patch +--- + +Add `@default` JSDoc tags to `PostHogCoreOptions` configuration properties for better IDE documentation and discoverability. diff --git a/.changeset/warm-foxes-wave.md b/.changeset/warm-foxes-wave.md new file mode 100644 index 0000000000..de09162e02 --- /dev/null +++ b/.changeset/warm-foxes-wave.md @@ -0,0 +1,19 @@ +--- +'posthog-react-native': minor +--- + +`captureAppLifecycleEvents` is now enabled by default. If you want to disable it, you can set `captureAppLifecycleEvents: false` in the PostHog options: + +```js +const posthog = new PostHog('', { + captureAppLifecycleEvents: false, +}) +``` + +Or when using the PostHogProvider: + +```jsx + + + +``` diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts index 192bdb4187..bc13390b9e 100644 --- a/packages/core/src/types.ts +++ b/packages/core/src/types.ts @@ -1,34 +1,71 @@ export type PostHogCoreOptions = { - /** PostHog API host, usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com' */ + /** + * PostHog API host, usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com' + * + * @default 'https://us.i.posthog.com' + */ host?: string - /** The number of events to queue before sending to PostHog (flushing) */ + /** + * The number of events to queue before sending to PostHog (flushing) + * + * @default 20 + */ flushAt?: number - /** The interval in milliseconds between periodic flushes */ + /** + * The interval in milliseconds between periodic flushes + * + * @default 10000 + */ flushInterval?: number - /** The maximum number of queued messages to be flushed as part of a single batch (must be higher than `flushAt`) */ + /** + * The maximum number of queued messages to be flushed as part of a single batch (must be higher than `flushAt`) + * + * @default 100 + */ maxBatchSize?: number - /** The maximum number of cached messages either in memory or on the local storage. - * Defaults to 1000, (must be higher than `flushAt`) + /** + * The maximum number of cached messages either in memory or on the local storage (must be higher than `flushAt`) + * + * @default 1000 */ maxQueueSize?: number - /** If set to true the SDK is essentially disabled (useful for local environments where you don't want to track anything) */ + /** + * If set to true the SDK is essentially disabled (useful for local environments where you don't want to track anything) + * + * @default false + */ disabled?: boolean - /** If set to false the SDK will not track until the `optIn` function is called. */ + /** + * If set to false the SDK will not track until the `optIn` function is called. + * + * @default true + */ defaultOptIn?: boolean - /** Whether to track that `getFeatureFlag` was called (used by Experiments) */ + /** + * Whether to track that `getFeatureFlag` was called (used by Experiments) + * + * @default true + */ sendFeatureFlagEvent?: boolean - /** Whether to load feature flags when initialized or not */ + /** + * Whether to load feature flags when initialized or not + * + * @default true + */ preloadFeatureFlags?: boolean /** * Whether to load remote config when initialized or not * Experimental support - * Default: false - Remote config is loaded by default + * + * @default false */ disableRemoteConfig?: boolean /** * Whether to load surveys when initialized or not * Experimental support - * Default: false - Surveys are loaded by default, but requires the `PostHogSurveyProvider` to be used + * Requires the `PostHogSurveyProvider` to be used + * + * @default false */ disableSurveys?: boolean /** Option to bootstrap the library with given distinctId and feature flags */ @@ -38,22 +75,59 @@ export type PostHogCoreOptions = { featureFlags?: Record featureFlagPayloads?: Record } - /** How many times we will retry HTTP requests. Defaults to 3. */ + /** + * How many times we will retry HTTP requests + * + * @default 3 + */ fetchRetryCount?: number - /** The delay between HTTP request retries, Defaults to 3 seconds. */ + /** + * The delay between HTTP request retries in milliseconds + * + * @default 3000 + */ fetchRetryDelay?: number - /** Timeout in milliseconds for any calls. Defaults to 10 seconds. */ + /** + * Timeout in milliseconds for any calls + * + * @default 10000 + */ requestTimeout?: number - /** Timeout in milliseconds for feature flag calls. Defaults to 10 seconds for stateful clients, and 3 seconds for stateless. */ + /** + * Timeout in milliseconds for feature flag calls + * + * @default 10000 for stateful clients, 3000 for stateless + */ featureFlagsRequestTimeoutMs?: number - /** Timeout in milliseconds for remote config calls. Defaults to 3 seconds. */ + /** + * Timeout in milliseconds for remote config calls + * + * @default 3000 + */ remoteConfigRequestTimeoutMs?: number - /** For Session Analysis how long before we expire a session (defaults to 30 mins) */ + /** + * For Session Analysis how long before we expire a session in seconds + * + * @default 1800 + */ sessionExpirationTimeSeconds?: number - /** Whether to disable GZIP compression */ + /** + * Whether to disable GZIP compression + * + * @default false + */ disableCompression?: boolean + /** + * Whether to disable GeoIP lookups + * + * @default false + */ disableGeoip?: boolean - /** Special flag to indicate ingested data is for a historical migration. */ + /** + * Special flag to indicate ingested data is for a historical migration + * + * @default false + */ historicalMigration?: boolean /** * Evaluation contexts for feature flags. diff --git a/packages/react-native/src/PostHogProvider.tsx b/packages/react-native/src/PostHogProvider.tsx index 849d5c18bc..f986872580 100644 --- a/packages/react-native/src/PostHogProvider.tsx +++ b/packages/react-native/src/PostHogProvider.tsx @@ -21,9 +21,23 @@ export interface PostHogProviderProps { apiKey?: string /** An existing PostHog client instance */ client?: PostHog - /** Autocapture configuration - can be a boolean or detailed options */ + /** + * Autocapture configuration - can be a boolean or detailed options. + * + * When not set, the default behavior is: + * - `captureScreens`: true + * - `captureTouches`: false + * - `captureAppLifecycleEvents`: true + * + * Set to `true` to enable all autocapture features (including touches). + * Set to `false` to disable all autocapture features. + */ autocapture?: boolean | PostHogAutocaptureOptions - /** Enable debug mode for additional logging */ + /** + * Enable debug mode for additional logging + * + * @default false + */ debug?: boolean /** Custom styles for the provider wrapper View */ style?: StyleProp @@ -132,9 +146,7 @@ export const PostHogProvider = ({ const parsedOptions = { ...options, captureAppLifecycleEvents: - options?.captureAppLifecycleEvents !== undefined - ? options.captureAppLifecycleEvents - : !captureNone && captureAll, + options?.captureAppLifecycleEvents !== undefined ? options.captureAppLifecycleEvents : !captureNone, } return new PostHog(apiKey ?? '', parsedOptions) diff --git a/packages/react-native/src/posthog-rn.ts b/packages/react-native/src/posthog-rn.ts index 094f6d71e8..ad34aa984d 100644 --- a/packages/react-native/src/posthog-rn.ts +++ b/packages/react-native/src/posthog-rn.ts @@ -33,30 +33,37 @@ import { ErrorTracking, ErrorTrackingOptions } from './error-tracking' export { PostHogPersistedProperty } export interface PostHogOptions extends PostHogCoreOptions { - /** Allows you to provide the storage type. By default 'file'. + /** + * Allows you to provide the storage type. * 'file' will try to load the best available storage, the provided 'customStorage', 'customAsyncStorage' or in-memory storage. + * + * @default 'file' */ persistence?: 'memory' | 'file' /** Allows you to provide your own implementation of the common information about your App or a function to modify the default App properties generated */ customAppProperties?: | PostHogCustomAppProperties | ((properties: PostHogCustomAppProperties) => PostHogCustomAppProperties) - /** Allows you to provide a custom asynchronous storage such as async-storage, expo-file-system or a synchronous storage such as mmkv. + /** + * Allows you to provide a custom asynchronous storage such as async-storage, expo-file-system or a synchronous storage such as mmkv. * If not provided, PostHog will attempt to use the best available storage via optional peer dependencies (async-storage, expo-file-system). * If `persistence` is set to 'memory', this option will be ignored. */ customStorage?: PostHogCustomStorage - /** Captures app lifecycle events such as Application Installed, Application Updated, Application Opened, Application Became Active and Application Backgrounded. - * By default is false. + /** + * Captures app lifecycle events such as Application Installed, Application Updated, Application Opened, Application Became Active and Application Backgrounded. * Application Installed and Application Updated events are not supported with persistence set to 'memory'. + * + * @default true */ captureAppLifecycleEvents?: boolean /** * Enable Recording of Session Replays for Android and iOS * Requires Record user sessions to be enabled in the PostHog Project Settings - * Defaults to false + * + * @default false */ enableSessionReplay?: boolean @@ -69,7 +76,8 @@ export interface PostHogOptions extends PostHogCoreOptions { * If enabled, the session id ($session_id) will be persisted across app restarts. * This is an option for back compatibility, so your current data isn't skewed with the new version of the SDK. * If this is false, the session id will be always reset on app restart. - * Defaults to false + * + * @default false */ enablePersistSessionIdAcrossRestart?: boolean @@ -266,7 +274,8 @@ export class PostHog extends PostHogCore { } } - if (options?.captureAppLifecycleEvents) { + // captureAppLifecycleEvents defaults to true; only skip if explicitly set to false + if (options?.captureAppLifecycleEvents !== false) { void this.captureAppLifecycleEvents() } diff --git a/packages/react-native/src/types.ts b/packages/react-native/src/types.ts index f1abad3243..812c0fbc30 100644 --- a/packages/react-native/src/types.ts +++ b/packages/react-native/src/types.ts @@ -13,12 +13,41 @@ export type PostHogNavigationRef = { } export type PostHogAutocaptureOptions = { - // Touches + /** + * Enable autocapture of touch events + * + * @default false + */ captureTouches?: boolean + /** + * Custom prop name used to label elements for autocapture + * + * @default 'ph-label' + */ customLabelProp?: string + /** + * Prop name used to prevent autocapture on an element and its children + * + * @default 'ph-no-capture' + */ noCaptureProp?: string + /** + * Maximum number of elements to capture in the component tree hierarchy + * + * @default 20 + */ maxElementsCaptured?: number + /** + * List of element labels to ignore during autocapture + * + * @default [] + */ ignoreLabels?: string[] + /** + * List of prop names to capture from elements + * + * @default ['style', 'testID', 'accessibilityLabel', 'ph-label', 'children'] + */ propsToCapture?: string[] /** @@ -95,12 +124,14 @@ export interface PostHogCustomAppProperties { export type PostHogSessionReplayConfig = { /** * Enable masking of all text and text input fields - * Default: true + * + * @default true */ maskAllTextInputs?: boolean /** * Enable masking of all images to a placeholder - * Default: true + * + * @default true */ maskAllImages?: boolean /** @@ -108,19 +139,22 @@ export type PostHogSessionReplayConfig = { * These may include UIImagePickerController, PHPickerViewController and CNContactPickerViewController * iOS only * Experimental support - * Default: true + * + * @default true */ maskAllSandboxedViews?: boolean /** * Enable capturing of logs as console events - * Default: true + * + * @default true */ captureLog?: boolean /** * Deboucer delay used to reduce the number of snapshots captured and reduce performance impact * This is used for capturing the view as a screenshot * The lower the number more snapshots will be captured but higher the performance impact - * Defaults to 1s on iOS + * + * @default 1000 * @deprecated please use throttleDelayMs instead */ iOSdebouncerDelayMs?: number @@ -128,8 +162,9 @@ export type PostHogSessionReplayConfig = { * Deboucer delay used to reduce the number of snapshots captured and reduce performance impact * This is used for capturing the view as a screenshot * The lower the number more snapshots will be captured but higher the performance impact - * Defaults to 1000ms (1s) * Ps: it was 500ms (0.5s) by default until version 3.3.7 + * + * @default 1000 * @deprecated please use throttleDelayMs instead */ androidDebouncerDelayMs?: number @@ -141,13 +176,14 @@ export type PostHogSessionReplayConfig = { * This value has precedence over iOSdebouncerDelayMs and androidDebouncerDelayMs * If this is not set, we will take the max number between iOSdebouncerDelayMs and androidDebouncerDelayMs for back compatibility * - * Defaults to 1000ms = 1s + * @default 1000 */ throttleDelayMs?: number /** * Enable capturing network telemetry * iOS only - * Default: true + * + * @default true */ captureNetworkTelemetry?: boolean /** diff --git a/packages/react-native/test/posthog.spec.ts b/packages/react-native/test/posthog.spec.ts index cd89f506bf..f6aca75f0d 100644 --- a/packages/react-native/test/posthog.spec.ts +++ b/packages/react-native/test/posthog.spec.ts @@ -480,13 +480,14 @@ describe('PostHog React Native', () => { it('do not rotate session id on restart', async () => { const sessionId = '0192244d-a627-7ae2-b22a-ccd594bed71d' rnStorage.setItem(PostHogPersistedProperty.SessionId, sessionId) - const now = JSON.stringify(Date.now()) + const now = Date.now() rnStorage.setItem(PostHogPersistedProperty.SessionLastTimestamp, now) rnStorage.setItem(PostHogPersistedProperty.SessionStartTimestamp, now) posthog = new PostHog('1', { customStorage: storage, enablePersistSessionIdAcrossRestart: true, + captureAppLifecycleEvents: false, }) expect(posthog.getPersistedProperty(PostHogPersistedProperty.SessionId)).toEqual(sessionId) @@ -497,13 +498,14 @@ describe('PostHog React Native', () => { it('rotate session id on restart if persist session id across restart is disabled', async () => { const sessionId = '0192244d-a627-7ae2-b22a-ccd594bed71d' rnStorage.setItem(PostHogPersistedProperty.SessionId, sessionId) - const now = JSON.stringify(Date.now()) + const now = Date.now() rnStorage.setItem(PostHogPersistedProperty.SessionLastTimestamp, now) rnStorage.setItem(PostHogPersistedProperty.SessionStartTimestamp, now) posthog = new PostHog('1', { customStorage: storage, enablePersistSessionIdAcrossRestart: false, + captureAppLifecycleEvents: false, }) expect(posthog.getPersistedProperty(PostHogPersistedProperty.SessionId)).toEqual(undefined) @@ -1109,6 +1111,7 @@ describe('Feature flag error tracking', () => { fetchRetryCount: 0, preloadFeatureFlags: false, sendFeatureFlagEvent: true, + captureAppLifecycleEvents: false, }) })