PostHog iOS SDK 4.x (experimental)

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

PostHog 4.x is published with Swift Package Manager only. In Xcode, choose File > Add Package Dependencies… and enter https://github.com/PostHog/posthog-ios, or add it to your Package.swift:

Swift
dependencies: [
.package(url: "https://github.com/PostHog/posthog-ios.git", from: "4.0.0")
]

Initialize

Call setup once, as early as possible in app startup.

Swift
import PostHog
let config = PostHogConfig(projectToken: "<ph_project_token>", host: "https://us.i.posthog.com")
PostHogSDK.shared.setup(config)

Capture an event

Swift
PostHogSDK.shared.capture("button_clicked", properties: ["plan": "pro"])

Call identify to link events to a user:

Swift
PostHogSDK.shared.identify("user_123", userProperties: ["email": "max@example.com"])

Shut down

Events are sent in batches. Call flush() to send queued events now, or close() to shut the SDK down.

Swift
PostHogSDK.shared.close()

Setup

PostHogSDK.setup(_:)

Swift
@objc func setup(_ config: PostHogConfig)

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(_:)

Swift
@objc static func with(_ config: PostHogConfig) -> PostHogSDK

Creates and sets up an additional SDK instance.

Parameters

  • config: Configuration for the new instance.

Return Value

A configured PostHogSDK instance.

Capture

PostHogSDK.capture(_:)

Swift
@objc func capture(_ event: String)

Captures a custom event for the current user.

Parameters

  • event: Event name to capture.

PostHogSDK.capture(_:distinctId:properties:userProperties:userPropertiesSetOnce:groups:)

Swift
@objc(captureWithEvent:distinctId:properties:userProperties:userPropertiesSetOnce:groups:) func capture(_ event: String, distinctId: String? = nil, properties: [String : Any]? = nil, userProperties: [String : Any]? = nil, userPropertiesSetOnce: [String : Any]? = nil, groups: [String : String]? = nil)

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 when nil, empty or whitespace-only.
  • 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:options:)

Swift
@objc(captureWithEvent:distinctId:properties:userProperties:userPropertiesSetOnce:groups:timestamp:options:) func capture(_ event: String, distinctId: String? = nil, properties: [String : Any]? = nil, userProperties: [String : Any]? = nil, userPropertiesSetOnce: [String : Any]? = nil, groups: [String : String]? = nil, timestamp: Date? = nil, options: [String : Any]? = nil)

Captures a custom event for an explicit distinct ID, timestamp and options.

Parameters

  • event: Event name to capture.
  • distinctId: Optional distinct ID override. Defaults to the current SDK distinct ID when nil, empty or whitespace-only.
  • 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.
  • options: Optional settings that tell PostHog how to process this event, sent apart from its properties. Known keys: - process_person_profile (Bool): whether the event creates or updates a person profile. Defaults to whether the SDK currently processes person profiles for this user (see personProfiles). - cookieless_mode (Bool): process the event in cookieless mode. - disable_skew_correction (Bool): keep timestamp as sent, without correcting for device clock skew. - product_tour_id (String): the product tour the event belongs to. These replace the $process_person_profile, $cookieless_mode, $ignore_sent_at and $product_tour_id properties. Those properties still work: they are removed from the event’s properties and used as the option, unless you set that option here. A $process_person_profile property you pass or register overrides the SDK’s default. Other keys are sent unchanged and ignored by PostHog. PostHog drops an event whose option value it can’t read. beforeSend can change them through PostHogEvent.options.

PostHogSDK.capture(_:properties:)

Swift
@objc(captureWithEvent:properties:) func capture(_ event: String, properties: [String : Any]? = nil)

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:)

Swift
@objc(captureWithEvent:properties:userProperties:) func capture(_ event: String, properties: [String : Any]? = nil, userProperties: [String : Any]? = nil)

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:)

Swift
@objc(captureWithEvent:properties:userProperties:userPropertiesSetOnce:) func capture(_ event: String, properties: [String : Any]? = nil, userProperties: [String : Any]? = nil, userPropertiesSetOnce: [String : Any]? = nil)

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:)

Swift
@objc(captureWithEvent:properties:userProperties:userPropertiesSetOnce:groups:) func capture(_ event: String, properties: [String : Any]? = nil, userProperties: [String : Any]? = nil, userPropertiesSetOnce: [String : Any]? = nil, groups: [String : String]? = nil)

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(_:)

Swift
@objc func identify(_ distinctId: String)

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:)

Swift
@objc(identifyWithDistinctId:userProperties:) func identify(_ distinctId: String, userProperties: [String : Any]? = nil)

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:options:)

Swift
@objc(identifyWithDistinctId:userProperties:userPropertiesSetOnce:options:) func identify(_ distinctId: String, userProperties: [String : Any]? = nil, userPropertiesSetOnce: [String : Any]? = nil, options: [String : Any]? = nil)

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.
  • options: Optional settings that tell PostHog how to process the $identify or $set event it sends, sent apart from its properties. Known keys are process_person_profile (Bool), cookieless_mode (Bool), disable_skew_correction (Bool) and product_tour_id (String), as described on capture(_:distinctId:properties:userProperties:userPropertiesSetOnce:groups:timestamp:options:). An option wins over its legacy $process_person_profile, $cookieless_mode, $ignore_sent_at or $product_tour_id property. beforeSend can change them through PostHogEvent.options.

Logs

PostHogSDK.logger

Swift
@objc var logger: PostHogLogger? { get }

Logger facade exposing trace/debug/info/warn/error/fatal(_:attributes:). nil before setup(_:) is called.

PostHogSDK.captureLog(_:)

Swift
@objc(captureLogWithBody:) func captureLog(_ body: String)

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:)

Swift
@objc(captureLogWithBody:level:) func captureLog(_ body: String, level: PostHogLogSeverity)

Capture a structured log record at the given severity.

Parameters

  • body: The log message. Required and non-empty.
  • level: Severity. Use .trace/.debug for diagnostic detail, .info for regular events, .warn/.error/.fatal for problems.

PostHogSDK.captureLog(_:level:attributes:)

Swift
@objc(captureLogWithBody:level:attributes:) func captureLog(_ body: String, level: PostHogLogSeverity, attributes: [String : Any]?)

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
func captureLog(_ body: String, level: PostHogLogSeverity = .info, attributes: [String : Any]? = nil, traceId: String? = nil, spanId: String? = nil, traceFlags: Int? = nil)

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.
Swift
@objc(captureLogWithBody:level:attributes:traceId:spanId:traceFlags:) func captureLog(_ body: String, level: PostHogLogSeverity, attributes: [String : Any]?, traceId: String?, spanId: String?, traceFlags: NSNumber?)

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 the sampled flag). nil omits the field on the wire; 0 emits an explicit zero.

Alias

PostHogSDK.alias(_:)

Swift
@objc func alias(_ alias: String)

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.

PostHogSDK.alias(_:options:)

Swift
@objc(alias:options:) func alias(_ alias: String, options: [String : Any]? = nil)

Assigns an additional distinct ID to the current user.

Parameters

  • alias: The additional distinct ID to associate with the current user.
  • options: Optional settings that tell PostHog how to process the $create_alias event, sent apart from its properties. Known keys are process_person_profile (Bool), cookieless_mode (Bool), disable_skew_correction (Bool) and product_tour_id (String), as described on capture(_:distinctId:properties:userProperties:userPropertiesSetOnce:groups:timestamp:options:). An option wins over its legacy $process_person_profile, $cookieless_mode, $ignore_sent_at or $product_tour_id property. beforeSend can change them through PostHogEvent.options.

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 AI

PostHogSDK.captureAi(_:distinctId:properties:userProperties:userPropertiesSetOnce:groups:timestamp:options:)

Swift
@discardableResult @objc(captureAiWithEvent:distinctId:properties:userProperties:userPropertiesSetOnce:groups:timestamp:options:) func captureAi(_ event: String, distinctId: String? = nil, properties: [String : Any]? = nil, userProperties: [String : Any]? = nil, userPropertiesSetOnce: [String : Any]? = nil, groups: [String : String]? = nil, timestamp: Date? = nil, options: [String : Any]? = nil) -> String?

Captures an AI observability event, such as $ai_generation, $ai_span, $ai_trace or $ai_embedding, and sends it to PostHog’s AI endpoint, which accepts much larger events than capture.

Parameters

  • event: AI event name, such as $ai_generation.
  • 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.
  • options: Optional settings that tell PostHog how to process this event. Same keys as capture’s options.

Return Value

The event’s UUID, or nil if the event wasn’t queued: for example, the SDK is opted out or disabled, its name is empty, beforeSend dropped it, or it’s over captureAiMaxEventBytes.

Discussion

Takes the same arguments as capture(_:distinctId:properties:userProperties:userPropertiesSetOnce:groups:timestamp:options:) and goes through the same beforeSend hooks. The event is queued on disk separately from other events and sent unchanged: the SDK doesn’t redact or truncate prompts, outputs or media. An event over captureAiMaxEventBytes (8 MiB plus 64 KiB by default) is dropped. PostHog drops an event sent here whose name doesn’t start with $ai_, and the SDK logs a debug message when it’s given one. capture never sends events here, even ones named $ai_*.

AI events use flushAt, maxBatchSize and flushIntervalSeconds from PostHogConfig, like other events, and captureAiCompression, captureAiMaxQueueSize and captureAiTimeout instead of compression, maxQueueSize and the 10-second timeout. These limits are fixed:

  • Requests carry up to about 5 MiB of events, and the SDK sends as soon as that much is queued.

  • Up to 50 MiB of AI events are kept on disk. Beyond that, the oldest are dropped.

Capture exception

PostHogSDK.captureException(_:)

