PostHog iOS SDK
Getting started
The iOS SDK runs in iOS and other Apple platform apps.
To send your first event, add the package, then call setup once at app startup with your project token and host from your project settings.
After setup, PostHog captures app lifecycle events, such as Application Opened, by itself. Use capture for your own events.
Install
Add the package with Swift Package Manager, https://github.com/PostHog/posthog-ios.git, or with CocoaPods:
Initialize
Call setup once, as early as possible in app startup.
Capture an event
Call identify to link events to a user:
Shut down
Events are sent in batches. Call flush() to send queued events now, or close() to shut the SDK down.
Setup
PostHogSDK.setup(_:)
Initializes this SDK instance with the provided configuration.
Parameters
config: The configuration to install.
Discussion
Call this once, as early as possible in app startup. Calls made before setup completes are ignored. Calling setup again on the same instance logs a warning and has no effect.
PostHogSDK.with(_:)
Creates and sets up an additional SDK instance.
Parameters
config: Configuration for the new instance.
Return Value
A configured PostHogSDK instance.
Capture
PostHogSDK.capture(_:)
Captures a custom event for the current user.
Parameters
event: Event name to capture.
PostHogSDK.capture(_:distinctId:properties:userProperties:userPropertiesSetOnce:groups:)
Captures a custom event for an explicit distinct ID.
Parameters
event: Event name to capture.distinctId: Optional distinct ID override. Defaults to the current SDK distinct ID.properties: Event properties attached only to this event.userProperties: Person properties to set. Existing values are overwritten.userPropertiesSetOnce: Person properties to set only if they do not already exist.groups: Group type/key pairs to attach to this event.
PostHogSDK.capture(_:distinctId:properties:userProperties:userPropertiesSetOnce:groups:timestamp:)
Captures a custom event for an explicit distinct ID and timestamp.
Parameters
event: Event name to capture.distinctId: Optional distinct ID override. Defaults to the current SDK distinct ID.properties: Event properties attached only to this event.userProperties: Person properties to set. Existing values are overwritten.userPropertiesSetOnce: Person properties to set only if they do not already exist.groups: Group type/key pairs to attach to this event.timestamp: Optional event timestamp. Defaults to the current time. The absolute instant is serialized in UTC, regardless of the calendar or time zone used to create it.
PostHogSDK.capture(_:properties:)
Captures a custom event with event properties.
Parameters
event: Event name to capture.properties: Event properties attached only to this event.
PostHogSDK.capture(_:properties:userProperties:)
Captures a custom event and updates person properties.
Parameters
event: Event name to capture.properties: Event properties attached only to this event.userProperties: Person properties to set. Existing values are overwritten.
PostHogSDK.capture(_:properties:userProperties:userPropertiesSetOnce:)
Captures a custom event and updates person properties.
Parameters
event: Event name to capture.properties: Event properties attached only to this event.userProperties: Person properties to set. Existing values are overwritten.userPropertiesSetOnce: Person properties to set only if they do not already exist.
PostHogSDK.capture(_:properties:userProperties:userPropertiesSetOnce:groups:)
Captures a custom event with group context.
Parameters
event: Event name to capture.properties: Event properties attached only to this event.userProperties: Person properties to set. Existing values are overwritten.userPropertiesSetOnce: Person properties to set only if they do not already exist.groups: Group type/key pairs to attach to this event.
Identify
PostHogSDK.identify(_:)
Identifies the current user with a stable distinct ID.
Parameters
distinctId: Stable user identifier from your application.
Discussion
By default, the first successful identify call links prior anonymous events to the provided ID. If PostHogConfig.reuseAnonymousId is true, prior anonymous events are not linked. Empty IDs and configurations with personProfiles == .never are ignored. While opted out, the distinct ID and feature flags still update, but no event is captured.
PostHogSDK.identify(_:userProperties:)
Identifies the current user and sets person properties.
Parameters
distinctId: Stable user identifier from your application.userProperties: Properties to set on the person profile. Existing values are overwritten.
PostHogSDK.identify(_:userProperties:userPropertiesSetOnce:)
Identifies the current user and sets person properties.
Parameters
distinctId: Stable user identifier from your application.userProperties: Properties to set on the person profile. Existing values are overwritten.userPropertiesSetOnce: Properties to set only if they do not already exist.
Logs
PostHogSDK.logger
Logger facade exposing trace/debug/info/warn/error/fatal(_:attributes:). nil before setup(_:) is called.
PostHogSDK.captureLog(_:)
Capture a structured log record at .info severity.
Parameters
body: The log message. Required and non-empty.
Discussion
Log records ship to PostHog via a separate /i/v1/logs endpoint and are persisted to disk so they survive app restarts. The call performs a synchronous disk write on the calling thread, then the network send happens asynchronously — same contract as capture(_:) for events. Avoid calling from the main thread on hot paths. Records run through config.logs.beforeSend and the per-window rate cap before enqueueing — both can drop a record silently. An empty or whitespace-only body is always dropped.
PostHogSDK.captureLog(_:level:)
Capture a structured log record at the given severity.
Parameters
body: The log message. Required and non-empty.level: Severity. Use.trace/.debugfor diagnostic detail,.infofor regular events,.warn/.error/.fatalfor problems.
PostHogSDK.captureLog(_:level:attributes:)
Capture a structured log record with caller-supplied attributes.
Parameters
body: The log message. Required and non-empty.level: Severity.attributes: Per-record attributes (request id, duration, etc.). Values must be JSON-serializable; non-serializable entries are dropped.
PostHogSDK.captureLog(_:level:attributes:traceId:spanId:traceFlags:)
Swift-native variant of captureLog with default values for every argument except body. Most call sites can write captureLog("...") or captureLog("...", level: .warn, attributes: [...]).
Parameters
body: The log message. Required and non-empty.level: Severity. Defaults to.info.attributes: Per-record attributes. Values must be JSON-serializable.traceId: Optional 32-character lowercase hex W3C trace ID.spanId: Optional 16-character lowercase hex W3C span ID.traceFlags: Optional W3C trace flags bitfield.
Capture a structured log record with W3C trace context. Intended for callers correlating logs with distributed traces; most apps should use the simpler overload.
Parameters
body: The log message. Required and non-empty.level: Severity.attributes: Per-record attributes. Same rules as the simpler overload.traceId: 32-character lowercase hex W3C trace id.spanId: 16-character lowercase hex W3C span id.traceFlags: W3C trace flags bitfield (bit 0 is thesampledflag).nilomits the field on the wire;0emits an explicit zero.
Alias
PostHogSDK.alias(_:)
Assigns an additional distinct ID to the current user.
Parameters
alias: The additional distinct ID to associate with the current user.
Discussion
Use alias when a user should be connected to another identifier that was previously used to track them. This sends a $create_alias event.
Capture exception
PostHogSDK.captureException(_:)
Capture an NSException without additional properties
Parameters
exception: The NSException to capture
Discussion
Convenience overload for Objective-C callers so properties: doesn’t need to be passed as nil.
Capture a Swift Error or NSError without additional properties
Parameters
error: The error to capture (can be any Error or NSError)
Discussion
Convenience overload for Objective-C callers so properties: doesn’t need to be passed as nil.
PostHogSDK.captureException(_:properties:)
Capture an NSException
Parameters
exception: The NSException to captureproperties: Optional additional properties to attach to the event
Discussion
Captures an NSException as a $exception event with full stack trace. This is useful for Objective-C code that uses NSException.
Example:
Capture a Swift Error or NSError
Parameters
error: The error to capture (can be any Error or NSError)properties: Optional additional properties to attach to the event
Discussion
Captures an error as a $exception event with full stack trace and error chain information. The error will be marked as handled by default.
Example:
Debug
PostHogSDK.debug(_:)
Enables or disables SDK debug logging at runtime.
Parameters
enabled: Passtrueto enable verbose logs orfalseto disable them.
Exception steps
PostHogSDK.addExceptionStep(_:)
Record an exception step without additional properties.
Parameters
message: A short, non-empty description of what happened.
Discussion
Convenience overload for Objective-C callers so properties: doesn’t need to be passed as nil.
PostHogSDK.addExceptionStep(_:properties:)
Record an exception step (breadcrumb-style context record).
Parameters
message: A short, non-empty description of what happened. Empty messages are ignored.properties: Optional additional context to attach to the step.
Discussion
Steps accumulate in a session-scoped buffer and are attached to every captured $exception as $exception_steps, giving the error tracking UI a timeline of recent activity before each error. The buffer is not cleared by a capture — it rotates only by byte-budget eviction and is cleared on a clean launch or close(). On a fatal crash the buffered steps are persisted with the crash context and attached to the crash $exception reported on the next launch.
Reserved keys $message and $timestamp are stripped from properties — the SDK sets the canonical values. The $timestamp is captured at call time so the timeline stays accurate. This method never throws and never blocks; a failed step is silently skipped.
Example:
Flush
PostHogSDK.flush()
Trigger an immediate flush of every queue — events, session-replay snapshots, and structured logs.
Get anonymous ID
PostHogSDK.getAnonymousId()
Returns the anonymous ID generated for this install.
Return Value
The anonymous ID, or an empty string when the SDK is not set up.
Get distinct ID
PostHogSDK.getDistinctId()
Returns the current PostHog distinct ID.
Return Value
The current distinct ID, or an empty string when the SDK is not set up.
Discussion
Before identify(_:), this is the anonymous ID. After identify, this is the identified user’s ID.
Get feature flag
PostHogSDK.getFeatureFlag(_:)
Returns a feature flag value.
Parameters
key: The feature flag key.
Return Value
Bool, String, or nil if the flag is unavailable.
Discussion
Boolean flags return Bool. Multivariate flags return their variant String.
PostHogSDK.getFeatureFlag(_:sendFeatureFlagEvent:)
Returns a feature flag value and optionally captures a usage event.
Parameters
key: The feature flag key.sendFeatureFlagEvent: Whether to capture$feature_flag_calledfor this lookup.
Return Value
Bool, String, or nil if the flag is unavailable.
Get feature flag payload
PostHogSDK.getFeatureFlagPayload(_:)
Deprecated: Use getFeatureFlagResult(_:) instead which properly tracks feature flag usage
Returns the payload for a feature flag.
Parameters
key: The feature flag key.
Return Value
The flag payload, or nil if the flag or payload is unavailable.
Discussion
Warning: This method does not send the
$feature_flag_calledevent. UsegetFeatureFlagResult(_:)instead for proper analytics tracking.
Get feature flag result
PostHogSDK.getFeatureFlagResult(_:)
Returns the feature flag result containing the flag value, variant, and payload.
Parameters
key: The feature flag key
Return Value
A PostHogFeatureFlagResult containing the flag’s enabled state, variant (if any), and payload (if any), or nil if the flag doesn’t exist.
Discussion
This is the recommended method for retrieving feature flags as it provides all flag information in a single call and properly tracks flag usage.
PostHogSDK.getFeatureFlagResult(_:sendFeatureFlagEvent:)
Returns the feature flag result and optionally captures a usage event.
Parameters
key: The feature flag key.sendFeatureFlagEvent: Whether to capture$feature_flag_calledfor this lookup.
Return Value
A result containing enabled state, variant, and payload, or nil if unavailable.
Get feature flags
PostHogSDK.getAllFeatureFlags()
Returns all currently loaded feature flags as structured results.
Return Value
An array of PostHogFeatureFlagResult, or nil if no flags are loaded.
Discussion
Each PostHogFeatureFlagResult carries the flag’s key, enabled state, variant (for multivariate flags), and decoded payload. Flags become available after they finish loading from the server; before the first load (or when the SDK is disabled) this returns nil. Reading does not capture $feature_flag_called events.
Get session ID
PostHogSDK.getSessionId()
Returns the current session ID without rotating or creating a session.
Return Value
The current session ID, or nil if no session is active or the SDK is not set up.
Group
PostHogSDK.group(type:key:)
Associates subsequent events with a group.
Parameters
type: Group type, such as"company"or"organization".key: Group key from your application.
PostHogSDK.group(type:key:groupProperties:)
Associates subsequent events with a group and optionally updates group properties.
Parameters
type: Group type, such as"company"or"organization".key: Group key from your application.groupProperties: Optional properties to set on the group profile.
Discussion
This sends a $groupidentify event and reloads feature flags if the group value changed. The call is ignored if type or key is empty.
Is feature enabled
PostHogSDK.isFeatureEnabled(_:)
Returns whether a feature flag is enabled.
Parameters
key: The feature flag key.
Return Value
true when the flag is enabled, otherwise false.
Discussion
Multivariate flags are considered enabled when a variant string is returned.
PostHogSDK.isFeatureEnabled(_:sendFeatureFlagEvent:)
Returns whether a feature flag is enabled and optionally captures a usage event.
Parameters
key: The feature flag key.sendFeatureFlagEvent: Whether to capture$feature_flag_calledfor this lookup.
Return Value
true when the flag is enabled, otherwise false.
Is opt out
PostHogSDK.isOptOut()
Returns whether this SDK instance is currently opted out.
Return Value
true when opted out or when the SDK is not set up.
Is session replay active
PostHogSDK.isSessionReplayActive()
Returns whether session replay is currently recording.
Return Value
true only when replay is active, a session ID exists, and remote config allows recording.
On feature flags
PostHogSDK.onFeatureFlags(_:)
Registers a callback that’s invoked whenever feature flags are loaded or updated.
Parameters
callback: Receives the enabled flags, their values, and whether loading failed.
Return Value
A subscription. Call unsubscribe() on it to stop receiving updates.
Discussion
The callback runs on the main thread. It’s invoked after the SDK loads flags at startup (including from bootstrap values), after reloadFeatureFlags(), and after calls that reload flags such as identify(), group() or reset(). If flags have already loaded when you register, it’s also invoked with the current values shortly afterwards.
You can register before setup(). Treat each invocation as “flags may have changed”, not as an exactly-once event.
PostHogSDK.didReceiveFeatureFlags
Posted after a feature flag reload finishes and cached flags are updated.
Discussion
The notification object is nil.
Opt in
PostHogSDK.optIn()
Opts the current user back into data capture.
Discussion
This persists the opt-in state, unless opt-out persistence is disabled, and installs integrations that were disabled while opted out. Session replay restarts in a new session if the app wanted it on at optOut(): config.sessionReplay is enabled or startSessionRecording() was called, and stopSessionRecording() wasn’t called after. Sampling, linked flags and event triggers apply again to the new session.
PostHogSDK.optOut()
Opts the current user out of data capture.
Discussion
This persists the opt-out state, unless opt-out persistence is disabled, stops integrations, and causes future capture calls to be ignored. It also unregisters this device’s push subscription, so Workflows stop sending it notifications. The device token itself is kept, so optIn() resubscribes this device on its own — on the next flush() or launch at the latest — with no further call from the app.
Register
PostHogSDK.register(_:)
Registers super properties that are included with every subsequent event.
Parameters
properties: Event properties to persist and attach to future captures.
Discussion
New values overwrite existing values for the same keys and persist across app restarts until removed with unregister(_:) or cleared by reset().
Reload feature flags
PostHogSDK.reloadFeatureFlags()
Reloads feature flags for the current user and group context.
PostHogSDK.reloadFeatureFlags(_:)
Reloads feature flags and invokes a callback when finished.
Parameters
callback: Invoked when the reload finishes, or immediately if the reload is skipped (SDK disabled/opted-out, or no remote config available).
Reset
PostHogSDK.reset()
Resets local identity, super properties, feature flag cache, and session state.
Discussion
Call this when a user logs out. The next captured event will use a new anonymous identity unless PostHogConfig.reuseAnonymousId is enabled. If a push token is registered, it is unregistered for the logged-out identity and re-registered under the new anonymous id.
Reset group properties for flags
PostHogSDK.resetGroupPropertiesForFlags()
Clears all group properties for feature flag evaluation.
Example Usage
PostHogSDK.resetGroupPropertiesForFlags(_:)
Clears group properties for feature flag evaluation for a specific group type.
Parameters
groupType: The group type to clear properties for
Example Usage
PostHogSDK.resetGroupPropertiesForFlags(_:reloadFeatureFlags:)
Clears group properties for feature flag evaluation for a specific group type.
Parameters
groupType: The group type to clear properties forreloadFeatureFlags: Whether to automatically reload feature flags after clearing properties for this group type.
Example Usage
PostHogSDK.resetGroupPropertiesForFlags(reloadFeatureFlags:)
Clears all group properties for feature flag evaluation.
Parameters
reloadFeatureFlags: Whether to automatically reload feature flags after clearing all group properties.
Example Usage
Reset person properties for flags
PostHogSDK.resetPersonPropertiesForFlags()
Resets all person properties that were set for feature flag evaluation.
Discussion
After calling this method, feature flag evaluation will only use server-side person properties and will not include any locally overridden properties.
Example Usage
PostHogSDK.resetPersonPropertiesForFlags(reloadFeatureFlags:)
Resets all person properties that were set for feature flag evaluation.
Parameters
reloadFeatureFlags: Whether to automatically reload feature flags after resetting properties
Discussion
After calling this method, feature flag evaluation will only use server-side person properties and will not include any locally overridden properties.
Example Usage
Screen
PostHogSDK.screen(_:)
Records a screen view by capturing a $screen event.
Parameters
screenTitle: The screen name to record.
PostHogSDK.screen(_:properties:)
Records a screen view by capturing a $screen event with screenTitle.
Parameters
screenTitle: The screen name to record. It takes precedence over a$screen_namekey inproperties.properties: Additional properties to attach to this$screenevent.
Discussion
The title is also cached and automatically attached as $screen_name to every subsequent event (until reset() or close() clears it).
To override the auto-attached value on another event, pass $screen_name in that event’s properties dictionary.
Set group properties for flags
PostHogSDK.setGroupPropertiesForFlags(_:properties:)
Sets properties for a specific group type to include when evaluating feature flags. These properties supplement the standard group information sent to PostHog for flag evaluation, providing additional context that can be used in flag targeting conditions.
Parameters
groupType: The group type identifier (e.g., “organization”, “team”)properties: Dictionary of properties to set for this group type
Example Usage
Note: This method automatically reloads feature flags to apply the new properties.
See Also:
setGroupPropertiesForFlags(_:properties:reloadFeatureFlags:)to control flag reloading behavior
PostHogSDK.setGroupPropertiesForFlags(_:properties:reloadFeatureFlags:)
Sets properties for a specific group type to include when evaluating feature flags. These properties supplement the standard group information sent to PostHog for flag evaluation, providing additional context that can be used in flag targeting conditions.
Parameters
groupType: The group type identifier (e.g., “organization”, “team”)properties: Dictionary of properties to set for this group typereloadFeatureFlags: Whether to automatically reload feature flags after setting properties
Example Usage
Set person properties
PostHogSDK.setPersonProperties(userPropertiesToSet:)
Sets properties on the person profile associated with the current distinct_id.
Parameters
userPropertiesToSet: Properties to store about the user. These will overwrite existing values.
Discussion
Updates user properties that are stored with the person profile in PostHog. If personProfiles is set to never, this call will be ignored.
This method sends a $set event to PostHog.
PostHogSDK.setPersonProperties(userPropertiesToSet:userPropertiesToSetOnce:)
Sets properties on the person profile associated with the current distinct_id.
Parameters
userPropertiesToSet: Properties to store about the user. These will overwrite existing values.userPropertiesToSetOnce: Properties to store about the user only if not previously set. Note: For feature flag evaluations, if the same key is present in both parameters, the value from userPropertiesToSet will take precedence.
Discussion
Updates user properties that are stored with the person profile in PostHog. If personProfiles is set to never, this call will be ignored.
This method sends a $set event to PostHog.
Set person properties for flags
PostHogSDK.setPersonPropertiesForFlags(_:)
Sets person properties that will be included in feature flag evaluation requests.
Parameters
properties: Dictionary of person properties to include in flag evaluation
Discussion
This method allows you to override server-side person properties for immediate feature flag evaluation, solving the race condition where person properties from identify() calls may not have been processed by the server yet.
Properties are merged additively with existing properties. Feature flags are automatically reloaded after setting properties.
Example Usage
Important: The reload is asynchronous and is not ordered against the automatic preload that
PostHogConfig.preloadFeatureFlagsstarts at setup. SeesetPersonPropertiesForFlags(_:reloadFeatureFlags:)for the startup ordering contract and how to wait for flags evaluated with these properties.
See Also:
setPersonPropertiesForFlags(_:reloadFeatureFlags:)to control flag reloading behavior
PostHogSDK.setPersonPropertiesForFlags(_:reloadFeatureFlags:)
Sets person properties that will be included in feature flag evaluation requests.
Parameters
properties: Dictionary of person properties to include in flag evaluationreloadFeatureFlags: Whether to automatically reload feature flags after setting properties
Discussion
This method allows you to override server-side person properties for immediate feature flag evaluation, solving the race condition where person properties from identify() calls may not have been processed by the server yet.
Properties are merged additively with existing properties.
Example Usage
Startup ordering
Several code paths can each start a /flags request at launch, and none of them is ordered against this call:
-
the automatic preload started during
setup()whenPostHogConfig.preloadFeatureFlagsistrue(the default) — it can go out before your properties are set, so an early flag read may see values evaluated without them, -
identify(...), which reloads flags itself, -
any explicit
reloadFeatureFlags()your app makes.
Requests are coalesced rather than run concurrently, so your properties always reach the server eventually. To read a flag that reflects them, set them without reloading and wait for an explicit reload rather than reading immediately after setup:
Setting PostHogConfig.preloadFeatureFlags = false removes the automatic preload entirely and leaves your app in control of when flags load.
Note:
reset()clears person properties set here, so they must be set again afterwards.
Note:
reloadFeatureFlags(_:)reports that the reload finished, not that it succeeded. If the request fails, or the project is over its feature flag quota, the handler still runs and the flags you read are the previously cached ones.
Shutdown
PostHogSDK.close()
Shuts down this SDK instance and clears its in-memory state.
Discussion
Starts sending queued events, session replay snapshots, and logs (up to one batch each) and returns without waiting for delivery. Anything not sent, for example while offline, stays on disk and is sent after the next setup. Integrations are uninstalled, and this instance must be set up again before reuse.
Start session recording
PostHogSDK.startSessionRecording()
Starts session recording.
Discussion
This method will have no effect if PostHog is not enabled, or if session replay is disabled in your project settings.
Ingestion controls are not overridden when calling this method. The recording will not start if:
-
The session is not sampled,
-
Event triggers are configured and have not been activated for the current session.
Note:
-
Calling this method will resume the current session or create a new one if it doesn’t exist
-
With
config.sessionReplay = false, recording started here continues into new sessions untilstopSessionRecording()is called
PostHogSDK.startSessionRecording(resumeCurrent:)
Starts session recording.
Parameters
resumeCurrent: Whether to resume recording of current session (true) or start a new session (false).
Discussion
This method will have no effect if PostHog is not enabled, or if session replay is disabled in your project settings.
Ingestion controls are not overridden when calling this method. The recording will not start if:
-
The session is not sampled,
-
Event triggers are configured and have not been activated for the current session.
Stop session recording
PostHogSDK.stopSessionRecording()
Stops the current session recording if one is in progress.
Discussion
With config.sessionReplay = false, this also cancels a pending startSessionRecording() call, so remote config loads, event triggers and session changes will not start recording until the app calls startSessionRecording() again. A later optOut() and optIn() don’t restart it either. While opted out this method is ignored.
Stopping also starts a best-effort, asynchronous flush of replay snapshots already recorded instead of waiting for the next scheduled flush. Normal buffering and delivery limits still apply: snapshots can be held back, for example because the session is shorter than the minimum duration, and a large backlog is sent over more than one flush.
This method will have no effect if PostHog is not enabled
Unregister
PostHogSDK.unregister(_:)
Removes a previously registered super property.
Parameters
key: The property key to stop attaching to future events.
Autocapture
PostHogSDK.isAutocaptureActive()
Returns whether UIKit or SwiftUI element autocapture is enabled in local state.
Return Value
true when the SDK is set up and either interaction autocapture option is enabled. This does not verify that the swizzling-backed integration was installed.
PostHogSDK.isRageClickActive()
Returns whether rage click autocapture is enabled in local state.
Return Value
true when the SDK is set up and rage click detection is enabled. This does not verify that the swizzling-backed integration was installed.
Device ID generator
PostHogSDK.getDeviceId()
Returns the stable device identifier used for device-level feature flag bucketing.
Return Value
The stable device ID, or an empty string when the SDK is not set up.
Discussion
This ID persists across identify() and reset() calls, only changing on a fresh app install, manual cache clearing, or OS-initiated storage cleanup.
Session manager
PostHogSDK.endSession()
Ends the current analytics session.
PostHogSDK.startSession()
Starts or resumes the current analytics session.
SDK utils
PostHogSDK.captureDeepLink(openURLContexts:)
Capture a deep link from UIKit scene-based URL contexts.
Parameters
openURLContexts: The set of URL contexts from the scene delegate.
Discussion
Use this method with scene(_:openURLContexts:) in your UISceneDelegate. Only the first URL context is captured.
PostHogSDK.captureDeepLink(url:)
Captures a deep link opened event for a URL.
Parameters
url: The URL that was opened.
PostHogSDK.captureDeepLink(url:options:)
Capture a deep link with UIKit open URL options.
Parameters
url: The URL that was opened.options: The options dictionary from UIKit containing source application info.
Discussion
Use this method with application(_:open:options:) in your UIApplicationDelegate. The source application is extracted as the referrer.
PostHogSDK.captureDeepLink(urls:)
Capture deep link events from an array of URLs.
Parameters
urls: The URLs that were opened.
Discussion
Use this method with macOS NSApplicationDelegate.application(_:open:). File URLs are automatically filtered out; every other URL in the array is captured.
PostHogSDK.captureDeepLink(userActivity:)
Capture a deep link from an NSUserActivity (universal links).
Parameters
userActivity: The user activity containing the universal link.
Discussion
Use this method with application(_:continue:restorationHandler:) in your app delegate, or with SwiftUI’s .onContinueUserActivity() modifier. Only activities of type NSUserActivityTypeBrowsingWeb are processed.
PostHogSDK.captureFeatureInteraction(flag:flagVariant:)
Captures a $feature_interaction event for the specified feature flag.
Parameters
flag: The key of the feature flag being interacted with.flagVariant: The variant of the feature flag being interacted with. Ifnil, the SDK looks up the current flag value and skips capture when no value is available.
PostHogSDK.captureFeatureView(flag:flagVariant:)
Captures a $feature_view event for the specified feature flag.
Parameters
flag: The key of the feature flag being viewed.flagVariant: The variant of the feature flag being viewed. Ifnil, the SDK looks up the current flag value and skips capture when no value is available.
PostHogSDK.capturePushNotificationOpened(response:)
Manually captures a $push_notification_opened event for a notification the user tapped.
Parameters
response: TheUNNotificationResponsereceived from the system.
Discussion
Use this when you’re not relying on the automatic swizzling installed by capturePushNotificationOpened, for example when enableSwizzling is false or when you manage your own UNUserNotificationCenterDelegate. Call it from your userNotificationCenter(_:didReceive:withCompletionHandler:) implementation.
The notification’s title/subtitle/body are included only when the push is attributed to PostHog (a posthog key in its userInfo); unattributed pushes capture the open event without content. Use the field-based overload to capture content explicitly.
A notification sent by PostHog is captured once: when the posthog entry of userInfo carries an invocation_id, a repeat with the same invocation_id and action_id within 5 minutes of the first capture is skipped, whether that first capture came from this method, from the field-based overload, or from the SDK’s automatic capture. Notifications without a posthog.invocation_id are always captured. Only the 20 most recently captured notifications are remembered, so a host that reports more than that inside the window can capture a repeat of the oldest.
A rerun of that workflow, or a loop back to its push step, sends the pair again as a new notification, and its open counts separately: two responses whose notification.request.identifier differ are two taps, not one reported twice.
PostHogSDK.capturePushNotificationOpened(title:subtitle:body:payload:action:)
Manually captures a $push_notification_opened event from raw notification fields.
Parameters
title: The notification title; omitted from the event whennilor empty.subtitle: The notification subtitle; omitted whennilor empty.body: The notification body; omitted whennilor empty.payload: The notification payload (userInfo). The keys of itsposthogentry — a dictionary, or a JSON string when relayed through FCM — become$notification_<key>properties.action: The action identifier for an action-button tap; leavenilfor a plain tap (the default action is omitted from the event).
Discussion
Use this when no UNNotificationResponse is available — for example when you handle a push yourself in application(_:didReceiveRemoteNotification:fetchCompletionHandler:) or relay it from a cross-platform layer.
A notification sent by PostHog is captured once: when payload["posthog"] carries an invocation_id, a repeat with the same invocation_id and action_id within 5 minutes of the first capture is skipped, whether that first capture came from this method or from the SDK’s automatic capture. Payloads without a posthog.invocation_id are always captured. Only the 20 most recently captured notifications are remembered, so a host that reports more than that inside the window can capture a repeat of the oldest. This overload carries no notification identifier, so a rerun of that workflow reported through it inside the window reads as the same tap and is skipped; report a rerun through capturePushNotificationOpened(response:), which can tell the deliveries apart.
PostHogSDK.registerPushNotificationToken(_:)
Sends a device push token to PostHog so Workflows can deliver push notifications to this device.
Parameters
deviceToken: The APNs token as a lowercase-hex string. Convert aDatatoken viatoken.map { String(format: "%02x", $0) }.joined().
Discussion
Call this from application(_:didRegisterForRemoteNotificationsWithDeviceToken:) when you don’t rely on automatic swizzling (for example when enableSwizzling is false).
The token is linked to the current distinct id, so it follows the user across identify(_:).
Note: Push registration is available on iOS only in this version.
PostHogSDK.registerPushNotificationToken(_:appId:)
Sends a device push token to PostHog under an explicit app id.
Parameters
deviceToken: The push token string (APNs lowercase-hex, or an FCM token verbatim).appId: The app identifier the token belongs to, ornilto use the bundle identifier.
Discussion
Use the appId overload when relaying a token obtained through another provider (for example a Firebase project_id). When appId is nil the app’s bundle identifier is used.
Note: Push registration is available on iOS only in this version.
PostHogSDK.unregisterPushNotificationToken()
Unregisters this device’s push token from PostHog so Workflows stop targeting it — for example from your logout flow.
Discussion
Sends a DELETE /api/push_subscriptions/ for the identity the token was delivered to — the current distinct id when nothing was delivered yet — so the backend unsets the subscription property on the person that actually holds it, and forgets the locally stored token. The delete intent is durable: an offline or failed attempt is retried on flush()/next launch until it succeeds or hits a terminal 4xx. Call it directly if you manage push subscriptions yourself. On reset() the SDK already moves any registered token to the new anonymous identity (unregister then re-register), independently of capturePushNotificationSubscriptions — that flag only gates automatic token subscription at startup.
PostHogSDK.didStartNotification
Posted on the main queue after setup(_:) finishes successfully.
Discussion
The notification object is nil.
PostHogSDK.shared
Shared singleton SDK instance used by most applications.
Discussion
Call setup(_:) once with a PostHogConfig before using capture APIs.
PostHogSDK.prewarmPushNotificationOpenCapture()
Installs the notification-open swizzles before setup() is called.
Discussion
A cold launch from a notification tap delivers the response to the app within a few hundred milliseconds — sooner than a cross-platform host (Flutter, React Native) can reach its own setup() call from the Dart/JS runtime, so the swizzles are not yet in place and the open is lost. Call this from application(_:didFinishLaunchingWithOptions:), or from a plugin registration that runs inside it, and the response is held until setup() installs the integration, which then captures it.
Holds at most one response, and only replays it when setup() follows within 30 seconds. Native iOS apps that call setup() from didFinishLaunchingWithOptions do not need this.
The swizzles are installed immediately and released again when the last subscriber detaches (close()), or at setup() when the config disables push-open capture or the app is opted out. If setup() is never called they stay for the process lifetime. The per-class delegate wrapper, as elsewhere in this SDK, stays for the process lifetime regardless.
URLSession.postHogData(for:delegate:postHog:)
Performs data(for:delegate:) and captures network telemetry for session replay.
Parameters
request: Request to execute.delegate: Task delegate for the request.postHog: SDK instance used to read the session ID and emit telemetry. Pass an initialized instance;nilperforms the request without capturing replay telemetry.
Return Value
The data and URL response returned by URLSession.
Discussion
Throws: Any error thrown by
URLSession.data(for:delegate:).
URLSession.postHogData(for:postHog:)
Performs data(for:) and captures network telemetry for session replay.
Parameters
request: Request to execute.postHog: SDK instance used to read the session ID and emit telemetry. Pass an initialized instance;nilperforms the request without capturing replay telemetry.
Return Value
The data and URL response returned by URLSession.
Discussion
Throws: Any error thrown by
URLSession.data(for:).
URLSession.postHogData(from:delegate:postHog:)
Performs data(from:delegate:) and captures network telemetry for session replay.
Parameters
url: URL to request.delegate: Task delegate for the request.postHog: SDK instance used to read the session ID and emit telemetry. Pass an initialized instance;nilperforms the request without capturing replay telemetry.
Return Value
The data and URL response returned by URLSession.
Discussion
Throws: Any error thrown by
URLSession.data(from:delegate:).
URLSession.postHogData(from:postHog:)
Performs data(from:) and captures network telemetry for session replay.
Parameters
url: URL to request.postHog: SDK instance used to read the session ID and emit telemetry. Pass an initialized instance;nilperforms the request without capturing replay telemetry.
Return Value
The data and URL response returned by URLSession.
Discussion
Throws: Any error thrown by
URLSession.data(from:).
URLSession.postHogDownload(for:delegate:postHog:)
Performs download(for:delegate:) and captures network telemetry for session replay.
Parameters
request: Download request to execute.delegate: Task delegate for the request.postHog: SDK instance used to read the session ID and emit telemetry. Pass an initialized instance;nilperforms the request without capturing replay telemetry.
Return Value
The downloaded file URL and URL response returned by URLSession.
Discussion
Throws: Any error thrown by
URLSession.download(for:delegate:).
URLSession.postHogDownload(from:delegate:postHog:)
Performs download(from:delegate:) and captures network telemetry for session replay.
Parameters
url: URL to download.delegate: Task delegate for the request.postHog: SDK instance used to read the session ID and emit telemetry. Pass an initialized instance;nilperforms the request without capturing replay telemetry.
Return Value
The downloaded file URL and URL response returned by URLSession.
Discussion
Throws: Any error thrown by
URLSession.download(from:delegate:).
URLSession.postHogDownload(resumeFrom:delegate:postHog:)
Performs download(resumeFrom:delegate:) and captures network telemetry for session replay.
Parameters
resumeData: Resume data from a previously cancelled download.delegate: Task delegate for the request.postHog: SDK instance used to read the session ID and emit telemetry. Pass an initialized instance;nilperforms the request without capturing replay telemetry.
Return Value
The downloaded file URL and URL response returned by URLSession.
Discussion
Throws: Any error thrown by
URLSession.download(resumeFrom:delegate:).
URLSession.postHogUpload(for:from:delegate:postHog:)
Performs upload(for:from:delegate:) and captures network telemetry for session replay.
Parameters
request: Upload request to execute.bodyData: Request body data to upload.delegate: Task delegate for the request.postHog: SDK instance used to read the session ID and emit telemetry. Pass an initialized instance;nilperforms the request without capturing replay telemetry.
Return Value
The data and URL response returned by URLSession.
Discussion
Throws: Any error thrown by
URLSession.upload(for:from:delegate:).
URLSession.postHogUpload(for:from:postHog:)
Performs upload(for:from:) and captures network telemetry for session replay.
Parameters
request: Upload request to execute.bodyData: Request body data to upload.postHog: SDK instance used to read the session ID and emit telemetry. Pass an initialized instance;nilperforms the request without capturing replay telemetry.
Return Value
The data and URL response returned by URLSession.
Discussion
Throws: Any error thrown by
URLSession.upload(for:from:).
URLSession.postHogUpload(for:fromFile:delegate:postHog:)
Performs upload(for:fromFile:delegate:) and captures network telemetry for session replay.
Parameters
request: Upload request to execute.fileURL: File URL to upload.delegate: Task delegate for the request.postHog: SDK instance used to read the session ID and emit telemetry. Pass an initialized instance;nilperforms the request without capturing replay telemetry.
Return Value
The data and URL response returned by URLSession.
Discussion
Throws: Any error thrown by
URLSession.upload(for:fromFile:delegate:).
URLSession.postHogUpload(for:fromFile:postHog:)
Performs upload(for:fromFile:) and captures network telemetry for session replay.
Parameters
request: Upload request to execute.fileURL: File URL to upload.postHog: SDK instance used to read the session ID and emit telemetry. Pass an initialized instance;nilperforms the request without capturing replay telemetry.
Return Value
The data and URL response returned by URLSession.
Discussion
Throws: Any error thrown by
URLSession.upload(for:fromFile:).
View.postHogDeepLinkListener(_:)
Attach a PostHog deep link listener to this view.
Parameters
posthog: SDK instance to use for tracking. Defaults toPostHogSDK.shared.
Return Value
A modified view that captures supported deep link events.
Discussion
The listener forwards .onOpenURL and .onContinueUserActivity events to PostHog.
View.postHogLabel(_:)
Adds a custom label to this view for use with PostHog’s auto-capture functionality.
Parameters
label: A custom label that uniquely identifies the element for analytics purposes.
Return Value
A modified view that applies the label to the underlying UIKit view when possible.
Discussion
By setting a custom label, you can easily identify and filter interactions with this specific element in your analytics data.
Usage
View.postHogMask(_:)
Marks a SwiftUI View to be masked in PostHog session replay recordings.
Parameters
isEnabled: Whether masking should be enabled. Defaults to true.
Return Value
A modified view that will be masked in session replay recordings when enabled
Discussion
Use this modifier to explicitly mask sensitive views in session replay recordings.
The masked region is reported through a single passive overlay view whose frame is read live at capture time, so the redaction can never go stale — a row that scrolled, animated, or was repositioned is redacted at its current position. This does not rely on mapping SwiftUI content to backing UIKit views, so it behaves identically across OS rendering engines (including iOS 26+).
Note: an explicit postHogMask() always masks its region, even inside an area marked with postHogNoMask() — the explicit mask wins.
Note: for .drawingGroup() or Canvas content, apply this modifier to the group itself.
For example:
View.postHogNoMask()
Marks a SwiftUI View to be excluded from masking in PostHog session replay recordings.
Return Value
A modified view that will not be masked in session replay recordings
Discussion
Note: On iOS 26+ (Xcode 26 SwiftUI rendering engine), SwiftUI views may no longer map reliably to a backing UIView, so this modifier may behave inconsistently. A future SDK update will try to address this limitation, but for now, we recommend using this modifier with caution.
There are cases where PostHog SDK will unintentionally mask some SwiftUI views.
Because of the nature of how we intercept SwiftUI view hierarchy (and how it maps to UIKit), we can’t always be 100% confident that a view should be masked. For that reason, we prefer to take a proactive and prefer to mask views if we’re not sure.
Use this modifier to prevent views from being masked in session replay recordings.
Note: for .drawingGroup() or Canvas content, apply this modifier to the group itself.
For example:
View.postHogNoRageClick(_:)
Excludes a SwiftUI View from PostHog rage click detection.
Parameters
isEnabled: Whether the view should be excluded from rage click detection. Defaults to true.
Return Value
A modified view that is excluded from rage click detection when enabled.
Discussion
Rapid repeated taps on this view (and its descendants) will not be captured as a $rageclick event. Use this for controls where fast repeated tapping is intentional but not auto-detected as a UIKit control — for example a custom-built stepper or carousel arrow.
For example:
View.postHogScreenView(_:_:postHog:)
Marks a SwiftUI view to be tracked as a $screen event when onAppear runs.
Parameters
screenName: The screen name. Defaults to the view’s type name.properties: Additional properties to attach to the$screenevent.postHog: SDK instance used to send the event. Defaults toPostHogSDK.shared.
Return Value
A modified view that captures a screen view when it appears.
View.postHogViewSeen(_:_:postHog:)
Captures a custom event when this SwiftUI view appears.
Parameters
event: Event name to capture.properties: Additional event properties.postHog: SDK instance used to send the event. Defaults toPostHogSDK.shared.
Return Value
A modified view that captures the event when it appears.
UIView.postHogLabel
Adds a custom label to this view for use with PostHog’s auto-capture functionality.
Discussion
By setting a custom label, you can easily identify and filter interactions with this specific element in your analytics data.
Usage
Types
PostHogBootstrapConfig
Pre-seeded identity and feature-flag state applied during setup, before any network request completes.
Overview
Set bootstrap before calling setup(_:) to seed identity and feature flag state. This ensures events captured synchronously during initialization (Application Installed / Application Updated, pre-identify lifecycle events) carry a caller-controlled $distinct_id rather than the SDK-generated UUID, and that feature flag reads return caller-provided values before the first /flags response. Mirrors the bootstrap option in posthog-js.
Identity is seeded on a fresh install. For a returning user, an identified bootstrap (isIdentifiedId == true) reconciles against the stored identity — upgrading a matching anonymous ID to identified, merging a differing anonymous user into the bootstrapped ID, or preserving a different already-identified user. An anonymous bootstrap is ignored once an anonymous ID is persisted. Bootstrapped feature flags form a temporary base layer applied on every initialization: the first complete /flags response replaces them, while a partial or errored response overlays only the keys it recomputed.
PostHogBootstrapConfig.init()
Creates an empty bootstrap; set the properties you need before assigning it to bootstrap.
PostHogBootstrapConfig.init(anonymousId:)
Seeds an anonymous identity: anonymousId becomes the $distinct_id for events captured before the host calls identify(...).
PostHogBootstrapConfig.init(distinctId:isIdentifiedId:)
Seeds identity from a distinctId, stating explicitly whether it is already identified.
Discussion
Pass isIdentifiedId: true for a user the host has already identified (seeds .distinctId and marks the install identified), or false to seed it as an anonymous ID instead (equivalent to init(anonymousId:)).
PostHogBootstrapConfig.init(distinctId:isIdentifiedId:featureFlags:featureFlagPayloads:)
Seeds identity and feature-flag state in one initializer. Pass nil for any dimension you don’t want to seed.
Parameters
distinctId: The ID to seed on first launch, ornilto seed no identity. Used as the anonymous ID whenisIdentifiedIdisfalse, or an already-identified user’s ID whentrue.isIdentifiedId: WhetherdistinctIdis an already-identified user. Defaults tofalse.featureFlags: Flag values served until the first/flagsresponse, ornil.featureFlagPayloads: JSON payloads keyed by flag, paired withfeatureFlags, ornil.
PostHogBootstrapConfig.init(featureFlags:featureFlagPayloads:)
Seeds feature-flag state only, without seeding identity.
PostHogBootstrapConfig.distinctId
The distinct ID to seed on first launch.
Discussion
When isIdentifiedId is false (the default), this becomes the anonymous ID — the $distinct_id on pre-identify events. When true, it is treated as an already-identified user’s distinct ID and the SDK skips the $identify merge for it.
PostHogBootstrapConfig.featureFlagPayloads
JSON payloads paired with featureFlags, keyed by flag key.
Discussion
Each value is the already-decoded payload (for example a dictionary, array, string, or number) for the matching flag, served alongside featureFlags before the first /flags response.
PostHogBootstrapConfig.featureFlags
Feature flag values served until the first /flags response arrives.
Discussion
Maps a flag key to its value (a Bool for boolean flags or a String for multivariate flags). These values are served immediately after setup so flag reads don’t fall back to not-loaded defaults during cold start. They are a temporary base layer: the first complete /flags response replaces the served set entirely, so bootstrapped-only keys are not retained after it; a partial or errored response merges, preserving keys it didn’t recompute.
PostHogBootstrapConfig.isIdentifiedId
Whether distinctId represents an already-identified user.
Discussion
Defaults to false. Set to true when the host application has resolved the user’s identity outside the SDK (for example from a backend session token) and wants the iOS SDK to treat them as identified from the first event onward.
PostHogConfig
Runtime configuration for a PostHogSDK instance.
Overview
Create a config with your project token, mutate any options you need, then pass it to PostHogSDK.shared.setup(_:) or PostHogSDK.with(_:). Options that control queues, integrations, or resource attributes should be set before setup; later mutations may not affect already-installed SDK components.
PostHogConfig.init(apiKey:)
Deprecated: Use init(projectToken:) instead. This will be removed in the next major version.
Creates a configuration using the deprecated apiKey name.
Parameters
apiKey: Your PostHog project token.
Discussion
- Deprecated: Use
init(projectToken:)instead.
PostHogConfig.init(apiKey:host:)
Deprecated: Use init(projectToken:host:) instead. This will be removed in the next major version.
Creates a configuration using the deprecated apiKey name and an explicit host.
Parameters
apiKey: Your PostHog project token.host: PostHog ingestion host. Empty or invalid values fall back todefaultHost.
Discussion
- Deprecated: Use
init(projectToken:host:)instead.
PostHogConfig.init(projectToken:)
Creates a configuration using the default PostHog host.
Parameters
projectToken: Your PostHog project token. Leading and trailing whitespace is trimmed.
PostHogConfig.init(projectToken:host:)
Creates a configuration with an explicit PostHog ingestion host.
Parameters
projectToken: Your PostHog project token. Leading and trailing whitespace is trimmed.host: PostHog ingestion host, for example"https://us.i.posthog.com"or"https://eu.i.posthog.com". Empty or invalid values fall back todefaultHost.
PostHogConfig.apiKey
Deprecated: Use projectToken instead. This will be removed in the next major version.
Obsolete alias for projectToken.
PostHogConfig.appGroupIdentifier
The identifier of the App Group that should be used to store shared analytics data. PostHog will try to get the physical location of the App Group’s shared container, otherwise fallback to the default location Default: nil
PostHogConfig.bootstrap
Pre-seeded identity and feature-flag state applied during setup, before any network request completes.
Discussion
Set this before calling setup(_:) so events captured synchronously during initialization (Application Installed / Application Updated, pre-identify lifecycle events) carry a caller-controlled $distinct_id rather than the SDK-generated UUID, and so feature flag reads return caller-provided values before the first /flags response. Mirrors the bootstrap option in posthog-js.
Identity is seeded on a fresh install. For a returning user, an identified bootstrap (isIdentifiedId == true) reconciles against the stored identity — upgrading a matching anonymous ID to identified, merging a differing anonymous user into the bootstrapped ID, or preserving a different already-identified user. An anonymous bootstrap is ignored once an anonymous ID is persisted.
Feature flags are applied on every initialization and take precedence over the persisted flag cache. They are a temporary base layer: the first complete /flags response replaces them entirely, while a partial or errored response overlays only the keys it recomputed.
Defaults to nil (use the SDK-generated UUID and no bootstrapped flags).
PostHogConfig.captureApplicationLifecycleEvents
Whether the SDK automatically captures application lifecycle events.
Discussion
When enabled, the SDK records events such as Application Installed, Application Updated, Application Opened, and background/foreground transitions. Default: true.
PostHogConfig.captureAutocaptureElementText
Whether autocapture reads control text and selected values. Requires captureElementInteractions to be enabled for regular autocapture events. Also applies to rage-click events when rage-click detection is enabled independently. Explicit postHogLabel identifiers remain available when disabled. Manual events and session replay are unaffected. Accessibility labels may still be read to check exclusion markers. Configure before SDK setup. Defaults to true.
PostHogConfig.captureElementInteractions
Enables UIKit element interaction autocapture on iOS and Mac Catalyst.
Discussion
Enable captureSwiftUIElementInteractions for better SwiftUI autocapture events. When that option is disabled, existing SwiftUI gesture capture is preserved. Requires enableSwizzling = true. Default: false.
PostHogConfig.capturePushNotificationOpened
Automatically capture a $push_notification_opened event when the user taps a remote push notification, by swizzling UNUserNotificationCenterDelegate. Locally-scheduled notifications are ignored — capture those yourself with PostHogSDK.capturePushNotificationOpened(title:subtitle:body:payload:action:), passing the content you scheduled. capturePushNotificationOpened(response:) reads title/subtitle/body only from notifications PostHog sent (a posthog key in userInfo), so for a local one it captures the open with no content.
Discussion
A notification sent by PostHog is captured once: a manual capturePushNotificationOpened call for a tap this already captured (same posthog.invocation_id and action_id, within 5 minutes) is skipped, and so is the reverse. A resend of that notification is a separate tap and is captured.
Note: Requires
enableSwizzlingto betrue. To capture opens without swizzling, callPostHogSDK.capturePushNotificationOpened(response:)from your ownuserNotificationCenter(_:didReceive:withCompletionHandler:)implementation.
Default: true. Set to false to opt out.
Requires your app to set UNUserNotificationCenter.current().delegate. Without one, iOS reports the tap to nobody and no open can be captured, in any app state.
PostHogConfig.capturePushNotificationSubscriptions
Automatically register the device’s APNs token with PostHog by swizzling application(_:didRegisterForRemoteNotificationsWithDeviceToken:), so Workflows can deliver push notifications.
Discussion
Note: Requires
enableSwizzlingto betrue. To register tokens without swizzling, callPostHogSDK.registerPushNotificationToken(_:)from your ownapplication(_:didRegisterForRemoteNotificationsWithDeviceToken:)implementation. Registration is iOS-only in this version.
Default: true. Set to false to opt out.
PostHogConfig.captureScreenViews
Automatically captures a $screen event whenever the visible screen changes (via viewDidAppear swizzling).
Discussion
A split view that shows several columns at once counts as one screen, named after the split view, so navigating inside one of its columns does not capture a $screen event. Call PostHogSDK.shared.screen(...) to track those screens.
$screen_name stamping on subsequent events is a related effect: any successful screen() call — whether fired by this auto-capture path or invoked manually via PostHogSDK.shared.screen(...) — caches the screen name so it lands as $screen_name on every later event the SDK captures. To opt out of $screen_name stamping entirely, set this to false and avoid calling screen(...) manually.
Default: true
PostHogConfig.captureSwiftUIElementInteractions
Enables SwiftUI tap autocapture on iOS and Mac Catalyst.
Discussion
Works independently of captureElementInteractions and requires enableSwizzling = true. SwiftUI controls backed by UIKit, such as TextField, still require captureElementInteractions = true to capture their control interactions. Uses element labels and accessibility identifiers to resolve SwiftUI taps, replacing legacy hosting-view tap events. Event counts and element chains can differ from legacy capture. Unresolved elements are skipped. Configure before SDK setup. Default: false.
PostHogConfig.compression
How the SDK compresses request bodies before sending them to the PostHog API.
Discussion
Set this to .none when the network between the app and PostHog changes or re-encodes the compressed body, e.g. on a managed work profile, which makes the server reject the request.
Default: .gzip.
PostHogConfig.dataMode
Required network connectivity mode for flushing queued data.
Discussion
Only .wifi restricts flushing. Default: .any.
PostHogConfig.debug
Enables verbose SDK diagnostic logging.
Discussion
Default: false.
PostHogConfig.disableGeoIp
Skip GeoIP enrichment on the server for captured events and feature flag requests.
Discussion
When enabled, the server won’t infer the user’s location from their IP address.
Default: false
PostHogConfig.enableSwizzling
Enable method swizzling for SDK functionality that depends on it
Discussion
When disabled, functionality that require swizzling (like autocapture, screen views, session replay, surveys) will not be installed.
Note: Disabling swizzling will limit session rotation logic to only detect application open and background events. Session rotation will still work, just with reduced granularity for detecting user activity.
Default: true
PostHogConfig.errorTrackingConfig
Configuration for error tracking.
Discussion
See known limitations: https://posthog.com/docs/error-tracking/installation/ios#limitations
PostHogConfig.evaluationContexts
Evaluation contexts for feature flags.
Discussion
When configured, only feature flags that have at least one matching evaluation tag will be evaluated. Feature flags with no evaluation tags will always be evaluated for backward compatibility.
Example usage:
This helps ensure feature flags are only evaluated in the appropriate contexts for your SDK instance.
Default: nil (all flags are evaluated)
PostHogConfig.evaluationEnvironments
Deprecated: Use evaluationContexts instead. This property will continue to work but will be removed in a future version.
Deprecated alias for evaluationContexts.
Discussion
- Deprecated: Use
evaluationContextsinstead. This property will be removed in a future version.
PostHogConfig.featureFlagRequestMaxRetries
Maximum number of retries for feature flag requests after transient network errors or retryable HTTP responses. Defaults to 1. Set to 0 to disable feature flag request retries.
PostHogConfig.flushAt
Number of queued events that triggers an automatic flush.
Discussion
Lower values send data sooner but can increase battery and network usage. Default: 20 (5 on tvOS).
PostHogConfig.flushIntervalSeconds
Interval, in seconds, between periodic queue flush checks.
Discussion
Lower values deliver events closer to real time but can increase battery usage. Default: 30.
PostHogConfig.getAnonymousId
Hook used to customize newly generated anonymous IDs.
Parameters
uuid: The SDK-generated anonymous UUID.
Return Value
The UUID to persist as the anonymous ID.
Discussion
The SDK passes its generated UUID v7 and stores the UUID returned by this closure. Existing stored anonymous IDs are not regenerated.
PostHogConfig.host
PostHog ingestion host used for all SDK network requests.
Discussion
Defaults to PostHogConfig.defaultHost when the initializer host is empty or invalid.
PostHogConfig.logs
Configuration for the logs subsystem (manual captureLog capture). Mutate fields on config.logs before calling PostHogSDK.setup(_:).
PostHogConfig.maxBatchSize
Maximum number of events included in a single batch request.
Discussion
Default: 50.
PostHogConfig.maxQueueSize
Maximum number of events kept in the on-disk queue before older events are dropped.
Discussion
Default: 1000 (100 on tvOS).
PostHogConfig.maxRetries
Maximum number of retries for push-subscription registration failures.
Discussion
This limit does not apply to event, replay, or log ingestion. Retryable ingestion failures retain queued records for later flush triggers, subject to backoff. Use maxQueueSize for events and replay, and logs.maxBufferSize for logs.
Default: 3.
PostHogConfig.optOut
Starts the SDK in an opted-out state when set before setup.
Discussion
While opted out, capture calls are ignored and integrations are not installed. Use PostHogSDK.optIn() and PostHogSDK.optOut() to change the persisted state at runtime. A state persisted by an earlier launch wins over this value, unless reset() cleared it or opt-out persistence is turned off. Default: false.
PostHogConfig.personProfiles
Determines the behavior for processing user profiles.
PostHogConfig.preloadFeatureFlags
Whether feature flags are loaded automatically during SDK setup.
Discussion
The preload is started automatically during setup() and is not ordered against anything your app does after setup(). In particular it can go out before a setPersonPropertiesForFlags(...) call, in which case the first /flags response is evaluated without those overrides and an early flag read can see the pre-override value until the reload triggered by that call lands. See setPersonPropertiesForFlags(_:reloadFeatureFlags:) for the ordering contract and how to wait for flags evaluated with your overrides.
Default: true.
PostHogConfig.projectToken
Your PostHog project token.
Discussion
You can find it at: https://us.posthog.com/settings/project-details#variables
This field was formerly named apiKey.
PostHogConfig.propertiesSanitizer
Deprecated: Use beforeSend instead
Hook that allows to sanitize the event properties The hook is called before the event is cached or sent over the wire
PostHogConfig.pushIdentityProvider
Supplies a signed identity token to attach (as identity_token) to push subscription register/unregister requests, for projects that enable identity verification on their push integration. Invoked with the distinct_id and app_id the request carries; call completion exactly once, from any thread, with a token minted by your backend — or nil to send the request without one. The SDK never mints tokens itself: your backend signs an HS256 JWT with the project’s secret API key, claims sub = distinct id, app_id, aud = “posthog:push_identity”, and an exp.
Discussion
The token is cached in memory per (distinctId, appId) and re-requested on identity change, on the next launch, and once after a 401 rejection. If completion isn’t called within ~10s the SDK stops waiting and sends the request without an identity token; where your project requires identity verification the backend will likely reject it, so make sure your provider always completes.
The hook is invoked on a background queue that serializes push-registration work — never on the calling thread — and completion may be called from any thread. Still return promptly: blocking here stalls the SDK’s push retry/offline-resume flow (though not your app’s main thread).
Default: nil (requests carry no identity token).
PostHogConfig.rageClickConfig
Rage click detection configuration.
PostHogConfig.remoteConfig
Deprecated: Remote config is now always loaded. This option is a no-op and will be removed in a future version.
Deprecated no-op for remote config loading.
Discussion
Remote config is now always loaded; setting this property has no effect.
- Deprecated: Remote config is always loaded. This option will be removed in a future version.
PostHogConfig.requestHeaders
Custom headers to send with every request to the PostHog API. Useful for reverse-proxy setups that require authentication, e.g. an Authorization header. Read once when the SDK is set up; changes after setup are ignored.
PostHogConfig.reuseAnonymousId
Flag to reuse the anonymous Id between reset() and next identify() calls
Discussion
If enabled, the anonymous Id will be reused for all anonymous users on this device, essentially creating a “Guest user Id” as long as this option is enabled.
Note: Events captured before call to identify() won’t be linked to the identified user Events captured after call to reset() won’t be linked to the identified user
Defaults to false.
PostHogConfig.sendFeatureFlagEvent
Whether feature flag lookups automatically capture $feature_flag_called events.
Discussion
Individual lookup calls can override this value with their sendFeatureFlagEvent parameter. Default: true.
PostHogConfig.sessionReplay
Enable Recording of Session Replays for iOS
Discussion
Note: Ingestion controls (sampling, feature flags, and event triggers) are currently applied using AND logic. All configured conditions must be satisfied for recording to start.
Default: false
PostHogConfig.sessionReplayConfig
Session Replay configuration
PostHogConfig.setDefaultPersonProperties
Automatically set common device and app properties as person properties for feature flag evaluation.
Discussion
When enabled, the SDK will automatically set the following person properties:
-
$app_version: App version from bundle
-
$app_build: App build number from bundle
-
$app_namespace: App bundle identifier
-
$os_name: Operating system name (iOS, macOS, etc.)
-
$os_version: Operating system version
-
$device_type: Device type (Mobile, Tablet, Desktop, etc.)
-
$lib: SDK name
-
$lib_version: SDK version
This helps ensure feature flags that rely on these properties work correctly without waiting for server-side processing of identify() calls.
Default: true
PostHogConfig.snapshotEndpoint
Session replay snapshot endpoint path.
Discussion
Warning: This value is managed by the SDK from remote configuration and should not be changed by application code.
PostHogConfig.storageManager
Storage manager used by this configuration.
Discussion
Warning: This is an SDK extension point used internally to share identity storage with SDK integrations and tests. Application code should not normally replace it.
PostHogConfig.surveys
Enable mobile surveys
Discussion
Default: true
Note: Event triggers will only work with the instance that first enables surveys. In case of multiple instances, please make sure you are capturing events on the instance that has config.surveys = true
PostHogConfig.surveysConfig
Configuration for mobile survey presentation and localization.
Discussion
Mutate fields on config.surveysConfig or replace this object before calling setup. Available on iOS 15 and later.
PostHogConfig.tracingHeaders
When set, PostHog injects tracing headers into URLSession requests whose destination hostname exactly matches one of the configured hostnames.
Discussion
Injected headers on iOS:
-
X-POSTHOG-DISTINCT-ID -
X-POSTHOG-SESSION-ID
Notes:
-
Requires
enableSwizzling = true -
Hostname matching is exact and does not include ports or subdomain wildcards
-
iOS does not send
X-POSTHOG-WINDOW-IDbecause mobile apps do not have a per-window/tab concept -
Existing values for these headers will be overwritten
PostHogConfig.urlSessionConfiguration
Optional custom URLSessionConfiguration for network requests If not set, uses URLSessionConfiguration.default Useful for testing, proxying, or custom network configurations
PostHogConfig.setBeforeSend(_:)
Replaces the event beforeSend chain with the provided blocks.
Parameters
blocks: Ordered callbacks that can mutate or drop events.
Replaces the event beforeSend chain with the provided blocks.
Parameters
blocks: Ordered callbacks that can mutate or drop events.
Discussion
Blocks run synchronously in array order before an event is cached or sent. Returning nil from any block drops the event and skips the remaining blocks.
PostHogConfig.defaultHost
Default PostHog ingestion host for US Cloud projects.
Discussion
Use "https://eu.i.posthog.com" for EU Cloud projects.
PostHogConfig.PostHogConfig.PostHogDataMode
Network connectivity mode required before queued data may be flushed.
PostHogDisplayChoiceQuestion
Represents a multiple or single choice question where users can select one or more options
PostHogDisplayChoiceQuestion.choices
The list of options for the user to choose from
PostHogDisplayChoiceQuestion.hasOpenChoice
Whether the question includes an “other” option for users to input free-form text
PostHogDisplayChoiceQuestion.isMultipleChoice
Whether the user can select multiple options
PostHogDisplayChoiceQuestion.shuffleOptions
Whether the options should be shuffled to randomize the order
PostHogDisplayChoiceQuestion.skipSubmitButton
Whether selection should submit automatically for single-choice questions without an open choice
PostHogDisplayLinkQuestion
Represents a question with a clickable link
PostHogDisplayLinkQuestion.link
The URL that will be opened when the link is clicked
PostHogDisplayOpenQuestion
Represents an open-ended question where users can input free-form text
PostHogDisplayRatingQuestion
Represents a rating question where users can select a rating from a scale
PostHogDisplayRatingQuestion.lowerBoundLabel
The label for the lower bound of the rating scale
PostHogDisplayRatingQuestion.ratingType
The type of rating scale (numbers, emoji)
PostHogDisplayRatingQuestion.scaleLowerBound
The lower bound of the rating scale
PostHogDisplayRatingQuestion.scaleUpperBound
The upper bound of the rating scale
PostHogDisplayRatingQuestion.skipSubmitButton
Whether selecting a rating submits the answer without a submit button
PostHogDisplayRatingQuestion.upperBoundLabel
The label for the upper bound of the rating scale
PostHogDisplaySurvey
A model representing a PostHog survey to be displayed to users
PostHogDisplaySurvey.appearance
Optional appearance configuration for customizing the survey’s look and feel
PostHogDisplaySurvey.endDate
Optional date indicating when the survey should stop being shown
PostHogDisplaySurvey.id
Unique identifier for the survey
PostHogDisplaySurvey.initialQuestionIndex
The question to show when restoring an unfinished survey. Zero for a new survey.
PostHogDisplaySurvey.name
Name of the survey
PostHogDisplaySurvey.questions
Array of questions to be presented in the survey
PostHogDisplaySurvey.startDate
Optional date indicating when the survey should start being shown
PostHogDisplaySurveyAppearance
Model that describes the appearance customization of a PostHog survey
PostHogDisplaySurveyAppearance.backgroundColor
Optional background color as web color (e.g. “#FFFFFF” or “white”)
PostHogDisplaySurveyAppearance.borderColor
Optional border color as web color
PostHogDisplaySurveyAppearance.descriptionTextColor
Optional color for description text as web color
PostHogDisplaySurveyAppearance.displayIntroScreen
Whether to show an intro screen before the first question
PostHogDisplaySurveyAppearance.displayThankYouMessage
Whether to show a thank you message after survey completion
PostHogDisplaySurveyAppearance.fontFamily
Optional font family to use throughout the survey
PostHogDisplaySurveyAppearance.inputBackground
Optional background color for input fields as web color
PostHogDisplaySurveyAppearance.inputTextColor
Optional text color for input fields as web color
PostHogDisplaySurveyAppearance.introScreenButtonText
Optional text for the button that advances past the intro screen
PostHogDisplaySurveyAppearance.introScreenDescription
Optional description text for the intro screen
PostHogDisplaySurveyAppearance.introScreenDescriptionContentType
Optional content type for the intro screen description
PostHogDisplaySurveyAppearance.introScreenHeader
Optional header text for the intro screen
PostHogDisplaySurveyAppearance.placeholder
Optional placeholder text for input fields
PostHogDisplaySurveyAppearance.ratingButtonActiveColor
Optional color for active/selected rating buttons as web color
PostHogDisplaySurveyAppearance.ratingButtonColor
Optional color for rating buttons as web color
PostHogDisplaySurveyAppearance.submitButtonColor
Optional background color for the submit button as web color
PostHogDisplaySurveyAppearance.submitButtonText
Optional custom text for the submit button
PostHogDisplaySurveyAppearance.submitButtonTextColor
Optional text color for the submit button as web color
PostHogDisplaySurveyAppearance.surveyPopupDelaySeconds
Optional delay in seconds before showing the survey
PostHogDisplaySurveyAppearance.textColor
Optional primary text color as web color (for questions, close button, etc.)
PostHogDisplaySurveyAppearance.thankYouMessageCloseButtonText
Optional text for the close button in the thank you message
PostHogDisplaySurveyAppearance.thankYouMessageDescription
Optional description text for the thank you message
PostHogDisplaySurveyAppearance.thankYouMessageDescriptionContentType
Optional content type for the thank you message description
PostHogDisplaySurveyAppearance.thankYouMessageHeader
Optional header text for the thank you message
PostHogDisplaySurveyQuestion
Base class for all survey question types
PostHogDisplaySurveyQuestion.buttonText
Optional custom text for the question’s action button
PostHogDisplaySurveyQuestion.id
The question ID, empty if none
PostHogDisplaySurveyQuestion.isOptional
Whether the question can be skipped
PostHogDisplaySurveyQuestion.question
The main question text to display
PostHogDisplaySurveyQuestion.questionDescription
Optional additional description or context for the question
PostHogDisplaySurveyQuestion.questionDescriptionContentType
Content type for the question description (HTML or plain text)
PostHogErrorTrackingConfig
Configuration for error tracking and exception capture.
Overview
This class controls how exceptions are captured and processed, including which stack trace frames are marked as “in-app” code.
PostHogErrorTrackingConfig.init()
Creates an error tracking configuration with default in-app frame detection.
PostHogErrorTrackingConfig.autoCapture
Whether crash autocapture is enabled.
Discussion
When enabled, fatal crashes are persisted and sent as $exception events on the next launch. Default: false.
PostHogErrorTrackingConfig.exceptionSteps
Configuration for exception steps (breadcrumb-style context records).
Discussion
Steps recorded via PostHogSDK.addExceptionStep(_:properties:) accumulate over the run and are attached to every captured $exception as $exception_steps, giving the error tracking UI a timeline of recent activity before each error.
PostHogErrorTrackingConfig.ignoredExceptionTypes
Exception types to drop instead of sending them as $exception events.
Discussion
Applies to every $exception event, including crash autocapture and captureException(_:). An exception is dropped when any entry in its $exception_list has a type (for an NSException, its name) that exactly matches a value in this list. Matching is case-sensitive.
Default: [].
PostHogErrorTrackingConfig.inAppByDefault
Configures whether stack trace frames are considered in-app by default when the origin cannot be determined or no explicit includes/excludes match.
Discussion
-
If
true(default): Frames are in-app unless explicitly excluded (allowlist approach) -
If
false: Frames are external unless explicitly included (denylist approach)
Default behavior when true:
-
Known system frameworks (Foundation, UIKit, etc.) are excluded
-
All other packages are in-app unless in
inAppExcludes
Precedence: Priority 4 (final fallback)
Default: true
PostHogErrorTrackingConfig.inAppExcludes
List of package/bundle identifiers to be excluded from in-app frames
Discussion
Frames matching these prefixes will be marked as not in-app, unless they also match inAppIncludes (which takes precedence).
Example:
Precedence: Priority 2 (after inAppIncludes)
PostHogErrorTrackingConfig.inAppIncludes
List of package/bundle identifiers to be considered in-app frames
Discussion
Takes precedence over inAppExcludes. If a frame’s module matches any prefix in this list, it will be marked as in-app.
Example:
Default behavior:
-
Automatically includes main bundle identifier
-
Automatically includes executable name
Precedence: Priority 1 (highest)
PostHogEvent
Event object passed through BeforeSendBlock before it is queued.
Overview
Mutate fields in your before-send callback to redact or enrich the event, or return nil from the callback to drop it. Instances are created by the SDK; application code normally captures events through PostHogSDK.capture instead of constructing this type.
PostHogEvent.distinctId
Distinct ID associated with the event.
PostHogEvent.event
Event name, such as "user_signed_up" or "$screen".
PostHogEvent.properties
Event properties that will be serialized with the event.
PostHogEvent.timestamp
Event timestamp. The absolute instant is serialized in UTC, regardless of the calendar or time zone used to create it.
PostHogEvent.uuid
Unique event identifier generated by the SDK.
PostHogExceptionStepsConfig
Configuration for exception steps (breadcrumb-style context records).
Overview
Steps accumulate in a FIFO buffer bounded by a UTF-8 byte budget and are attached to every captured $exception. On a fatal crash they are persisted with the crash context and attached to the crash $exception on the next launch.
PostHogExceptionStepsConfig.enabled
Whether exception steps are recorded and attached to exceptions.
Discussion
When false, addExceptionStep(_:properties:) is a no-op and no steps are attached.
Default: true.
PostHogExceptionStepsConfig.maxBytes
Maximum total UTF-8 byte size of the buffered steps.
Discussion
When adding a step would exceed this budget, the oldest steps are evicted first. A single step larger than the budget is rejected outright.
Default: 32768 (32 KB).
PostHogFeatureFlagResult
Result object containing all information about a feature flag evaluation.
Overview
This class provides access to the flag’s enabled state, variant, and payload in a single convenient object.
Example Usage
PostHogFeatureFlagResult.enabled
Whether the feature flag is enabled.
Discussion
This is true if the flag value is:
-
A boolean
true -
A non-null string (variant)
PostHogFeatureFlagResult.key
The key of the feature flag.
PostHogFeatureFlagResult.payload
The payload associated with this feature flag, if any.
Discussion
The payload can be any JSON-serializable value (string, number, boolean, array, or dictionary).
PostHogFeatureFlagResult.variant
The variant name if this is a multivariate flag, otherwise nil.
PostHogFeatureFlagResult.payloadAs(_:)
Returns the payload deserialized as the specified Decodable type.
Parameters
type: The type to decode the payload as
Return Value
The payload as type T, or nil if the payload is nil or decoding fails
Discussion
If the payload is already an instance of T, returns it directly. Otherwise, attempts to serialize to JSON and decode.
PostHogFeatureFlagsLoaded
The feature flags passed to an onFeatureFlags callback.
Example Usage
PostHogFeatureFlagsLoaded.errorsLoading
true if the latest attempt to load feature flags failed.
Discussion
When it did, flags and variants hold the last known values, which can be empty.
PostHogFeatureFlagsLoaded.flags
The keys of the enabled feature flags.
PostHogFeatureFlagsLoaded.variants
The values of the enabled feature flags, keyed by flag key.
Discussion
A value is true for an enabled boolean flag, or the variant String for a multivariate flag. Disabled flags are not included.
PostHogFeatureFlagsSubscription
A registration returned by PostHogSDK.onFeatureFlags(_:).
Overview
The callback stays registered until you call unsubscribe(). You don’t need to keep a reference to this object unless you want to unsubscribe later.
PostHogFeatureFlagsSubscription.unsubscribe()
Stops the callback from being invoked. Calling it more than once has no effect.
PostHogLogEntry
A model representing a processed console log entry for session replay.
Overview
Describes a single console log entry after it has been processed by PostHogSessionReplayConsoleLogConfig.logSanitizer. Each instance contains the log message content and its determined severity level.
PostHogLogEntry.init(level:message:)
Creates a new console log entry.
Parameters
level: The severity level of the log entrymessage: The processed log message content
PostHogLogEntry.level
The severity level of the log entry. This determines how the log will be displayed in the session replay and whether it will be captured based on minLogLevel setting.
PostHogLogEntry.message
The actual content of the log message. This is the processed and sanitized log message
PostHogLogRecord
A captured log entry passed to your beforeSend callback. Mutate the fields below to redact, enrich, or rewrite the record; return nil to drop it.
Overview
Instances are created by the SDK at capture time. Mutations made after the callback returns have no effect — the record is encoded into the on-disk queue as soon as beforeSend finishes.
PostHogLogRecord.attributes
Free-form attributes attached to this record. Values must be JSON-serializable (String, Int, Double, Bool, arrays/dicts of the same, NSNumber); anything else is silently dropped at flush time. Use this to add structured context (request ids, build numbers, experiment buckets) or to remove keys you don’t want sent.
Discussion
From ObjC: bridges to an immutable NSDictionary. To mutate, take a mutableCopy, edit it, and assign back to the property — in-place mutation on the returned dictionary will fail.
PostHogLogRecord.body
The log message body. Required; empty bodies are dropped at capture time.
PostHogLogRecord.distinctId
PostHog distinct id of the user at capture time, or nil if no user is identified. Set to nil (or to a hash) to redact.
PostHogLogRecord.featureFlagKeys
Feature flag keys that were active at capture time. Empty when no flags are loaded. Useful for correlating logs with experiment cohorts; clear or filter to redact.
Discussion
From ObjC: bridges to an immutable NSArray. Replace the property to mutate; in-place mutation will fail.
PostHogLogRecord.level
Severity of the log entry. Reassign to re-classify (e.g. demote a noisy .warn to .debug).
PostHogLogRecord.screenName
Last screen name observed by automatic screen-view tracking, or nil if screen tracking is disabled or no screen has been seen yet. Set to nil (or rewrite) to redact navigation context.
PostHogLogRecord.sessionId
PostHog session id at capture time, or nil if no session is active. Set to nil to disassociate the record from the session.
PostHogLogRecord.spanId
W3C span id (16 hex characters) if this log belongs to a span. nil when no span is active.
PostHogLogRecord.traceFlags
W3C trace flags. Lower 8 bits are the bitfield; bit 0 is the sampled flag. nil omits the field on the wire; 0 explicitly emits zero.
PostHogLogRecord.traceId
W3C trace id (32 hex characters) if you’ve correlated this log with a distributed trace. nil when no trace context is associated. Set or rewrite for tracing integrations.
PostHogLogger
Convenience facade for capturing log records. Use PostHogSDK.shared.logger to call trace, debug, info, warn, error, or fatal.
PostHogLogger.debug(_:)
Capture a .debug record. Diagnostic detail useful during development.
Parameters
body: The log message. Required and non-empty.
PostHogLogger.debug(_:attributes:)
Capture a .debug record with structured attributes.
Parameters
body: The log message. Required and non-empty.attributes: Per-record attributes. Values must be JSON-serializable.
PostHogLogger.error(_:)
Capture an .error record. An operation failed; the app may continue.
Parameters
body: The log message. Required and non-empty.
PostHogLogger.error(_:attributes:)
Capture an .error record with structured attributes.
Parameters
body: The log message. Required and non-empty.attributes: Per-record attributes. Values must be JSON-serializable.
PostHogLogger.fatal(_:)
Capture a .fatal record. An unrecoverable failure; the app likely cannot continue.
Parameters
body: The log message. Required and non-empty.
PostHogLogger.fatal(_:attributes:)
Capture a .fatal record with structured attributes.
Parameters
body: The log message. Required and non-empty.attributes: Per-record attributes. Values must be JSON-serializable.
PostHogLogger.info(_:)
Capture an .info record. Default level for regular runtime events.
Parameters
body: The log message. Required and non-empty.
PostHogLogger.info(_:attributes:)
Capture an .info record with structured attributes.
Parameters
body: The log message. Required and non-empty.attributes: Per-record attributes. Values must be JSON-serializable.
PostHogLogger.trace(_:)
Capture a .trace record. Finest-grained detail; usually only enabled while diagnosing.
Parameters
body: The log message. Required and non-empty.
PostHogLogger.trace(_:attributes:)
Capture a .trace record with structured attributes.
Parameters
body: The log message. Required and non-empty.attributes: Per-record attributes. Values must be JSON-serializable.
PostHogLogger.warn(_:)
Capture a .warn record. Something unexpected happened but the operation continued.
Parameters
body: The log message. Required and non-empty.
PostHogLogger.warn(_:attributes:)
Capture a .warn record with structured attributes.
Parameters
body: The log message. Required and non-empty.attributes: Per-record attributes. Values must be JSON-serializable.
PostHogLogsConfig
Configuration for the PostHog logs subsystem. Mutate fields on config.logs before calling PostHogSDK.setup(_:).
PostHogLogsConfig.init()
Creates a logs configuration with default queueing, resource, and rate-cap options.
PostHogLogsConfig.environment
OpenTelemetry deployment.environment resource attribute. Omitted from the payload when nil. Set before PostHogSDK.setup(_:); later mutations are ignored.
PostHogLogsConfig.flushAt
Threshold at which the queue triggers a flush automatically. Smaller than maxBatchSize lets the queue fire smaller batches on a steady cadence rather than waiting for the full cap.
PostHogLogsConfig.flushIntervalSeconds
How often the queue checks for records to flush. Set before PostHogSDK.setup(_:); later mutations are ignored.
PostHogLogsConfig.maxBatchSize
Initial maximum number of records sent in a single request. May be reduced under server backpressure.
PostHogLogsConfig.maxBufferSize
Maximum number of records held on disk. When full, the oldest record is dropped (FIFO).
PostHogLogsConfig.rateCapMaxLogs
Maximum number of records accepted per rateCapWindowSeconds. Set to 0 (or any non-positive value) to disable the cap. Set before PostHogSDK.setup(_:); later mutations are ignored.
PostHogLogsConfig.rateCapWindowSeconds
Tumbling window in seconds used by the rate cap. Must be positive; non-positive values disable the cap. Set before PostHogSDK.setup(_:); later mutations are ignored.
PostHogLogsConfig.resourceAttributes
Additional OpenTelemetry resource attributes attached to every batch. SDK-managed keys (telemetry.sdk.*, os.*, service.name) win on key collision so users can’t shadow them. Set before PostHogSDK.setup(_:); later mutations are ignored.
Discussion
From ObjC: bridges to an immutable NSDictionary. Replace the property to change it; in-place mutation on the returned dictionary will fail.
PostHogLogsConfig.serviceName
OpenTelemetry service.name resource attribute. Defaults to the host app’s bundle identifier. Set before PostHogSDK.setup(_:); later mutations are ignored.
PostHogLogsConfig.serviceVersion
OpenTelemetry service.version resource attribute. Defaults to the host app’s CFBundleShortVersionString, or empty if unavailable. Empty values are omitted from the wire payload. Set before PostHogSDK.setup(_:); later mutations are ignored.
PostHogLogsConfig.setBeforeSend(_:)
Replaces the log beforeSend chain with the provided blocks.
Parameters
blocks: Ordered callbacks that can mutate or drop log records.
Discussion
Blocks run synchronously in array order before a log is enqueued. Returning nil from any block drops the log and skips the remaining blocks.
Replaces the log beforeSend chain with the provided blocks.
Parameters
blocks: Ordered callbacks that can mutate or drop log records.
PostHogNextSurveyQuestion
A model representing the next state of the survey progression.
PostHogNextSurveyQuestion.isSurveyCompleted
Whether all questions have been answered and the survey is complete Depending on the survey appearance configuration, you may want to show the “Thank you” message or dismiss the survey at this point
PostHogNextSurveyQuestion.questionIndex
The index of the next question to be displayed (0-based)
PostHogRageClickConfig
Configuration for iOS/macCatalyst rage click autocapture.
Overview
Rage click detection captures $rageclick when a user rapidly taps the same area.
PostHogRageClickConfig.enabled
Enable rage click detection for iOS/macCatalyst.
Discussion
When enabled, rapid taps in the same area will be captured as $rageclick events. Works independently of captureElementInteractions — you can enable rage click detection without enabling full autocapture.
Default: true
PostHogRageClickConfig.minimumTapCount
Number of consecutive taps within the threshold to qualify as a rage click.
Discussion
Default: 3
PostHogRageClickConfig.thresholdPoints
Manhattan distance threshold in logical points.
Discussion
Taps within this distance from the previous tap are considered “in the same area”. Uses Manhattan distance: |x1 - x2| + |y1 - y2|.
Default: 30
PostHogRageClickConfig.timeoutInterval
Maximum time interval between consecutive taps to count as part of the same sequence.
Discussion
If more than this interval passes between two taps, the sequence resets.
Default: 1.0 (seconds)
PostHogSessionManager
Manages the active PostHog session ID and session rotation state.
Overview
Warning: This class is public for backwards compatibility, but is intended for SDK-internal use only. Application code should use
PostHogSDK.getSessionId(),startSession(), andendSession()instead of interacting with this manager directly.
PostHogSessionManager.setSessionId(_:)
Deprecated: PostHogSessionManager becomes SDK-internal in PostHog 4.0. Use PostHogSDK.shared.getSessionId(), startSession() and endSession() instead. From 4.0, wrapper SDKs must import PostHog with @_spi(PostHogInternal) to use it.
Overrides the current session ID.
Parameters
sessionId: Session ID to use for subsequent events.
Discussion
Use with care: changing the session ID affects analytics session attribution and session replay.
PostHogSessionManager.shared
Deprecated: PostHogSessionManager becomes SDK-internal in PostHog 4.0. Use PostHogSDK.shared.getSessionId(), startSession() and endSession() instead. From 4.0, wrapper SDKs must import PostHog with @_spi(PostHogInternal) to use it.
Session manager used by PostHogSDK.shared.
PostHogSessionReplayConfig
Configuration for iOS session replay capture.
Overview
Mutate fields on config.sessionReplayConfig before calling PostHogSDK.setup(_:).
PostHogSessionReplayConfig.captureLogs
Enable capturing console output for session replay.
Discussion
When enabled, logs from the following sources will be captured:
-
Standard output (stdout)
-
Standard error (stderr)
-
OSLog messages
-
NSLog messages
Each log entry will be tagged with a level (info/warning/error) based on the message content and the source.
Defaults to false
Note: When enabled, can be disabled remotely via project settings (requires PostHogConfig.remoteConfig to be enabled)
PostHogSessionReplayConfig.captureLogsConfig
Further configuration for capturing console output
PostHogSessionReplayConfig.captureNetworkTelemetry
Enable capturing network telemetry Default: true
Discussion
Note: When enabled, can be disabled remotely via project settings (requires PostHogConfig.remoteConfig to be enabled)
PostHogSessionReplayConfig.captureTouches
Enable recording touch coordinates in session replay. Screenshot capture is unaffected. Set before SDK setup. Runtime changes are not supported. Default: true
PostHogSessionReplayConfig.debouncerDelay
Deprecated: Deprecated in favor of 'throttleDelay' which provides identical functionality. Will be removed in the next major release.
Debouncer delay used to reduce the number of snapshots captured and reduce performance impact This is used for capturing the view as a wireframe or screenshot The lower the number more snapshots will be captured but higher the performance impact Defaults to 1s
PostHogSessionReplayConfig.maskAllImages
Enable masking of all images to a placeholder Default: true
PostHogSessionReplayConfig.maskAllSandboxedViews
Enable masking of all sandboxed system views These may include UIImagePickerController, PHPickerViewController and CNContactPickerViewController Default: true
PostHogSessionReplayConfig.maskAllTextInputs
Enable masking of all text and text input fields Default: true
PostHogSessionReplayConfig.maskPhotoLibraryImages
Deprecated: This property has no effect and will be removed in the next major release. To learn how to manually mask user photos please see our Privacy controls documentation: https://posthog.com/docs/session-replay/privacy?tab=iOS
Deprecated placeholder for photo-library image masking.
Discussion
This property has no effect. To manually mask user photos, see the privacy controls documentation: https://posthog.com/docs/session-replay/privacy?tab=iOS
Default: false.
PostHogSessionReplayConfig.sampleRate
Session recording sample rate, between 0.0 and 1.0.
Discussion
1.0 means every session will be recorded, 0.0 means no sessions will be recorded. Sampling is deterministic based on the session ID, so the same session will always produce the same sampling decision.
When set, takes precedence over the remote config sample rate. When nil, the remote config sample rate is used (if available), otherwise all sessions are recorded.
Values outside the 0.0–1.0 range are ignored and treated as nil.
Defaults to nil
PostHogSessionReplayConfig.screenshotMode
By default Session replay will capture all the views on the screen as a wireframe, By enabling this option, PostHog will capture the screenshot of the screen. The screenshot may contain sensitive information, use with caution. Default: false
PostHogSessionReplayConfig.screenshotModeBackgroundCapture
Schedule screenshot image capture on a background queue when screenshotMode is enabled.
Discussion
Warning: Enabling this option will trigger Main Thread Checker warnings and may briefly freeze the app the first time a screenshot is captured. Consider disabling Main Thread Checker in your scheme’s run diagnostics when enabling this.
Experimental. Default: false
PostHogSessionReplayConfig.screenshotScale
Resolution of screenshotMode screenshots, as a multiplier of the screen’s native resolution.
Discussion
-
nil: one pixel per point on every device, so a 402×874 pt screen uploads 402×874 pixels. -
A value: that fraction of native resolution. On a 3x device,
1.0uploads 1206×2622 pixels (native) and0.5uploads 603×1311 (1.5 pixels per point).
Values are clamped to 0.1…1.0, and NaN or infinite values reset it to nil. The replay’s viewport in points is unchanged. Does not affect wireframe mode or compression quality. Exposed as NSNumber so Objective-C can leave it unset.
Experimental. Default: nil (one pixel per point)
PostHogSessionReplayConfig.throttleDelay
Throttle delay used to reduce the number of snapshots captured and reduce performance impact This is used for capturing the view as a wireframe or screenshot The lower the number more snapshots will be captured but higher the performance impact Defaults to 1s
Discussion
Note: Previously debouncerDelay
PostHogSessionReplayConsoleLogConfig
Configuration for console log capture inside session replay recordings.
Overview
Used when PostHogSessionReplayConfig.captureLogs is enabled.
PostHogSessionReplayConsoleLogConfig.logSanitizer
Block to process and format captured console output for session replay.
Parameters
output: The raw console output to process.
Return Value
A PostHogLogEntry to capture, or nil to skip the log output.
Discussion
This block is called whenever console output is captured. It allows you to:
-
Filter or modify log messages before they are sent to session replay
-
Determine the appropriate log level (info/warn/error) for each message
-
Format, sanitize, or skip log messages (e.g. remove sensitive data or PII)
The default implementation:
-
Detect log level (best effort)
-
Process OSLog messages to remove metadata
PostHogSessionReplayConsoleLogConfig.minLogLevel
The minimum log level to capture in session replay. Only log messages with this level or higher will be captured. For example, if set to .warn:
Discussion
-
.errormessages will be captured -
.warnmessages will be captured -
.infomessages will be skipped
Defaults to .error to minimize noise in session replays.
PostHogStorageManager
Manages persisted identity metadata for a PostHog SDK instance.
Overview
Warning: This class is public for backwards compatibility, but is intended for SDK-internal use only. Application code should use
PostHogSDKidentity APIs instead of interacting with storage directly.
PostHogStorageManager.getAnonymousId()
Returns the persisted anonymous ID, creating one if needed.
Return Value
The anonymous ID for this install.
PostHogStorageManager.getDeviceId()
Returns the stable device identifier used for device-level feature flag bucketing.
Return Value
The stable device ID for this install.
Discussion
This ID persists across identify() and reset() calls, only changing on a fresh app install or manual cache clearing.
PostHogStorageManager.getDistinctId()
Returns the persisted distinct ID, falling back to the anonymous ID.
Return Value
The current distinct ID.
PostHogStorageManager.isIdentified()
Returns whether the current distinct ID is identified.
Return Value
true after a successful identify flow, otherwise false.
PostHogStorageManager.isPersonProcessing()
Returns whether person profile processing has been enabled locally.
Return Value
true when identified/person processing has been activated.
PostHogStorageManager.reset(keepAnonymousId:_:)
Clears cached identity metadata and optionally removes persisted values.
Parameters
keepAnonymousId: Whether to keep the current anonymous ID cached and persisted.resetStorage: Whether to remove values from the backing store as well as memory.
PostHogStorageManager.setAnonymousId(_:)
Persists an anonymous ID.
Parameters
id: Anonymous ID to store.
PostHogStorageManager.setDistinctId(_:)
Persists the current distinct ID.
Parameters
id: Distinct ID to store.
PostHogStorageManager.setIdentified(_:)
Persists whether the current distinct ID is identified.
Parameters
isIdentified: New identified state.
PostHogStorageManager.setPersonProcessing(_:)
Persists whether person profile processing is enabled locally.
Parameters
enable: New person-processing state.
PostHogSurveyResponse
A model representing a user’s response to a survey question
PostHogSurveyResponse.linkClicked
Whether a link was clicked (for link questions)
PostHogSurveyResponse.ratingValue
The numeric rating value (for rating questions)
PostHogSurveyResponse.selectedOptions
The selected options (for multiple or single choice questions)
PostHogSurveyResponse.textValue
The text response (for open questions)
PostHogSurveyResponse.type
The response kind: link, rating, open-ended, single-choice, or multiple-choice.
PostHogSurveyResponse.link(_:)
Creates a response for a link question.
Parameters
clicked: Whether the link was clicked.
Return Value
A response with type .link and linkClicked populated.
PostHogSurveyResponse.multipleChoice(_:)
Creates a response for a multiple-choice question.
Parameters
multipleChoice: The selected options.
Return Value
A response with type .multipleChoice and selectedOptions populated.
PostHogSurveyResponse.openEnded(_:)
Creates a response for an open-ended question.
Parameters
openEnded: The text response.
Return Value
A response with type .openEnded and textValue populated.
PostHogSurveyResponse.rating(_:)
Creates a response for a rating question.
Parameters
rating: The selected rating value.
Return Value
A response with type .rating and ratingValue populated.
PostHogSurveyResponse.singleChoice(_:)
Creates a response for a single-choice question.
Parameters
singleChoice: The selected option.
Return Value
A response with type .singleChoice and selectedOptions containing the option when non-nil.
PostHogSurveysConfig
Configuration for mobile survey rendering.
Overview
Mutate fields on PostHogConfig.surveysConfig before SDK setup to customize survey UI, lifecycle handling, or localization.
PostHogSurveysConfig.overrideDisplayLanguage
Optional explicit override for the language used when rendering surveys.
Discussion
When set, surveys with matching entries in translations will be rendered in this language regardless of the device locale or any language person property.
Format: a language tag such as "fr", "pt-BR", "zh-CN". Matching is case-insensitive and falls back to the base language (e.g. "pt" if "pt-BR" is requested but only "pt" is provided).
Blank or nil values are treated as unset.
Default: nil.
PostHogSurveysConfig.surveysDelegate
Delegate responsible for managing survey presentation in your app. Handles survey rendering, response collection, and lifecycle events. You can provide your own delegate for a custom survey presentation.
Discussion
Defaults to PostHogSurveysDefaultDelegate which provides a standard survey UI.
PostHogPropertiesSanitizer
Protocol to sanitize the event properties
PostHogPropertiesSanitizer.sanitize(_:)
Sanitizes the event properties
Parameters
properties: The event properties to sanitize
Return Value
The sanitized properties
Discussion
Note:
inoutcannot be used in Swift protocols, so clone the properties before mutating them.
PostHogSurveysDelegate
Delegate used by the SDK to present surveys and receive survey lifecycle callbacks.
PostHogSurveysDelegate.supportsSurveyResume
Whether this delegate can resume unfinished surveys. Defaults to false when omitted.
Discussion
Return true only if the renderer starts at survey.initialQuestionIndex. The SDK restores the saved answers and submission ID for that attempt. Delegates that omit this property or return false start a fresh attempt at question 0.
For example, a renderer that supports the restored position can opt in with:
PostHogSurveysDelegate.cleanupSurveys()
Called when surveys are stopped to clean up any UI elements and reset the survey display state. This method should handle the dismissal of any active surveys and cleanup of associated resources.
PostHogSurveysDelegate.renderSurvey(_:onSurveyShown:onSurveyResponse:onSurveyClosed:)
Called when an activated PostHog survey needs to be rendered on the app’s UI Delegates that opt in through supportsSurveyResume must start at survey.initialQuestionIndex to resume an unfinished survey.
Parameters
survey: The survey to be displayed to the useronSurveyShown: To be called when the survey is successfully displayed to the user.onSurveyResponse: Call when the user submits a response to a question; use the returned state to advance or complete the survey.onSurveyClosed: To be called when the survey is dismissed
PostHogSurveysDelegate.updateSurvey(_:)
Called when the content of the currently displayed survey changes without restarting it, for example when the user’s language is updated and a new translation becomes available.
Parameters
survey: The survey with refreshed (e.g. re-translated) content. Itsidmatches the survey passed torenderSurvey.
Discussion
Implementations should update the on-screen survey in place — preserving the current question, progress, and any in-progress answers — rather than presenting it again. Optional: delegates that don’t support live updates can omit it and the survey simply keeps the language it was first rendered with.
Always delivered on the main thread. May arrive before the survey is visibly shown — e.g. while a display delay (surveyPopupDelaySeconds) is still pending — so a delegate that defers presentation must also apply the update to its pending survey, otherwise the update is dropped and the survey shows the language it was first resolved with.
BeforeSendBlock
Callback invoked before an event is persisted or sent.
Parameters
event: The event about to be queued.
Return Value
The event to queue, or nil to drop it.
Discussion
Return the event (mutated or unchanged) to continue processing, or nil to drop it. Blocks run synchronously on the capture caller’s thread and compose in registration order.
OnPostHogSurveyClosed
To be called when a survey is dismissed
Parameters
survey: The survey that was closed
OnPostHogSurveyResponse
To be called when a user responds to a survey question
Parameters
survey: The current survey being displayedindex: The index of the question being answeredresponse: The user’s response to the question
Return Value
The next survey state, or nil if the attempt is no longer valid. The built-in renderer closes an invalidated survey.
OnPostHogSurveyShown
To be called when a survey is successfully shown to the user
Parameters
survey: The survey that was displayed
PostHogBeforeSendLogBlock
A beforeSend callback gets one chance to mutate or drop a log record before it is enqueued. Returning nil drops the record; mutating the record’s body to an empty string also drops it. Multiple blocks compose left-to-right; if any returns nil, later blocks are skipped. Runs synchronously on the thread that called captureLog.
Parameters
record: The log record about to be queued.
Return Value
The record to queue, or nil to drop it.
PostHogCompression
How the SDK compresses request bodies before sending them to the PostHog API.
PostHogCompression.PostHogCompression.gzip
Gzip request bodies. If gzipping fails on device, the body is sent uncompressed.
PostHogCompression.PostHogCompression.none
Send request bodies uncompressed, with no Content-Encoding header.
PostHogDisplaySurveyRatingType
Type of rating display for survey rating questions
PostHogDisplaySurveyRatingType.PostHogDisplaySurveyRatingType.emoji
Display emoji rating options
PostHogDisplaySurveyRatingType.PostHogDisplaySurveyRatingType.number
Display numeric rating options
PostHogDisplaySurveyTextContentType
Content type for text-based survey elements
PostHogDisplaySurveyTextContentType.PostHogDisplaySurveyTextContentType.html
Content should be rendered as HTML
PostHogDisplaySurveyTextContentType.PostHogDisplaySurveyTextContentType.text
Content should be rendered as plain text
PostHogLogLevel
The severity level of a console log entry.
Overview
Used to categorize logs by their severity in session replay.
PostHogLogLevel.PostHogLogLevel.error
Error messages indicating failures or critical issues
PostHogLogLevel.PostHogLogLevel.info
Informational messages, debugging output, and general logs
PostHogLogLevel.PostHogLogLevel.warn
Warning messages indicating potential issues or deprecation notices
PostHogLogSeverity
Severity level for a captured log record sent to PostHog’s logs ingestion.
Overview
Cases are declared in severity order so >= comparisons on the raw value give the expected result from both Swift and ObjC. ObjC consumers can safely write if (severity >= PostHogLogSeverityWarn) { ... } when severity is a PostHogLogSeverity value.
Maps to OpenTelemetry severity numbers (TRACE=1, DEBUG=5, INFO=9, WARN=13, ERROR=17, FATAL=21) for the OTLP wire format.
PostHogLogSeverity.PostHogLogSeverity.debug
Diagnostic information useful while debugging.
PostHogLogSeverity.PostHogLogSeverity.error
Error messages indicating failures or critical issues.
PostHogLogSeverity.PostHogLogSeverity.fatal
An unrecoverable failure; the app likely cannot continue.
PostHogLogSeverity.PostHogLogSeverity.info
Informational messages and general logs.
PostHogLogSeverity.PostHogLogSeverity.trace
Finest-grained tracing detail.
PostHogLogSeverity.PostHogLogSeverity.warn
Warning messages indicating potential issues or deprecation notices.
PostHogPersonProfiles
Determines the behavior for processing user profiles.
Overview
-
never: We won’t process persons for any event. This means that anonymous users will not be merged once they sign up or login, so you lose the ability to create funnels that track users from anonymous to identified. All events (including$identify) will be sent with$process_person_profile: False. -
always: We will process persons data for all events. -
identifiedOnly: (default): we will only process persons when you callidentify,alias, andgroup, Anonymous users won’t get person profiles.
PostHogPersonProfiles.PostHogPersonProfiles.always
Always process person profiles for all events.
PostHogPersonProfiles.PostHogPersonProfiles.identifiedOnly
Process person profiles only after identify, alias, or group creates one.
PostHogPersonProfiles.PostHogPersonProfiles.never
Never process person profiles. All events are sent with $process_person_profile: false.
PostHogSurveyResponseType
Type of response submitted for a survey question.
PostHogSurveyResponseType.PostHogSurveyResponseType.link
Response for a link question.
PostHogSurveyResponseType.PostHogSurveyResponseType.multipleChoice
Response for a multiple-choice question.
PostHogSurveyResponseType.PostHogSurveyResponseType.openEnded
Response for an open-ended text question.
PostHogSurveyResponseType.PostHogSurveyResponseType.rating
Response for a rating question.
PostHogSurveyResponseType.PostHogSurveyResponseType.singleChoice
Response for a single-choice question.