Swift
@objc(captureExceptionWithNSException:) func captureException(_ exception: NSException)

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.

Swift
@objc(captureExceptionWithError:) func captureException(_ error: Error)

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:options:)

Swift
@objc(captureExceptionWithNSException:properties:options:) func captureException(_ exception: NSException, properties: [String : Any]? = nil, options: [String : Any]? = nil)

Capture an NSException

Parameters

  • exception: The NSException to capture
  • properties: Optional additional properties to attach to the event
  • options: Optional settings that tell PostHog how to process the $exception event, sent apart from its properties. Known keys are process_person_profile (Bool), cookieless_mode (Bool), disable_skew_correction (Bool) and product_tour_id (String), as described on capture(_:distinctId:properties:userProperties:userPropertiesSetOnce:groups:timestamp:options:). An option wins over its legacy $process_person_profile, $cookieless_mode, $ignore_sent_at or $product_tour_id property. beforeSend can change them through PostHogEvent.options.

Discussion

Captures an NSException as a $exception event with full stack trace. This is useful for Objective-C code that uses NSException.

Example:

objc
@try {
[self riskyOperation];
} @catch (NSException *exception) {
[[PostHogSDK shared] captureExceptionWithNSException:exception properties:nil];
}
Swift
@objc(captureExceptionWithError:properties:options:) func captureException(_ error: Error, properties: [String : Any]? = nil, options: [String : Any]? = nil)

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
  • options: Optional settings that tell PostHog how to process the $exception event, sent apart from its properties. Known keys are process_person_profile (Bool), cookieless_mode (Bool), disable_skew_correction (Bool) and product_tour_id (String), as described on capture(_:distinctId:properties:userProperties:userPropertiesSetOnce:groups:timestamp:options:). An option wins over its legacy $process_person_profile, $cookieless_mode, $ignore_sent_at or $product_tour_id property. beforeSend can change them through PostHogEvent.options.

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:

Swift
do {
try FileManager.default.removeItem(at: badFileUrl)
} catch {
PostHogSDK.shared.captureException(error)
}

Debug

PostHogSDK.debug(_:)

Swift
@objc func debug(_ enabled: Bool = true)

Enables or disables SDK debug logging at runtime.

Parameters

  • enabled: Pass true to enable verbose logs or false to disable them.

Exception steps

PostHogSDK.addExceptionStep(_:)

Swift
@objc(addExceptionStep:) func addExceptionStep(_ message: String)

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:)

Swift
@objc(addExceptionStep:properties:) func addExceptionStep(_ message: String, properties: [String : Any]? = nil)

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:

Swift
PostHogSDK.shared.addExceptionStep("User tapped Checkout", properties: ["screen": "cart"])

Flush

PostHogSDK.flush()

Swift
@objc func flush()

Trigger an immediate flush of every queue — events, AI events, session-replay snapshots, and structured logs.

Get anonymous ID

PostHogSDK.getAnonymousId()

Swift
@objc func getAnonymousId() -> String

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()

Swift
@objc func getDistinctId() -> String

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(_:)

Swift
@objc func getFeatureFlag(_ key: String) -> Any?

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:)

Swift
@objc(getFeatureFlagWithKey:sendFeatureFlagEvent:) func getFeatureFlag(_ key: String, sendFeatureFlagEvent: Bool) -> Any?

Returns a feature flag value and optionally captures a usage event.

Parameters

  • key: The feature flag key.
  • sendFeatureFlagEvent: Whether to capture $feature_flag_called for this lookup.

Return Value

Bool, String, or nil if the flag is unavailable.

Get feature flag result

PostHogSDK.getFeatureFlagResult(_:)

Swift
@objc func getFeatureFlagResult(_ key: String) -> PostHogFeatureFlagResult?

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:)

Swift
@objc(getFeatureFlagResultWithKey:sendFeatureFlagEvent:) func getFeatureFlagResult(_ key: String, sendFeatureFlagEvent: Bool) -> PostHogFeatureFlagResult?

Returns the feature flag result and optionally captures a usage event.

Parameters

  • key: The feature flag key.
  • sendFeatureFlagEvent: Whether to capture $feature_flag_called for this lookup.

Return Value

A result containing enabled state, variant, and payload, or nil if unavailable.

Get feature flags

PostHogSDK.getAllFeatureFlags()

Swift
@objc func getAllFeatureFlags() -> [PostHogFeatureFlagResult]?

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.

Swift
for flag in PostHogSDK.shared.getAllFeatureFlags() ?? [] {
print(flag.key, flag.enabled, flag.payload as Any)
}

Get session ID

PostHogSDK.getSessionId()

Swift
@objc func getSessionId() -> String?

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:)

Swift
@objc(groupWithType:key:) func group(type: String, key: String)

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:options:)

Swift
@objc(groupWithType:key:groupProperties:options:) func group(type: String, key: String, groupProperties: [String : Any]? = nil, options: [String : Any]? = nil)

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.
  • options: Optional settings that tell PostHog how to process the $groupidentify event, sent apart from its properties. Known keys are process_person_profile (Bool), cookieless_mode (Bool), disable_skew_correction (Bool) and product_tour_id (String), as described on capture(_:distinctId:properties:userProperties:userPropertiesSetOnce:groups:timestamp:options:). An option wins over its legacy $process_person_profile, $cookieless_mode, $ignore_sent_at or $product_tour_id property. beforeSend can change them through PostHogEvent.options.

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(_:)

Swift
@objc func isFeatureEnabled(_ key: String) -> Bool

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 non-empty variant string is returned.

PostHogSDK.isFeatureEnabled(_:defaultValue:)

Swift
@objc(isFeatureEnabledWithKey:defaultValue:) func isFeatureEnabled(_ key: String, defaultValue: Bool) -> Bool

Returns whether a feature flag is enabled, or a default you supply when the flag has no value.

Parameters

  • key: The feature flag key.
  • defaultValue: The value to return when the flag has no value.

Return Value

true when the flag is enabled, false when it is disabled, otherwise defaultValue.

Discussion

defaultValue has no implicit value; isFeatureEnabled(_:) is the equivalent of passing false.

The default is returned when flags have not loaded yet, the flags request failed with nothing cached, the loaded flags have no flag with this key, or the SDK is not set up. A flag that has a value always wins, including false and variant strings, and an empty variant counts as false. $feature_flag_called follows PostHogConfig.sendFeatureFlagEvent and never reports the default as the flag’s value.

Swift
if PostHogSDK.shared.isFeatureEnabled("new-checkout", defaultValue: true) {
showNewCheckout()
}

PostHogSDK.isFeatureEnabled(_:defaultValue:sendFeatureFlagEvent:)

Swift
@objc(isFeatureEnabledWithKey:defaultValue:sendFeatureFlagEvent:) func isFeatureEnabled(_ key: String, defaultValue: Bool, sendFeatureFlagEvent: Bool) -> Bool

Returns whether a feature flag is enabled, or a default you supply when the flag has no value, and optionally captures a usage event.

Parameters

  • key: The feature flag key.
  • defaultValue: The value to return when the flag has no value.
  • sendFeatureFlagEvent: Whether to capture $feature_flag_called for this lookup.

Return Value

true when the flag is enabled, false when it is disabled, otherwise defaultValue.

Discussion

defaultValue has no implicit value, and sendFeatureFlagEvent overrides PostHogConfig.sendFeatureFlagEvent for this call.

The default is returned when flags have not loaded yet, the flags request failed with nothing cached, the loaded flags have no flag with this key, or the SDK is not set up. A flag that has a value always wins, including false and variant strings, and an empty variant counts as false. $feature_flag_called never reports the default as the flag’s value.

Swift
let enabled = PostHogSDK.shared.isFeatureEnabled(
"new-checkout",
defaultValue: true,
sendFeatureFlagEvent: false
)

PostHogSDK.isFeatureEnabled(_:sendFeatureFlagEvent:)

Swift
@objc(isFeatureEnabledWithKey:sendFeatureFlagEvent:) func isFeatureEnabled(_ key: String, sendFeatureFlagEvent: Bool) -> Bool

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_called for this lookup.

Return Value

true when the flag is enabled, otherwise false.

Is opt out

PostHogSDK.isOptOut()

Swift
@objc func isOptOut() -> Bool

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()

Swift
@objc func isSessionReplayActive() -> Bool

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(_:)

Swift
@discardableResult @objc(onFeatureFlags:) func onFeatureFlags(_ callback: @escaping (PostHogFeatureFlagsLoaded) -> Void) -> PostHogFeatureFlagsSubscription

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.

Opt in

PostHogSDK.optIn()

Swift
@objc func 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()

Swift
@objc func 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(_:)

Swift
@objc(registerProperties:) func register(_ properties: [String : Any])

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()

Swift
@objc func reloadFeatureFlags()

Reloads feature flags for the current user and group context.

PostHogSDK.reloadFeatureFlags(_:)

Swift
@objc(reloadFeatureFlagsWithCallback:) func reloadFeatureFlags(_ callback: @escaping (PostHogFeatureFlagsLoaded) -> Void)

Reloads feature flags and invokes a callback with the result when finished.

Parameters

  • callback: Invoked when the reload finishes, possibly on a background thread. If the request fails, errorsLoading is true and the flags are the last known ones. If the reload is skipped because the SDK isn’t set up, it’s invoked right away with no flags and errorsLoading set to true. To update UI or other main-actor state, hop to the main actor, for example with Task { @MainActor in ... }.

Discussion

Swift
PostHogSDK.shared.reloadFeatureFlags { result in
if result.errorsLoading {
// The reload failed. result.variants holds the last known flags.
}
}

Reset

PostHogSDK.reset()

Swift
@objc func 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()

Swift
@objc func resetGroupPropertiesForFlags()

Clears all group properties for feature flag evaluation.

Example Usage

Swift
// Clear all group properties
PostHogSDK.shared.resetGroupPropertiesForFlags()

PostHogSDK.resetGroupPropertiesForFlags(_:)

Swift
@objc(resetGroupPropertiesForFlagsWithGroupType:) func resetGroupPropertiesForFlags(_ groupType: String)

Clears group properties for feature flag evaluation for a specific group type.

Parameters

  • groupType: The group type to clear properties for

Example Usage

Swift
// Clear properties for specific group type
PostHogSDK.shared.resetGroupPropertiesForFlags("organization")

PostHogSDK.resetGroupPropertiesForFlags(_:reloadFeatureFlags:)

Swift
@objc(resetGroupPropertiesForFlagsWithGroupType:reloadFeatureFlags:) func resetGroupPropertiesForFlags(_ groupType: String, reloadFeatureFlags: Bool = true)

Clears group properties for feature flag evaluation for a specific group type.

Parameters

  • groupType: The group type to clear properties for
  • reloadFeatureFlags: Whether to automatically reload feature flags after clearing properties for this group type.

Example Usage

Swift
// Clear properties for specific group type
PostHogSDK.shared.resetGroupPropertiesForFlags("organization", reloadFeatureFlags: true)

PostHogSDK.resetGroupPropertiesForFlags(reloadFeatureFlags:)

Swift
@objc(resetGroupPropertiesForFlagsWithReloadFeatureFlags:) func resetGroupPropertiesForFlags(reloadFeatureFlags: Bool = true)

Clears all group properties for feature flag evaluation.

Parameters

  • reloadFeatureFlags: Whether to automatically reload feature flags after clearing all group properties.

Example Usage

Swift
// Clear all group properties
PostHogSDK.shared.resetGroupPropertiesForFlags(reloadFeatureFlags: true)

Reset person properties for flags

PostHogSDK.resetPersonPropertiesForFlags()

Swift
@objc func 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

Swift
// Clear all locally set person properties for flags
PostHogSDK.shared.resetPersonPropertiesForFlags()
// Feature flags will now use only server-side properties
let flagValue = PostHogSDK.shared.isFeatureEnabled("feature")

PostHogSDK.resetPersonPropertiesForFlags(reloadFeatureFlags:)

Swift
@objc(resetPersonPropertiesForFlagsWithReloadFeatureFlags:) func resetPersonPropertiesForFlags(reloadFeatureFlags: Bool = true)

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

Swift
// Clear all locally set person properties for flags
PostHogSDK.shared.resetPersonPropertiesForFlags(reloadFeatureFlags: true)
// Feature flags will now use only server-side properties
let flagValue = PostHogSDK.shared.isFeatureEnabled("feature")

Screen

PostHogSDK.screen(_:)

Swift
@objc func screen(_ screenTitle: String)

Records a screen view by capturing a $screen event.

Parameters

  • screenTitle: The screen name to record.

PostHogSDK.screen(_:properties:options:)

Swift
@objc(screenWithTitle:properties:options:) func screen(_ screenTitle: String, properties: [String : Any]? = nil, options: [String : Any]? = nil)

Records a screen view by capturing a $screen event with screenTitle.

Parameters

  • screenTitle: The screen name to record. It takes precedence over a $screen_name key in properties.
  • properties: Additional properties to attach to this $screen event.
  • options: Optional settings that tell PostHog how to process this $screen event, sent apart from its properties. Known keys are process_person_profile (Bool), cookieless_mode (Bool), disable_skew_correction (Bool) and product_tour_id (String), as described on capture(_:distinctId:properties:userProperties:userPropertiesSetOnce:groups:timestamp:options:). An option wins over its legacy $process_person_profile, $cookieless_mode, $ignore_sent_at or $product_tour_id property. beforeSend can change them through PostHogEvent.options.

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:)

Swift
@objc(setGroupPropertiesForFlags:properties:) func setGroupPropertiesForFlags(_ groupType: String, properties: [String : Any])

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

Swift
PostHogSDK.shared.setGroupPropertiesForFlags("organization", properties: [
"plan": "enterprise",
"seats": 50,
"industry": "technology"
])

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:)

Swift
@objc(setGroupPropertiesForFlags:properties:reloadFeatureFlags:) func setGroupPropertiesForFlags(_ groupType: String, properties: [String : Any], reloadFeatureFlags: Bool = true)

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
  • reloadFeatureFlags: Whether to automatically reload feature flags after setting properties

Example Usage

Swift
// Set properties without automatically reloading flags
PostHogSDK.shared.setGroupPropertiesForFlags("organization", properties: [
"plan": "enterprise",
"seats": 50
], reloadFeatureFlags: false)
// Manually reload flags later
PostHogSDK.shared.reloadFeatureFlags()

Set person properties

PostHogSDK.setPersonProperties(userPropertiesToSet:)

Swift
@objc(setPersonPropertiesWithUserPropertiesToSet:) func setPersonProperties(userPropertiesToSet: [String : Any]?)

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:options:)

Swift
@objc(setPersonPropertiesWithUserPropertiesToSet:userPropertiesToSetOnce:options:) func setPersonProperties(userPropertiesToSet: [String : Any]?, userPropertiesToSetOnce: [String : Any]? = nil, options: [String : Any]? = nil)

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.
  • options: Optional settings that tell PostHog how to process the $set event, sent apart from its properties. Known keys are process_person_profile (Bool), cookieless_mode (Bool), disable_skew_correction (Bool) and product_tour_id (String), as described on capture(_:distinctId:properties:userProperties:userPropertiesSetOnce:groups:timestamp:options:). An option wins over its legacy $process_person_profile, $cookieless_mode, $ignore_sent_at or $product_tour_id property. beforeSend can change them through PostHogEvent.options.

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(_:)

Swift
@objc func setPersonPropertiesForFlags(_ properties: [String : Any])

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

Swift
// Set properties and automatically reload flags
PostHogSDK.shared.setPersonPropertiesForFlags([
"$app_version": "2.93.0",
"plan": "premium"
])
// Now feature flags will be evaluated with these properties
let flagValue = PostHogSDK.shared.isFeatureEnabled("new_feature")

Important: The reload is asynchronous and is not ordered against the automatic preload that PostHogConfig.preloadFeatureFlags starts at setup. See setPersonPropertiesForFlags(_: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:)

Swift
@objc(setPersonPropertiesForFlagsWithProperties:reloadFeatureFlags:) func setPersonPropertiesForFlags(_ properties: [String : Any], reloadFeatureFlags: Bool = true)

Sets person properties that will be included in feature flag evaluation requests.

Parameters

  • properties: Dictionary of person properties to include in flag evaluation
  • reloadFeatureFlags: 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

Swift
// Set properties without automatically reloading flags
PostHogSDK.shared.setPersonPropertiesForFlags([
"$app_version": "2.93.0",
"plan": "premium"
], reloadFeatureFlags: false)
// Manually reload flags later
PostHogSDK.shared.reloadFeatureFlags()

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() when PostHogConfig.preloadFeatureFlags is true (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:

Swift
PostHogSDK.shared.setPersonPropertiesForFlags(["plan": "premium"], reloadFeatureFlags: false)
PostHogSDK.shared.reloadFeatureFlags { _ in
let flagValue = PostHogSDK.shared.isFeatureEnabled("new_feature")
}

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: The reloadFeatureFlags(_:) handler runs whether or not the reload succeeded. If the request fails, errorsLoading is true and the flags you read are the previously cached ones. If the project is over its feature flag quota, errorsLoading is false but the flags are still the previously cached ones.

Shutdown

PostHogSDK.close()

Swift
@objc func close()

Shuts down this SDK instance and clears its in-memory state.

Discussion

Starts sending queued events, AI 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()

Swift
@objc(startSessionRecording) func 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 until stopSessionRecording() is called

PostHogSDK.startSessionRecording(resumeCurrent:)

Swift
@objc(startSessionRecordingWithResumeCurrent:) func startSessionRecording(resumeCurrent: Bool)

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()

Swift
@objc func 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(_:)

Swift
@objc(unregisterProperties:) func unregister(_ key: String)

Removes a previously registered super property.

Parameters

  • key: The property key to stop attaching to future events.

Autocapture

PostHogSDK.isAutocaptureActive()

Swift
@objc func isAutocaptureActive() -> Bool

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()

Swift
@objc func isRageClickActive() -> Bool

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()

Swift
@objc func getDeviceId() -> String

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()

Swift
@objc func endSession()

Ends the current analytics session.

PostHogSDK.startSession()

Swift
@objc func startSession()

Starts or resumes the current analytics session.

SDK utils

PostHogSDK.captureDeepLink(openURLContexts:)

Swift
@objc func captureDeepLink(openURLContexts: Set<UIOpenURLContext>)

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:)

Swift
@objc func captureDeepLink(url: URL)

Captures a deep link opened event for a URL.

Parameters

  • url: The URL that was opened.

PostHogSDK.captureDeepLink(url:options:)

Swift
@objc func captureDeepLink(url: URL, options: [UIApplication.OpenURLOptionsKey : Any])

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:)

Swift
@objc func captureDeepLink(urls: [URL])

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:)

Swift
@objc func captureDeepLink(userActivity: NSUserActivity)

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:)

Swift
@objc func captureFeatureInteraction(flag: String, flagVariant: String?)

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. If nil, the SDK looks up the current flag value and skips capture when no value is available.

PostHogSDK.captureFeatureView(flag:flagVariant:)

Swift
@objc func captureFeatureView(flag: String, flagVariant: String?)

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. If nil, the SDK looks up the current flag value and skips capture when no value is available.

PostHogSDK.capturePushNotificationOpened(response:)

Swift
@objc func capturePushNotificationOpened(response: UNNotificationResponse)

Manually captures a $push_notification_opened event for a notification the user tapped.

Parameters

  • response: The UNNotificationResponse received 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:)

Swift
@objc func capturePushNotificationOpened(title: String? = nil, subtitle: String? = nil, body: String? = nil, payload: [AnyHashable : Any]? = nil, action: String? = nil)

Manually captures a $push_notification_opened event from raw notification fields.

Parameters

  • title: The notification title; omitted from the event when nil or empty.
  • subtitle: The notification subtitle; omitted when nil or empty.
  • body: The notification body; omitted when nil or empty.
  • payload: The notification payload (userInfo). The keys of its posthog entry — a dictionary, or a JSON string when relayed through FCM — become $notification_<key> properties.
  • action: The action identifier for an action-button tap; leave nil for 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(_:)

Swift
@objc func registerPushNotificationToken(_ deviceToken: String)

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 a Data token via token.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:)

Swift
@objc func registerPushNotificationToken(_ deviceToken: String, appId: String?)

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, or nil to 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.setAppLanguage(_:)

Swift
@objc(setAppLanguage:) func setAppLanguage(_ language: String?)

Sets the $app_language property: the language your app displays, sent with every event.

Parameters

  • language: A BCP 47 language tag, such as de or pt-BR. Pass nil to go back to the detected language.

Discussion

Call it at startup and whenever the language changes, because the value is kept in memory only. It overrides the language the SDK detects, and survives reset().

By default the SDK sends the localization your app bundle resolved, from Bundle.main.preferredLocalizations. Use this if you translate your app some other way, such as with an in-app language setting. Compare $locale, which is the device’s preferred language.

Swift
PostHogSDK.shared.setAppLanguage("de")

PostHogSDK.unregisterPushNotificationToken()

Swift
@objc func 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

Swift
@objc static let didStartNotification: Notification.Name

Posted on the main queue after setup(_:) finishes successfully.

Discussion

The notification object is nil.

PostHogSDK.shared

Swift
@objc nonisolated(unsafe) static let shared: PostHogSDK

Shared singleton SDK instance used by most applications.

Discussion

Call setup(_:) once with a PostHogConfig before using capture APIs.

PostHogSDK.prewarmPushNotificationOpenCapture()

Swift
@objc static func 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:)

Swift
func postHogData(for request: URLRequest, delegate: (any URLSessionTaskDelegate)? = nil, postHog: PostHogSDK? = nil) async throws -> (Data, URLResponse)

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; nil performs 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:)

Swift
func postHogData(for request: URLRequest, postHog: PostHogSDK? = nil) async throws -> (Data, URLResponse)

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; nil performs 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:)

Swift
func postHogData(from url: URL, delegate: (any URLSessionTaskDelegate)? = nil, postHog: PostHogSDK? = nil) async throws -> (Data, URLResponse)

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; nil performs 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:)

Swift
func postHogData(from url: URL, postHog: PostHogSDK? = nil) async throws -> (Data, URLResponse)

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; nil performs 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:)

Swift
func postHogDownload(for request: URLRequest, delegate: (any URLSessionTaskDelegate)? = nil, postHog: PostHogSDK? = nil) async throws -> (URL, URLResponse)

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; nil performs 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:)

Swift
func postHogDownload(from url: URL, delegate: (any URLSessionTaskDelegate)? = nil, postHog: PostHogSDK? = nil) async throws -> (URL, URLResponse)

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; nil performs 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:)

Swift
func postHogDownload(resumeFrom resumeData: Data, delegate: (any URLSessionTaskDelegate)? = nil, postHog: PostHogSDK? = nil) async throws -> (URL, URLResponse)

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; nil performs 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:)

Swift
func postHogUpload(for request: URLRequest, from bodyData: Data, delegate: (any URLSessionTaskDelegate)? = nil, postHog: PostHogSDK? = nil) async throws -> (Data, URLResponse)

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; nil performs 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:)

Swift
func postHogUpload(for request: URLRequest, from bodyData: Data, postHog: PostHogSDK? = nil) async throws -> (Data, URLResponse)

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; nil performs 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:)

Swift
func postHogUpload(for request: URLRequest, fromFile fileURL: URL, delegate: (any URLSessionTaskDelegate)? = nil, postHog: PostHogSDK? = nil) async throws -> (Data, URLResponse)

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; nil performs 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:)

Swift
func postHogUpload(for request: URLRequest, fromFile fileURL: URL, postHog: PostHogSDK? = nil) async throws -> (Data, URLResponse)

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; nil performs 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(_:)

Swift
@MainActor func postHogDeepLinkListener(_ posthog: PostHogSDK? = nil) -> some View

Attach a PostHog deep link listener to this view.

Parameters

  • posthog: SDK instance to use for tracking. Defaults to PostHogSDK.shared.

Return Value

A modified view that captures supported deep link events.

Discussion

The listener forwards .onOpenURL and .onContinueUserActivity events to PostHog.

View.postHogLabel(_:)

Swift
@MainActor func postHogLabel(_ label: String?) -> some View

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
Swift
struct ContentView: View {
var body: some View {
Button("Login") {
...
}
.postHogLabel("loginButton")
}
}

View.postHogMask(_:)

Swift
@MainActor func postHogMask(_ isEnabled: Bool = true) -> some View

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:

Swift
// This view will be masked in recordings
SensitiveDataView()
.postHogMask()
// Conditionally mask based on a flag
SensitiveDataView()
.postHogMask(shouldMask)

View.postHogNoMask()

Swift
@MainActor func postHogNoMask() -> some View

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:

Swift
// This view may be accidentally masked by PostHog SDK
SomeSafeView()
// This custom view (and all its subviews) will not be masked in recordings
SomeSafeView()
.postHogNoMask()

View.postHogNoRageClick(_:)

Swift
@MainActor func postHogNoRageClick(_ isEnabled: Bool = true) -> some View

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:

Swift
// Taps on this control won't trigger rage clicks
CustomStepper()
.postHogNoRageClick()
// Conditionally opt out based on a flag
CustomStepper()
.postHogNoRageClick(shouldExclude)

View.postHogScreenView(_:_:postHog:)

Swift
@MainActor func postHogScreenView(_ screenName: String? = nil, _ properties: [String : Any]? = nil, postHog: PostHogSDK? = nil) -> some View

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 $screen event.
  • postHog: SDK instance used to send the event. Defaults to PostHogSDK.shared.

Return Value

A modified view that captures a screen view when it appears.

View.postHogViewSeen(_:_:postHog:)

Swift
@MainActor func postHogViewSeen(_ event: String, _ properties: [String : Any]? = nil, postHog: PostHogSDK? = nil) -> some View

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 to PostHogSDK.shared.

Return Value

A modified view that captures the event when it appears.

UIView.postHogLabel

Swift
@MainActor var postHogLabel: String? { get set }

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
Swift
let myView = UIView()
myView.postHogLabel = "customLabel"

Types

PostHogBootstrapConfig

Swift
@objc(PostHogBootstrapConfig) class 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()

Swift
override init()

Creates an empty bootstrap; set the properties you need before assigning it to bootstrap.

PostHogBootstrapConfig.init(anonymousId:)

Swift
@objc convenience init(anonymousId: String)

Seeds an anonymous identity: anonymousId becomes the $distinct_id for events captured before the host calls identify(...).

PostHogBootstrapConfig.init(distinctId:isIdentifiedId:)

Swift
@objc convenience init(distinctId: String, isIdentifiedId: Bool)

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:)

Swift
@objc init(distinctId: String?, isIdentifiedId: Bool = false, featureFlags: [String : Any]?, featureFlagPayloads: [String : Any]?)

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, or nil to seed no identity. Used as the anonymous ID when isIdentifiedId is false, or an already-identified user’s ID when true.
  • isIdentifiedId: Whether distinctId is an already-identified user. Defaults to false.
  • featureFlags: Flag values served until the first /flags response, or nil.
  • featureFlagPayloads: JSON payloads keyed by flag, paired with featureFlags, or nil.

PostHogBootstrapConfig.init(featureFlags:featureFlagPayloads:)

Swift
@objc convenience init(featureFlags: [String : Any], featureFlagPayloads: [String : Any]?)

Seeds feature-flag state only, without seeding identity.

PostHogBootstrapConfig.distinctId

Swift
@objc var distinctId: String?

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

Swift
@objc var featureFlagPayloads: [String : Any]?

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

Swift
@objc var featureFlags: [String : Any]?

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

Swift
@objc var isIdentifiedId: Bool

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

Swift
@objc(PostHogConfig) class 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(projectToken:)

Swift
@objc(projectToken:) init(projectToken: String)

Creates a configuration using the default PostHog host.

Parameters
  • projectToken: Your PostHog project token. Leading and trailing whitespace is trimmed.

PostHogConfig.init(projectToken:host:)

Swift
@objc(projectToken:host:) init(projectToken: String, host: String = defaultHost)

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 to defaultHost.

PostHogConfig.appGroupIdentifier

Swift
@objc var appGroupIdentifier: String?

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

Swift
@objc var bootstrap: PostHogBootstrapConfig?

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.captureAiCompression

Swift
@objc var captureAiCompression: PostHogCompression

How the SDK compresses captureAi request bodies, separately from compression.

Discussion

Default: .gzip.

PostHogConfig.captureAiMaxEventBytes

Swift
@objc var captureAiMaxEventBytes: Int

Maximum size, in bytes, of a serialized captureAi event. The SDK drops a larger event.

Discussion

Use it to lower the limit. PostHog drops AI events whose properties are over 8 MiB, so the default allows 8 MiB plus 64 KiB for the rest of the event. A larger value uses the default and logs a warning when debug is on. A value of 0 or less uses the default. Default: 8454144 (8 MiB + 64 KiB).

PostHogConfig.captureAiMaxQueueSize

Swift
@objc var captureAiMaxQueueSize: Int

Maximum number of captureAi events kept in their on-disk queue before older events are dropped.

Discussion

AI events can be megabytes, so this is lower than maxQueueSize. The queue also keeps at most 50 MiB of AI events, whatever this is set to. A value of 0 or less uses the default. Default: 100.

PostHogConfig.captureAiTimeout

Swift
@objc var captureAiTimeout: TimeInterval

How long, in seconds, a captureAi request can go without network activity before it times out.

Discussion

AI requests can carry several MB, so this is longer than for other requests, which time out after 10 seconds. A value of 0 or less uses the default. Default: 60.

PostHogConfig.captureApplicationLifecycleEvents

Swift
@objc var captureApplicationLifecycleEvents: Bool

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

Swift
@objc var captureAutocaptureElementText: Bool

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

Swift
@objc var captureElementInteractions: Bool

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

Swift
@objc var capturePushNotificationOpened: Bool

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 enableSwizzling to be true. To capture opens without swizzling, call PostHogSDK.capturePushNotificationOpened(response:) from your own userNotificationCenter(_: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

Swift
@objc var capturePushNotificationSubscriptions: Bool

Automatically register the device’s APNs token with PostHog by swizzling application(_:didRegisterForRemoteNotificationsWithDeviceToken:), so Workflows can deliver push notifications.

Discussion

Note: Requires enableSwizzling to be true. To register tokens without swizzling, call PostHogSDK.registerPushNotificationToken(_:) from your own application(_:didRegisterForRemoteNotificationsWithDeviceToken:) implementation. Registration is iOS-only in this version.

Default: true. Set to false to opt out.

PostHogConfig.captureScreenViews

Swift
@objc var captureScreenViews: Bool

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

Swift
@objc var captureSwiftUIElementInteractions: Bool

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

Swift
@objc var compression: PostHogCompression

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. captureAi requests use captureAiCompression instead.

Default: .gzip.

PostHogConfig.dataMode

Swift
@objc var dataMode: PostHogDataMode

Required network connectivity mode for flushing queued data.

Discussion

Only .wifi restricts flushing. Default: .any.

PostHogConfig.debug

Swift
@objc var debug: Bool

Enables verbose SDK diagnostic logging.

Discussion

Default: false.

PostHogConfig.disableGeoIp

Swift
@objc var disableGeoIp: Bool

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

Swift
@objc var enableSwizzling: Bool

Enable method swizzling for SDK functionality that depends on it

Discussion

When disabled, functionality that require swizzling (like autocapture, screen views, session replay) 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

Swift
@objc let errorTrackingConfig: PostHogErrorTrackingConfig

Configuration for error tracking.

Discussion

See known limitations: https://posthog.com/docs/error-tracking/installation/ios#limitations

PostHogConfig.evaluationContexts

Swift
@objc var evaluationContexts: [String]?

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:

Swift
config.evaluationContexts = ["production", "web", "checkout"]

This helps ensure feature flags are only evaluated in the appropriate contexts for your SDK instance.

Default: nil (all flags are evaluated)

PostHogConfig.featureFlagRequestMaxRetries

Swift
@objc var featureFlagRequestMaxRetries: Int

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

Swift
@objc var flushAt: Int

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

Swift
@objc var flushIntervalSeconds: TimeInterval

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

Swift
@objc var getAnonymousId: ((UUID) -> UUID)

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. The closure can be called on any thread, so it must not read main-actor state.

PostHogConfig.host

Swift
@objc let host: URL

PostHog ingestion host used for all SDK network requests.

Discussion

Defaults to PostHogConfig.defaultHost when the initializer host is empty or invalid.

PostHogConfig.logs

Swift
@objc let logs: PostHogLogsConfig

Configuration for the logs subsystem (manual captureLog capture). Mutate fields on config.logs before calling PostHogSDK.setup(_:).

PostHogConfig.maxBatchSize

Swift
@objc var maxBatchSize: Int

Maximum number of events included in a single batch request.

Discussion

Default: 50.

PostHogConfig.maxQueueSize

Swift
@objc var maxQueueSize: Int

Maximum number of events kept in the on-disk queue before older events are dropped.

Discussion

Default: 1000 (100 on tvOS).

PostHogConfig.optOut

Swift
@objc var optOut: Bool

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

Swift
@objc var personProfiles: PostHogPersonProfiles

Determines the behavior for processing user profiles.

PostHogConfig.preloadFeatureFlags

Swift
@objc var preloadFeatureFlags: Bool

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

Swift
@objc let projectToken: String

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.pushIdentityProvider

Swift
@objc var pushIdentityProvider: ((_ distinctId: String, _ appId: String, _ completion: @escaping (String?) -> Void) -> Void)?

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.pushNotificationSubscriptionMaxRetries

Swift
@objc var pushNotificationSubscriptionMaxRetries: Int

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.rageClickConfig

Swift
@objc let rageClickConfig: PostHogRageClickConfig

Rage click detection configuration.

PostHogConfig.requestHeaders

Swift
@objc var requestHeaders: [String : String]?

Custom headers to send with every request to the PostHog API. Useful for reverse-proxy setups that require authentication, e.g. an X-Proxy-Token header.

Discussion

Event capture requests always send Authorization: Bearer <projectToken>, which replaces any Authorization header set here, so authenticate your proxy with a different header. Read once when the SDK is set up; changes after setup are ignored.

PostHogConfig.reuseAnonymousId

Swift
@objc var reuseAnonymousId: Bool

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

Swift
@objc var sendFeatureFlagEvent: Bool

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

Swift
@objc var sessionReplay: Bool

Enable Recording of Session Replays for iOS

Discussion

With Swift Package Manager, this is only available with the SessionReplay package trait, which is enabled by default.

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

Swift
@objc let sessionReplayConfig: PostHogSessionReplayConfig

Session Replay configuration

Discussion

With Swift Package Manager, this is only available with the SessionReplay package trait, which is enabled by default.

PostHogConfig.setDefaultPersonProperties

Swift
@objc var setDefaultPersonProperties: Bool

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.surveys

Swift
@objc var surveys: Bool { get set }

Enable mobile surveys

Discussion

With Swift Package Manager, this is only available with the Surveys package trait, which is enabled by default.

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

Swift
@objc var surveysConfig: PostHogSurveysConfig { get set }

Configuration for mobile survey presentation and localization.

Discussion

Mutate fields on config.surveysConfig or replace this object before calling setup. With Swift Package Manager, this is only available with the Surveys package trait, which is enabled by default.

PostHogConfig.tracingHeaders

Swift
@objc var tracingHeaders: [String]?

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-ID because mobile apps do not have a per-window/tab concept

  • Existing values for these headers will be overwritten

PostHogConfig.urlSessionConfiguration

Swift
@objc var urlSessionConfiguration: URLSessionConfiguration?

Optional custom URLSessionConfiguration for network requests If not set, uses URLSessionConfiguration.default Useful for testing, proxying, or custom network configurations

PostHogConfig.setBeforeSend(_:)

Swift
func setBeforeSend(_ blocks: BeforeSendBlock...)

Replaces the event beforeSend chain with the provided blocks.

Parameters
  • blocks: Ordered callbacks that can mutate or drop events.
Swift
func setBeforeSend(_ blocks: [(PostHogEvent) -> PostHogEvent?])

Replaces the event beforeSend chain with blocks from an array typed [(PostHogEvent) -> PostHogEvent?].

Parameters
  • blocks: Ordered callbacks that can mutate or drop events.
Discussion

The blocks can run on any thread, so they must be safe to call from any thread.

Swift
func setBeforeSend(_ blocks: [BeforeSendBlock])

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

Swift
static let defaultHost: String

Default PostHog ingestion host for US Cloud projects.

Discussion

Use "https://eu.i.posthog.com" for EU Cloud projects.

PostHogConfig.PostHogConfig.PostHogDataMode

Swift
@frozen @objc(PostHogDataMode) enum PostHogDataMode

Network connectivity mode required before queued data may be flushed.

PostHogConsoleLogEntry

Swift
@objc class PostHogConsoleLogEntry

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.

PostHogConsoleLogEntry.init(level:message:)

Swift
@objc init(level: PostHogConsoleLogLevel, message: String)

Creates a new console log entry.

Parameters
  • level: The severity level of the log entry
  • message: The processed log message content

PostHogConsoleLogEntry.level

Swift
@objc let level: PostHogConsoleLogLevel

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.

PostHogConsoleLogEntry.message

Swift
@objc let message: String

The actual content of the log message. This is the processed and sanitized log message

PostHogDisplayChoiceQuestion

Swift
@objc class PostHogDisplayChoiceQuestion

Represents a multiple or single choice question where users can select one or more options

PostHogDisplayChoiceQuestion.choices

Swift
let choices: [String]

The list of options for the user to choose from

PostHogDisplayChoiceQuestion.hasOpenChoice

Swift
let hasOpenChoice: Bool

Whether the question includes an “other” option for users to input free-form text

PostHogDisplayChoiceQuestion.isMultipleChoice

Swift
let isMultipleChoice: Bool

Whether the user can select multiple options

PostHogDisplayChoiceQuestion.shuffleOptions

Swift
let shuffleOptions: Bool

Whether the options should be shuffled to randomize the order

PostHogDisplayChoiceQuestion.skipSubmitButton

Swift
let skipSubmitButton: Bool

Whether selection should submit automatically for single-choice questions without an open choice

PostHogDisplayLinkQuestion

Swift
@objc class PostHogDisplayLinkQuestion

Represents a question with a clickable link

Swift
let link: String?

The URL that will be opened when the link is clicked

PostHogDisplayOpenQuestion

Swift
@objc class PostHogDisplayOpenQuestion

Represents an open-ended question where users can input free-form text

PostHogDisplayRatingQuestion

Swift
@objc class PostHogDisplayRatingQuestion

Represents a rating question where users can select a rating from a scale

PostHogDisplayRatingQuestion.lowerBoundLabel

Swift
let lowerBoundLabel: String

The label for the lower bound of the rating scale

PostHogDisplayRatingQuestion.ratingType

Swift
let ratingType: PostHogDisplaySurveyRatingType

The type of rating scale (numbers, emoji)

PostHogDisplayRatingQuestion.scaleLowerBound

Swift
let scaleLowerBound: Int

The lower bound of the rating scale

PostHogDisplayRatingQuestion.scaleUpperBound

Swift
let scaleUpperBound: Int

The upper bound of the rating scale

PostHogDisplayRatingQuestion.skipSubmitButton

Swift
let skipSubmitButton: Bool

Whether selecting a rating submits the answer without a submit button

PostHogDisplayRatingQuestion.upperBoundLabel

Swift
let upperBoundLabel: String

The label for the upper bound of the rating scale

PostHogDisplaySurvey

Swift
@objc class PostHogDisplaySurvey

A model representing a PostHog survey to be displayed to users

PostHogDisplaySurvey.appearance

Swift
let appearance: PostHogDisplaySurveyAppearance?

Optional appearance configuration for customizing the survey’s look and feel

PostHogDisplaySurvey.endDate

Swift
let endDate: Date?

Optional date indicating when the survey should stop being shown

PostHogDisplaySurvey.id

Swift
let id: String

Unique identifier for the survey

PostHogDisplaySurvey.initialQuestionIndex

Swift
let initialQuestionIndex: Int

The question to show when restoring an unfinished survey. Zero for a new survey.

PostHogDisplaySurvey.name

Swift
let name: String

Name of the survey

PostHogDisplaySurvey.questions

Swift
let questions: [PostHogDisplaySurveyQuestion]

Array of questions to be presented in the survey

PostHogDisplaySurvey.startDate

Swift
let startDate: Date?

Optional date indicating when the survey should start being shown

PostHogDisplaySurveyAppearance

Swift
@objc class PostHogDisplaySurveyAppearance

Model that describes the appearance customization of a PostHog survey

PostHogDisplaySurveyAppearance.backgroundColor

Swift
let backgroundColor: String?

Optional background color as web color (e.g. “#FFFFFF” or “white”)

PostHogDisplaySurveyAppearance.borderColor

Swift
let borderColor: String?

Optional border color as web color

PostHogDisplaySurveyAppearance.descriptionTextColor

Swift
let descriptionTextColor: String?

Optional color for description text as web color

PostHogDisplaySurveyAppearance.displayIntroScreen

Swift
let displayIntroScreen: Bool

Whether to show an intro screen before the first question

PostHogDisplaySurveyAppearance.displayThankYouMessage

Swift
let displayThankYouMessage: Bool

Whether to show a thank you message after survey completion

PostHogDisplaySurveyAppearance.fontFamily

Swift
let fontFamily: String?

Optional font family to use throughout the survey

PostHogDisplaySurveyAppearance.inputBackground

Swift
let inputBackground: String?

Optional background color for input fields as web color

PostHogDisplaySurveyAppearance.inputTextColor

Swift
let inputTextColor: String?

Optional text color for input fields as web color

PostHogDisplaySurveyAppearance.introScreenButtonText

Swift
let introScreenButtonText: String?

Optional text for the button that advances past the intro screen

PostHogDisplaySurveyAppearance.introScreenDescription

Swift
let introScreenDescription: String?

Optional description text for the intro screen

PostHogDisplaySurveyAppearance.introScreenDescriptionContentType

Swift
let introScreenDescriptionContentType: PostHogDisplaySurveyTextContentType?

Optional content type for the intro screen description

PostHogDisplaySurveyAppearance.introScreenHeader

Swift
let introScreenHeader: String?

Optional header text for the intro screen

PostHogDisplaySurveyAppearance.placeholder

Swift
let placeholder: String?

Optional placeholder text for input fields

PostHogDisplaySurveyAppearance.ratingButtonActiveColor

Swift
let ratingButtonActiveColor: String?

Optional color for active/selected rating buttons as web color

PostHogDisplaySurveyAppearance.ratingButtonColor

Swift
let ratingButtonColor: String?

Optional color for rating buttons as web color

PostHogDisplaySurveyAppearance.submitButtonColor

Swift
let submitButtonColor: String?

Optional background color for the submit button as web color

PostHogDisplaySurveyAppearance.submitButtonText

Swift
let submitButtonText: String?

Optional custom text for the submit button

PostHogDisplaySurveyAppearance.submitButtonTextColor

Swift
let submitButtonTextColor: String?

Optional text color for the submit button as web color

PostHogDisplaySurveyAppearance.surveyPopupDelaySeconds

Swift
let surveyPopupDelaySeconds: TimeInterval?

Optional delay in seconds before showing the survey

PostHogDisplaySurveyAppearance.textColor

Swift
let textColor: String?

Optional primary text color as web color (for questions, close button, etc.)

PostHogDisplaySurveyAppearance.thankYouMessageCloseButtonText

Swift
let thankYouMessageCloseButtonText: String?

Optional text for the close button in the thank you message

PostHogDisplaySurveyAppearance.thankYouMessageDescription

Swift
let thankYouMessageDescription: String?

Optional description text for the thank you message

PostHogDisplaySurveyAppearance.thankYouMessageDescriptionContentType

Swift
let thankYouMessageDescriptionContentType: PostHogDisplaySurveyTextContentType?

Optional content type for the thank you message description

PostHogDisplaySurveyAppearance.thankYouMessageHeader

Swift
let thankYouMessageHeader: String?

Optional header text for the thank you message

PostHogDisplaySurveyQuestion

Swift
@objc class PostHogDisplaySurveyQuestion

Base class for all survey question types

PostHogDisplaySurveyQuestion.buttonText

Swift
@objc let buttonText: String?

Optional custom text for the question’s action button

PostHogDisplaySurveyQuestion.id

Swift
@objc let id: String

The question ID, empty if none

PostHogDisplaySurveyQuestion.isOptional

Swift
@objc let isOptional: Bool

Whether the question can be skipped

PostHogDisplaySurveyQuestion.question

Swift
@objc let question: String

The main question text to display

PostHogDisplaySurveyQuestion.questionDescription

Swift
@objc let questionDescription: String?

Optional additional description or context for the question

PostHogDisplaySurveyQuestion.questionDescriptionContentType

Swift
@objc let questionDescriptionContentType: PostHogDisplaySurveyTextContentType

Content type for the question description (HTML or plain text)

PostHogErrorTrackingConfig

Swift
@objc class 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()

Swift
override init()

Creates an error tracking configuration with default in-app frame detection.

PostHogErrorTrackingConfig.autoCapture

Swift
@objc var autoCapture: Bool { get set }

Whether crash autocapture is enabled.

Discussion

When enabled, fatal crashes are persisted and sent as $exception events on the next launch. With Swift Package Manager, this is only available with the CrashReporting package trait, which is enabled by default. Default: false.

PostHogErrorTrackingConfig.exceptionSteps

Swift
@objc var exceptionSteps: PostHogExceptionStepsConfig

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

Swift
@objc var ignoredExceptionTypes: [String]

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.

Swift
config.errorTrackingConfig.ignoredExceptionTypes = ["MyCustomException"]

Default: [].

PostHogErrorTrackingConfig.inAppByDefault

Swift
@objc var inAppByDefault: Bool

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

Swift
@objc var inAppExcludes: [String]

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:

Swift
config.errorTrackingConfig.inAppExcludes = [
"Alamofire",
"SDWebImage"
]

Precedence: Priority 2 (after inAppIncludes)

PostHogErrorTrackingConfig.inAppIncludes

Swift
@objc var inAppIncludes: [String]

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:

Swift
config.errorTrackingConfig.inAppIncludes = [
"MyApp",
"SharedUtils"
]

Default behavior:

  • Automatically includes main bundle identifier

  • Automatically includes executable name

Precedence: Priority 1 (highest)

PostHogEvent

Swift
@objc(PostHogEvent) class 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

Swift
@objc var distinctId: String

Distinct ID associated with the event.

PostHogEvent.event

Swift
@objc var event: String

Event name, such as "user_signed_up" or "$screen".

PostHogEvent.options

Swift
@objc var options: [String : Any]

Options that tell PostHog how to process this event, separate from its properties.

Discussion

Holds the options passed to capture(..., options:). Known keys are process_person_profile, cookieless_mode, disable_skew_correction and product_tour_id; unknown keys are sent unchanged and ignored by PostHog. When the event is sent, the legacy $process_person_profile, $cookieless_mode, $ignore_sent_at and $product_tour_id properties are removed from properties and used for their options, unless that option is set here.

PostHogEvent.properties

Swift
@objc var properties: [String : Any]

Event properties that will be serialized with the event.

PostHogEvent.timestamp

Swift
@objc var timestamp: Date

Event timestamp. The absolute instant is serialized in UTC, regardless of the calendar or time zone used to create it.

PostHogEvent.uuid

Swift
@objc var uuid: UUID { get }

Unique event identifier generated by the SDK.

PostHogExceptionStepsConfig

Swift
@objc class 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

Swift
@objc var enabled: Bool

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

Swift
@objc var maxBytes: Int

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

Swift
@objc(PostHogFeatureFlagResult) class 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

Swift
if let result = PostHogSDK.shared.getFeatureFlagResult("my-feature") {
if result.enabled {
// Feature is enabled
if let variant = result.variant {
// Handle specific variant
print("Variant: \(variant)")
}
if let payload = result.payload as? [String: Any] {
// Use the payload data
}
}
}

PostHogFeatureFlagResult.enabled

Swift
@objc let enabled: Bool

Whether the feature flag is enabled.

Discussion

This is true if the flag value is:

  • A boolean true

  • A non-empty string (variant)

PostHogFeatureFlagResult.key

Swift
@objc let key: String

The key of the feature flag.

PostHogFeatureFlagResult.payload

Swift
@objc let payload: Any?

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

Swift
@objc let variant: String?

The variant name if this is a multivariate flag, otherwise nil.

PostHogFeatureFlagResult.payloadAs(_:)

Swift
func payloadAs<T>(_ type: T.Type) -> T? where T : Decodable

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

Swift
@objc(PostHogFeatureFlagsLoaded) final class PostHogFeatureFlagsLoaded

The feature flags passed to an onFeatureFlags callback.

Example Usage

Swift
let subscription = PostHogSDK.shared.onFeatureFlags { loaded in
if loaded.errorsLoading {
// The values are the last known (cached) flags
}
if loaded.variants["new-checkout"] as? String == "test" {
// Show the test variant
}
}
// Later, stop listening
subscription.unsubscribe()

PostHogFeatureFlagsLoaded.errorsLoading

Swift
@objc let errorsLoading: Bool

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

Swift
@objc let flags: [String]

The keys of the enabled feature flags.

PostHogFeatureFlagsLoaded.variants

Swift
@objc let variants: [String : Any]

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

Swift
@objc(PostHogFeatureFlagsSubscription) final class 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()

Swift
@objc func unsubscribe()

Stops the callback from being invoked. Calling it more than once has no effect.

PostHogLogRecord

Swift
@objc final class 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

Swift
@objc var attributes: [String : Any]

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

Swift
@objc var body: String

The log message body. Required; empty bodies are dropped at capture time.

PostHogLogRecord.distinctId

Swift
@objc var distinctId: String?

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

Swift
@objc var featureFlagKeys: [String]

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

Swift
@objc var level: PostHogLogSeverity

Severity of the log entry. Reassign to re-classify (e.g. demote a noisy .warn to .debug).

PostHogLogRecord.screenName

Swift
@objc var screenName: String?

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

Swift
@objc var sessionId: String?

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

Swift
@objc var spanId: String?

W3C span id (16 hex characters) if this log belongs to a span. nil when no span is active.

PostHogLogRecord.traceFlags

Swift
@objc var traceFlags: NSNumber?

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

Swift
@objc var traceId: String?

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

Swift
@objc final class PostHogLogger

Convenience facade for capturing log records. Use PostHogSDK.shared.logger to call trace, debug, info, warn, error, or fatal.

PostHogLogger.debug(_:)

Swift
@objc(debugWithBody:) func debug(_ body: String)

Capture a .debug record. Diagnostic detail useful during development.

Parameters
  • body: The log message. Required and non-empty.

PostHogLogger.debug(_:attributes:)

Swift
@objc(debugWithBody:attributes:) func debug(_ body: String, attributes: [String : Any]? = nil)

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(_:)

Swift
@objc(errorWithBody:) func error(_ body: String)

Capture an .error record. An operation failed; the app may continue.

Parameters
  • body: The log message. Required and non-empty.

PostHogLogger.error(_:attributes:)

Swift
@objc(errorWithBody:attributes:) func error(_ body: String, attributes: [String : Any]? = nil)

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(_:)

Swift
@objc(fatalWithBody:) func fatal(_ body: String)

Capture a .fatal record. An unrecoverable failure; the app likely cannot continue.

Parameters
  • body: The log message. Required and non-empty.

PostHogLogger.fatal(_:attributes:)

Swift
@objc(fatalWithBody:attributes:) func fatal(_ body: String, attributes: [String : Any]? = nil)

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(_:)

Swift
@objc(infoWithBody:) func info(_ body: String)

Capture an .info record. Default level for regular runtime events.

Parameters
  • body: The log message. Required and non-empty.

PostHogLogger.info(_:attributes:)

Swift
@objc(infoWithBody:attributes:) func info(_ body: String, attributes: [String : Any]? = nil)

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(_:)

Swift
@objc(traceWithBody:) func trace(_ body: String)

Capture a .trace record. Finest-grained detail; usually only enabled while diagnosing.

Parameters
  • body: The log message. Required and non-empty.

PostHogLogger.trace(_:attributes:)

Swift
@objc(traceWithBody:attributes:) func trace(_ body: String, attributes: [String : Any]? = nil)

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(_:)

Swift
@objc(warnWithBody:) func warn(_ body: String)

Capture a .warn record. Something unexpected happened but the operation continued.

Parameters
  • body: The log message. Required and non-empty.

PostHogLogger.warn(_:attributes:)

Swift
@objc(warnWithBody:attributes:) func warn(_ body: String, attributes: [String : Any]? = nil)

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

Swift
@objc final class PostHogLogsConfig

Configuration for the PostHog logs subsystem. Mutate fields on config.logs before calling PostHogSDK.setup(_:).

PostHogLogsConfig.init()

Swift
override init()

Creates a logs configuration with default queueing, resource, and rate-cap options.

PostHogLogsConfig.environment

Swift
@objc var environment: String?

OpenTelemetry deployment.environment resource attribute. Omitted from the payload when nil. Set before PostHogSDK.setup(_:); later mutations are ignored.

PostHogLogsConfig.flushAt

Swift
@objc var flushAt: Int

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

Swift
@objc var flushIntervalSeconds: TimeInterval

How often the queue checks for records to flush. Set before PostHogSDK.setup(_:); later mutations are ignored.

PostHogLogsConfig.maxBatchSize

Swift
@objc var maxBatchSize: Int

Initial maximum number of records sent in a single request. May be reduced under server backpressure.

PostHogLogsConfig.maxBufferSize

Swift
@objc var maxBufferSize: Int

Maximum number of records held on disk. When full, the oldest record is dropped (FIFO).

PostHogLogsConfig.rateCapMaxLogs

Swift
@objc var rateCapMaxLogs: Int

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

Swift
@objc var rateCapWindowSeconds: TimeInterval

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

Swift
@objc var resourceAttributes: [String : Any]

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

Swift
@objc var serviceName: String

OpenTelemetry service.name resource attribute. Defaults to the host app’s bundle identifier. Set before PostHogSDK.setup(_:); later mutations are ignored.

PostHogLogsConfig.serviceVersion

Swift
@objc var serviceVersion: String

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(_:)

Swift
func setBeforeSend(_ blocks: PostHogBeforeSendLogBlock...)

Replaces the log beforeSend chain with the provided blocks.

Parameters
  • blocks: Ordered callbacks that can mutate or drop log records.
Swift
func setBeforeSend(_ blocks: [PostHogBeforeSendLogBlock])

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.

Swift
func setBeforeSend(_ blocks: [(PostHogLogRecord) -> PostHogLogRecord?])

Replaces the log beforeSend chain with blocks from an array typed [(PostHogLogRecord) -> PostHogLogRecord?].

Parameters
  • blocks: Ordered callbacks that can mutate or drop log records.
Discussion

The blocks can run on any thread, so they must be safe to call from any thread.

PostHogNextSurveyQuestion

Swift
@objc class PostHogNextSurveyQuestion

A model representing the next state of the survey progression.

PostHogNextSurveyQuestion.isSurveyCompleted

Swift
let isSurveyCompleted: Bool

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

Swift
let questionIndex: Int

The index of the next question to be displayed (0-based)

PostHogRageClickConfig

Swift
@objc(PostHogRageClickConfig) class PostHogRageClickConfig

Configuration for iOS/macCatalyst rage click autocapture.

Overview

Rage click detection captures $rageclick when a user rapidly taps the same area.

PostHogRageClickConfig.enabled

Swift
@objc var enabled: Bool

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

Swift
@objc var minimumTapCount: Int

Number of consecutive taps within the threshold to qualify as a rage click.

Discussion

Default: 3

PostHogRageClickConfig.thresholdPoints

Swift
@objc var thresholdPoints: CGFloat

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

Swift
@objc var timeoutInterval: TimeInterval

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)

PostHogSessionReplayConfig

Swift
@objc(PostHogSessionReplayConfig) class PostHogSessionReplayConfig

Configuration for iOS session replay capture.

Overview

Mutate fields on config.sessionReplayConfig before calling PostHogSDK.setup(_:).

PostHogSessionReplayConfig.captureLogs

Swift
@objc var captureLogs: Bool

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

PostHogSessionReplayConfig.captureLogsConfig

Swift
@objc var captureLogsConfig: PostHogSessionReplayConsoleLogConfig

Further configuration for capturing console output

PostHogSessionReplayConfig.captureNetworkTelemetry

Swift
@objc var captureNetworkTelemetry: Bool

Enable capturing network telemetry Default: true

Discussion

Note: When enabled, can be disabled remotely via project settings

PostHogSessionReplayConfig.captureTouches

Swift
@objc var captureTouches: Bool

Enable recording touch coordinates in session replay. Screenshot capture is unaffected. Set before SDK setup. Runtime changes are not supported. Default: true

PostHogSessionReplayConfig.maskAllImages

Swift
@objc var maskAllImages: Bool

Enable masking of all images to a placeholder Default: true

PostHogSessionReplayConfig.maskAllSandboxedViews

Swift
@objc var maskAllSandboxedViews: Bool

Enable masking of all sandboxed system views These may include UIImagePickerController, PHPickerViewController and CNContactPickerViewController Default: true

PostHogSessionReplayConfig.maskAllTextInputs

Swift
@objc var maskAllTextInputs: Bool

Enable masking of all text and text input fields Default: true

PostHogSessionReplayConfig.sampleRate

Swift
@objc var sampleRate: NSNumber? { get set }

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.screenshotScale

Swift
@objc var screenshotScale: NSNumber? { get set }

Resolution of 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.0 uploads 1206×2622 pixels (native) and 0.5 uploads 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 compression quality. Exposed as NSNumber so Objective-C can leave it unset.

Experimental. Default: nil (one pixel per point)

PostHogSessionReplayConfig.throttleDelay

Swift
@objc var throttleDelay: TimeInterval

Throttle delay used to reduce the number of snapshots captured and reduce performance impact This is used for capturing the screenshot The lower the number more snapshots will be captured but higher the performance impact Defaults to 1s

PostHogSessionReplayConsoleLogConfig

Swift
@objc class PostHogSessionReplayConsoleLogConfig

Configuration for console log capture inside session replay recordings.

Overview

Used when PostHogSessionReplayConfig.captureLogs is enabled.

PostHogSessionReplayConsoleLogConfig.logSanitizer

Swift
@objc var logSanitizer: ((String) -> PostHogConsoleLogEntry?)

Block to process and format captured console output for session replay.

Parameters
  • output: The raw console output to process.
Return Value

A PostHogConsoleLogEntry to capture, or nil to skip the log output.

Discussion

This block is called whenever console output is captured. It allows you to:

  1. Filter or modify log messages before they are sent to session replay

  2. Determine the appropriate log level (info/warn/error) for each message

  3. 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

The block runs on a background thread, so it must not read main-actor state.

PostHogSessionReplayConsoleLogConfig.minLogLevel

Swift
@objc var minLogLevel: PostHogConsoleLogLevel

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
  • .error messages will be captured

  • .warn messages will be captured

  • .info messages will be skipped

Defaults to .error to minimize noise in session replays.

PostHogSurveyResponse

Swift
@objc @objcMembers class PostHogSurveyResponse

A model representing a user’s response to a survey question

PostHogSurveyResponse.linkClicked

Swift
let linkClicked: Bool?

Whether a link was clicked (for link questions)

PostHogSurveyResponse.ratingValue

Swift
let ratingValue: Int?

The numeric rating value (for rating questions)

PostHogSurveyResponse.selectedOptions

Swift
let selectedOptions: [String]?

The selected options (for multiple or single choice questions)

PostHogSurveyResponse.textValue

Swift
let textValue: String?

The text response (for open questions)

PostHogSurveyResponse.type

Swift
let type: PostHogSurveyResponseType

The response kind: link, rating, open-ended, single-choice, or multiple-choice.

Swift
static func link(_ clicked: Bool) -> PostHogSurveyResponse

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(_:)

Swift
static func multipleChoice(_ multipleChoice: [String]?) -> PostHogSurveyResponse

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(_:)

Swift
static func openEnded(_ openEnded: String?) -> PostHogSurveyResponse

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(_:)

Swift
static func rating(_ rating: Int?) -> PostHogSurveyResponse

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(_:)

Swift
static func singleChoice(_ singleChoice: String?) -> PostHogSurveyResponse

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

Swift
@objc class PostHogSurveysConfig

Configuration for mobile survey rendering.

Overview

Mutate fields on PostHogConfig.surveysConfig before SDK setup to customize survey UI, lifecycle handling, or localization. With Swift Package Manager, this is only available with the Surveys package trait, which is enabled by default.

PostHogSurveysConfig.overrideDisplayLanguage

Swift
@objc var overrideDisplayLanguage: String?

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

Swift
var surveysDelegate: PostHogSurveysDelegate

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.

PostHogSurveysDelegate

Swift
@objc protocol PostHogSurveysDelegate

Delegate used by the SDK to present surveys and receive survey lifecycle callbacks.

PostHogSurveysDelegate.supportsSurveyResume

Swift
@objc optional var supportsSurveyResume: Bool { get }

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:

Swift
var supportsSurveyResume: Bool { true }
// In renderSurvey, initialize the renderer at survey.initialQuestionIndex.

PostHogSurveysDelegate.cleanupSurveys()

Swift
@objc func 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:)

Swift
@objc func renderSurvey(_ survey: PostHogDisplaySurvey, onSurveyShown: @escaping OnPostHogSurveyShown, onSurveyResponse: @escaping OnPostHogSurveyResponse, onSurveyClosed: @escaping OnPostHogSurveyClosed)

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 user
  • onSurveyShown: 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(_:)

Swift
@objc optional func updateSurvey(_ survey: PostHogDisplaySurvey)

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. Its id matches the survey passed to renderSurvey.
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

Swift
typealias BeforeSendBlock = (PostHogEvent) -> PostHogEvent?

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

Swift
typealias OnPostHogSurveyClosed = (_ survey: PostHogDisplaySurvey) -> Void

To be called when a survey is dismissed

Parameters

  • survey: The survey that was closed

OnPostHogSurveyResponse

Swift
typealias OnPostHogSurveyResponse = (_ survey: PostHogDisplaySurvey, _ index: Int, _ response: PostHogSurveyResponse) -> PostHogNextSurveyQuestion?

To be called when a user responds to a survey question

Parameters

  • survey: The current survey being displayed
  • index: The index of the question being answered
  • response: 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

Swift
typealias OnPostHogSurveyShown = (_ survey: PostHogDisplaySurvey) -> Void

To be called when a survey is successfully shown to the user

Parameters

  • survey: The survey that was displayed

PostHogBeforeSendLogBlock

Swift
typealias PostHogBeforeSendLogBlock = (PostHogLogRecord) -> PostHogLogRecord?

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

Swift
@objc(PostHogCompression) enum PostHogCompression

How the SDK compresses request bodies before sending them to the PostHog API.

PostHogCompression.PostHogCompression.gzip

Swift
case gzip

Gzip request bodies. If gzipping fails on device, the body is sent uncompressed.

PostHogCompression.PostHogCompression.none

Swift
case none

Send request bodies uncompressed, with no Content-Encoding header.

PostHogConsoleLogLevel

Swift
@objc enum PostHogConsoleLogLevel

The severity level of a console log entry.

Overview

Used to categorize logs by their severity in session replay.

PostHogConsoleLogLevel.PostHogConsoleLogLevel.error

Swift
case error

Error messages indicating failures or critical issues

PostHogConsoleLogLevel.PostHogConsoleLogLevel.info

Swift
case info

Informational messages, debugging output, and general logs

PostHogConsoleLogLevel.PostHogConsoleLogLevel.warn

Swift
case warn

Warning messages indicating potential issues or deprecation notices

PostHogDisplaySurveyRatingType

Swift
@objc enum PostHogDisplaySurveyRatingType

Type of rating display for survey rating questions

PostHogDisplaySurveyRatingType.PostHogDisplaySurveyRatingType.emoji

Swift
case emoji

Display emoji rating options

PostHogDisplaySurveyRatingType.PostHogDisplaySurveyRatingType.number

Swift
case number

Display numeric rating options

PostHogDisplaySurveyTextContentType

Swift
@objc enum PostHogDisplaySurveyTextContentType

Content type for text-based survey elements

PostHogDisplaySurveyTextContentType.PostHogDisplaySurveyTextContentType.html

Swift
case html

Content should be rendered as HTML

PostHogDisplaySurveyTextContentType.PostHogDisplaySurveyTextContentType.text

Swift
case text

Content should be rendered as plain text

PostHogLogSeverity

Swift
@objc enum 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

Swift
case debug

Diagnostic information useful while debugging.

PostHogLogSeverity.PostHogLogSeverity.error

Swift
case error

Error messages indicating failures or critical issues.

PostHogLogSeverity.PostHogLogSeverity.fatal

Swift
case fatal

An unrecoverable failure; the app likely cannot continue.

PostHogLogSeverity.PostHogLogSeverity.info

Swift
case info

Informational messages and general logs.

PostHogLogSeverity.PostHogLogSeverity.trace

Swift
case trace

Finest-grained tracing detail.

PostHogLogSeverity.PostHogLogSeverity.warn

Swift
case warn

Warning messages indicating potential issues or deprecation notices.

PostHogPersonProfiles

Swift
@objc(PostHogPersonProfiles) enum 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 the process_person_profile: false option.

  • always: We will process persons data for all events.

  • identifiedOnly: (default): we will only process persons when you call identify, alias, and group, Anonymous users won’t get person profiles.

PostHogPersonProfiles.PostHogPersonProfiles.always

Swift
case always

Always process person profiles for all events.

PostHogPersonProfiles.PostHogPersonProfiles.identifiedOnly

Swift
case identifiedOnly

Process person profiles only after identify, alias, or group creates one.

PostHogPersonProfiles.PostHogPersonProfiles.never

Swift
case never

Never process person profiles. All events are sent with the process_person_profile: false option.

PostHogSurveyResponseType

Swift
@objc enum PostHogSurveyResponseType

Type of response submitted for a survey question.

Swift
case link

Response for a link question.

PostHogSurveyResponseType.PostHogSurveyResponseType.multipleChoice

Swift
case multipleChoice

Response for a multiple-choice question.

PostHogSurveyResponseType.PostHogSurveyResponseType.openEnded

Swift
case openEnded

Response for an open-ended text question.

PostHogSurveyResponseType.PostHogSurveyResponseType.rating

Swift
case rating

Response for a rating question.

PostHogSurveyResponseType.PostHogSurveyResponseType.singleChoice

Swift
case singleChoice

Response for a single-choice question.

Was this page useful?