diff --git a/PostHog/PostHogSDK.swift b/PostHog/PostHogSDK.swift index c71a579de..d3d7234cf 100644 --- a/PostHog/PostHogSDK.swift +++ b/PostHog/PostHogSDK.swift @@ -119,6 +119,8 @@ let maxRetryDelay = 30.0 /// Logger facade exposing `trace/debug/info/warn/error/fatal(_:attributes:)`. /// `nil` before `setup(_:)` is called. + /// + /// posthog-capability: logs @objc public private(set) var logger: PostHogLogger? #if os(iOS) @@ -161,6 +163,8 @@ let maxRetryDelay = 30.0 /// Enables or disables SDK debug logging at runtime. /// + /// posthog-capability: debug + /// /// - Parameter enabled: Pass `true` to enable verbose logs or `false` to disable them. @objc public func debug(_ enabled: Bool = true) { if !isEnabled() { @@ -172,6 +176,8 @@ let maxRetryDelay = 30.0 /// Initializes this SDK instance with the provided configuration. /// + /// posthog-capability: setup + /// /// 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. /// @@ -425,6 +431,8 @@ let maxRetryDelay = 30.0 /// Returns the current PostHog distinct ID. /// + /// posthog-capability: get-distinct-id + /// /// Before `identify(_:)`, this is the anonymous ID. After identify, this is the identified user's ID. /// /// - Returns: The current distinct ID, or an empty string when the SDK is not set up. @@ -434,6 +442,8 @@ let maxRetryDelay = 30.0 /// Returns the anonymous ID generated for this install. /// + /// posthog-capability: get-anonymous-id + /// /// - Returns: The anonymous ID, or an empty string when the SDK is not set up. @objc public func getAnonymousId() -> String { getStorageManagerValue { $0.getAnonymousId() } @@ -459,6 +469,8 @@ let maxRetryDelay = 30.0 /// Returns the current session ID without rotating or creating a session. /// + /// posthog-capability: get-session-id + /// /// - Returns: The current session ID, or `nil` if no session is active or the SDK is not set up. @objc public func getSessionId() -> String? { if !isEnabled() { @@ -844,6 +856,8 @@ let maxRetryDelay = 30.0 /// Trigger an immediate flush of every queue — events, session-replay /// snapshots, and structured logs. + /// + /// posthog-capability: flush @objc public func flush() { if !isEnabled() { return @@ -878,6 +892,8 @@ let maxRetryDelay = 30.0 /// Resets local identity, super properties, feature flag cache, and session state. /// + /// posthog-capability: reset + /// /// 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. @@ -947,6 +963,8 @@ let maxRetryDelay = 30.0 // register is a reserved word in ObjC /// Registers super properties that are included with every subsequent event. /// + /// posthog-capability: register + /// /// New values overwrite existing values for the same keys and persist across app restarts /// until removed with `unregister(_:)` or cleared by `reset()`. /// @@ -974,6 +992,8 @@ let maxRetryDelay = 30.0 /// Removes a previously registered super property. /// + /// posthog-capability: unregister + /// /// - Parameter key: The property key to stop attaching to future events. @objc(unregisterProperties:) public func unregister(_ key: String) { @@ -993,6 +1013,8 @@ let maxRetryDelay = 30.0 /// Identifies the current user with a stable distinct ID. /// + /// posthog-capability: identify + /// /// 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. @@ -1005,6 +1027,8 @@ let maxRetryDelay = 30.0 /// Identifies the current user and sets person properties. /// + /// posthog-capability: identify + /// /// - Parameters: /// - distinctId: Stable user identifier from your application. /// - userProperties: Properties to set on the person profile. Existing values are overwritten. @@ -1017,6 +1041,8 @@ let maxRetryDelay = 30.0 /// Identifies the current user and sets person properties. /// + /// posthog-capability: identify + /// /// - Parameters: /// - distinctId: Stable user identifier from your application. /// - userProperties: Properties to set on the person profile. Existing values are overwritten. @@ -1145,6 +1171,8 @@ let maxRetryDelay = 30.0 /// Sets properties on the person profile associated with the current distinct_id. /// + /// posthog-capability: set-person-properties + /// /// Updates user properties that are stored with the person profile in PostHog. /// If `personProfiles` is set to `never`, this call will be ignored. /// @@ -1161,6 +1189,8 @@ let maxRetryDelay = 30.0 /// Sets properties on the person profile associated with the current distinct_id. /// + /// posthog-capability: set-person-properties + /// /// Updates user properties that are stored with the person profile in PostHog. /// If `personProfiles` is set to `never`, this call will be ignored. /// @@ -1308,6 +1338,8 @@ let maxRetryDelay = 30.0 /// Captures a custom event for the current user. /// + /// posthog-capability: capture + /// /// - Parameter event: Event name to capture. @objc public func capture(_ event: String) { capture(event, distinctId: nil, properties: nil, userProperties: nil, userPropertiesSetOnce: nil, groups: nil) @@ -1315,6 +1347,8 @@ let maxRetryDelay = 30.0 /// Captures a custom event with event properties. /// + /// posthog-capability: capture + /// /// - Parameters: /// - event: Event name to capture. /// - properties: Event properties attached only to this event. @@ -1327,6 +1361,8 @@ let maxRetryDelay = 30.0 /// Captures a custom event and updates person properties. /// + /// posthog-capability: capture + /// /// - Parameters: /// - event: Event name to capture. /// - properties: Event properties attached only to this event. @@ -1341,6 +1377,8 @@ let maxRetryDelay = 30.0 /// Captures a custom event and updates person properties. /// + /// posthog-capability: capture + /// /// - Parameters: /// - event: Event name to capture. /// - properties: Event properties attached only to this event. @@ -1357,6 +1395,8 @@ let maxRetryDelay = 30.0 /// Captures a custom event with group context. /// + /// posthog-capability: capture + /// /// - Parameters: /// - event: Event name to capture. /// - properties: Event properties attached only to this event. @@ -1375,6 +1415,8 @@ let maxRetryDelay = 30.0 /// Captures a custom event for an explicit distinct ID. /// + /// posthog-capability: capture + /// /// - Parameters: /// - event: Event name to capture. /// - distinctId: Optional distinct ID override. Defaults to the current SDK distinct ID. @@ -1401,6 +1443,8 @@ let maxRetryDelay = 30.0 /// Captures a custom event for an explicit distinct ID and timestamp. /// + /// posthog-capability: capture + /// /// - Parameters: /// - event: Event name to capture. /// - distinctId: Optional distinct ID override. Defaults to the current SDK distinct ID. @@ -1435,6 +1479,8 @@ let maxRetryDelay = 30.0 /// Capture a structured log record at `.info` severity. /// + /// posthog-capability: logs + /// /// 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 @@ -1452,6 +1498,8 @@ let maxRetryDelay = 30.0 /// Capture a structured log record at the given severity. /// + /// posthog-capability: logs + /// /// - Parameters: /// - body: The log message. Required and non-empty. /// - level: Severity. Use `.trace`/`.debug` for diagnostic detail, @@ -1463,6 +1511,8 @@ let maxRetryDelay = 30.0 /// Capture a structured log record with caller-supplied attributes. /// + /// posthog-capability: logs + /// /// - Parameters: /// - body: The log message. Required and non-empty. /// - level: Severity. @@ -1478,6 +1528,8 @@ let maxRetryDelay = 30.0 /// callers correlating logs with distributed traces; most apps should use /// the simpler overload. /// + /// posthog-capability: logs + /// /// - Parameters: /// - body: The log message. Required and non-empty. /// - level: Severity. @@ -1501,6 +1553,8 @@ let maxRetryDelay = 30.0 /// argument except `body`. Most call sites can write `captureLog("...")` /// or `captureLog("...", level: .warn, attributes: [...])`. /// + /// posthog-capability: logs + /// /// - Parameters: /// - body: The log message. Required and non-empty. /// - level: Severity. Defaults to `.info`. @@ -1701,6 +1755,8 @@ let maxRetryDelay = 30.0 /// Records a screen view by capturing a `$screen` event. /// + /// posthog-capability: screen + /// /// - Parameter screenTitle: The screen name to record. @objc public func screen(_ screenTitle: String) { screen(screenTitle, properties: nil) @@ -1708,6 +1764,8 @@ let maxRetryDelay = 30.0 /// Records a screen view by capturing a `$screen` event with `screenTitle`. /// + /// posthog-capability: screen + /// /// The title is also cached and automatically attached as `$screen_name` to /// every subsequent event (until `reset()` or `close()` clears it). /// @@ -1849,6 +1907,8 @@ let maxRetryDelay = 30.0 /// Assigns an additional distinct ID to the current user. /// + /// posthog-capability: alias + /// /// Use alias when a user should be connected to another identifier that was previously used /// to track them. This sends a `$create_alias` event. /// @@ -2036,6 +2096,8 @@ let maxRetryDelay = 30.0 /// Associates subsequent events with a group. /// + /// posthog-capability: group + /// /// - Parameters: /// - type: Group type, such as `"company"` or `"organization"`. /// - key: Group key from your application. @@ -2046,6 +2108,8 @@ let maxRetryDelay = 30.0 /// Associates subsequent events with a group and optionally updates group properties. /// + /// posthog-capability: group + /// /// This sends a `$groupidentify` event and reloads feature flags if the group value changed. /// The call is ignored if `type` or `key` is empty. /// @@ -2084,6 +2148,8 @@ let maxRetryDelay = 30.0 /// Sets person properties that will be included in feature flag evaluation requests. /// + /// posthog-capability: set-person-properties-for-flags + /// /// 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. @@ -2116,6 +2182,8 @@ let maxRetryDelay = 30.0 /// Sets person properties that will be included in feature flag evaluation requests. /// + /// posthog-capability: set-person-properties-for-flags + /// /// 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. @@ -2182,6 +2250,8 @@ let maxRetryDelay = 30.0 /// Resets all person properties that were set for feature flag evaluation. /// + /// posthog-capability: reset-person-properties-for-flags + /// /// After calling this method, feature flag evaluation will only use server-side person properties /// and will not include any locally overridden properties. /// @@ -2199,6 +2269,8 @@ let maxRetryDelay = 30.0 /// Resets all person properties that were set for feature flag evaluation. /// + /// posthog-capability: reset-person-properties-for-flags + /// /// After calling this method, feature flag evaluation will only use server-side person properties /// and will not include any locally overridden properties. /// @@ -2230,6 +2302,8 @@ let maxRetryDelay = 30.0 /// These properties supplement the standard group information sent to PostHog for flag evaluation, /// providing additional context that can be used in flag targeting conditions. /// + /// posthog-capability: set-group-properties-for-flags + /// /// ## Example Usage /// ```swift /// PostHogSDK.shared.setGroupPropertiesForFlags("organization", properties: [ @@ -2253,6 +2327,8 @@ let maxRetryDelay = 30.0 /// These properties supplement the standard group information sent to PostHog for flag evaluation, /// providing additional context that can be used in flag targeting conditions. /// + /// posthog-capability: set-group-properties-for-flags + /// /// ## Example Usage /// ```swift /// // Set properties without automatically reloading flags @@ -2286,6 +2362,8 @@ let maxRetryDelay = 30.0 /// Clears all group properties for feature flag evaluation. /// + /// posthog-capability: reset-group-properties-for-flags + /// /// ## Example Usage /// ```swift /// // Clear all group properties @@ -2297,6 +2375,8 @@ let maxRetryDelay = 30.0 /// Clears all group properties for feature flag evaluation. /// + /// posthog-capability: reset-group-properties-for-flags + /// /// ## Example Usage /// ```swift /// // Clear all group properties @@ -2311,6 +2391,8 @@ let maxRetryDelay = 30.0 /// Clears group properties for feature flag evaluation for a specific group type. /// + /// posthog-capability: reset-group-properties-for-flags + /// /// ## Example Usage /// ```swift /// // Clear properties for specific group type @@ -2325,6 +2407,8 @@ let maxRetryDelay = 30.0 /// Clears group properties for feature flag evaluation for a specific group type. /// + /// posthog-capability: reset-group-properties-for-flags + /// /// ## Example Usage /// ```swift /// // Clear properties for specific group type @@ -2353,6 +2437,8 @@ let maxRetryDelay = 30.0 } /// Reloads feature flags for the current user and group context. + /// + /// posthog-capability: reload-feature-flags @objc public func reloadFeatureFlags() { reloadFeatureFlags { // No use case @@ -2361,6 +2447,8 @@ let maxRetryDelay = 30.0 /// Reloads feature flags and invokes a callback when finished. /// + /// posthog-capability: reload-feature-flags + /// /// - Parameter callback: Invoked when the reload finishes, or immediately if the reload /// is skipped (SDK disabled/opted-out, or no remote config available). @objc(reloadFeatureFlagsWithCallback:) @@ -2382,6 +2470,8 @@ let maxRetryDelay = 30.0 /// Registers a callback that's invoked whenever feature flags are loaded or updated. /// + /// posthog-capability: on-feature-flags + /// /// 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 @@ -2500,6 +2590,8 @@ let maxRetryDelay = 30.0 /// Returns the feature flag result containing the flag value, variant, and payload. /// + /// posthog-capability: get-feature-flag-result + /// /// This is the recommended method for retrieving feature flags as it provides /// all flag information in a single call and properly tracks flag usage. /// @@ -2512,6 +2604,8 @@ let maxRetryDelay = 30.0 /// Returns the feature flag result and optionally captures a usage event. /// + /// posthog-capability: get-feature-flag-result + /// /// - Parameters: /// - key: The feature flag key. /// - sendFeatureFlagEvent: Whether to capture `$feature_flag_called` for this lookup. @@ -2543,6 +2637,8 @@ let maxRetryDelay = 30.0 /// Returns a feature flag value. /// + /// posthog-capability: get-feature-flag + /// /// Boolean flags return `Bool`. Multivariate flags return their variant `String`. /// /// - Parameter key: The feature flag key. @@ -2553,6 +2649,8 @@ let maxRetryDelay = 30.0 /// Returns a feature flag value and optionally captures a usage event. /// + /// posthog-capability: get-feature-flag + /// /// - Parameters: /// - key: The feature flag key. /// - sendFeatureFlagEvent: Whether to capture `$feature_flag_called` for this lookup. @@ -2569,6 +2667,8 @@ let maxRetryDelay = 30.0 /// Returns whether a feature flag is enabled. /// + /// posthog-capability: is-feature-enabled + /// /// Multivariate flags are considered enabled when a variant string is returned. /// /// - Parameter key: The feature flag key. @@ -2579,6 +2679,8 @@ let maxRetryDelay = 30.0 /// Returns whether a feature flag is enabled and optionally captures a usage event. /// + /// posthog-capability: is-feature-enabled + /// /// - Parameters: /// - key: The feature flag key. /// - sendFeatureFlagEvent: Whether to capture `$feature_flag_called` for this lookup. @@ -2595,6 +2697,8 @@ let maxRetryDelay = 30.0 /// Returns all currently loaded feature flags as structured results. /// + /// posthog-capability: get-feature-flags + /// /// 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 @@ -2616,6 +2720,8 @@ let maxRetryDelay = 30.0 /// Returns the payload for a feature flag. /// + /// posthog-capability: get-feature-flag-payload + /// /// - Parameter key: The feature flag key. /// - Returns: The flag payload, or `nil` if the flag or payload is unavailable. /// - Warning: This method does not send the `$feature_flag_called` event. @@ -2771,6 +2877,8 @@ let maxRetryDelay = 30.0 /// Opts the current user back into data capture. /// + /// posthog-capability: opt-in + /// /// 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, @@ -2843,6 +2951,8 @@ let maxRetryDelay = 30.0 /// Opts the current user out of data capture. /// + /// posthog-capability: opt-in + /// /// 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. @@ -2878,6 +2988,8 @@ let maxRetryDelay = 30.0 /// Returns whether this SDK instance is currently opted out. /// + /// posthog-capability: is-opt-out + /// /// - Returns: `true` when opted out or when the SDK is not set up. @objc public func isOptOut() -> Bool { if !isEnabled() { @@ -2889,6 +3001,8 @@ let maxRetryDelay = 30.0 /// Shuts down this SDK instance and clears its in-memory state. /// + /// posthog-capability: shutdown + /// /// Starts sending queued events, session replay snapshots, and logs (up to one batch each) and returns without /// waiting for delivery. Anything not sent, for example while offline, stays on disk and is sent after the next /// setup. Integrations are uninstalled, and this instance must be set up again before reuse. @@ -2956,6 +3070,8 @@ let maxRetryDelay = 30.0 /** Starts session recording. + posthog-capability: start-session-recording + 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: @@ -2974,6 +3090,8 @@ let maxRetryDelay = 30.0 /** Starts session recording. + posthog-capability: start-session-recording + 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: @@ -3031,6 +3149,8 @@ let maxRetryDelay = 30.0 /** Stops the current session recording if one is in progress. + posthog-capability: stop-session-recording + 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 @@ -3108,6 +3228,8 @@ let maxRetryDelay = 30.0 /// Creates and sets up an additional SDK instance. /// + /// posthog-capability: setup + /// /// - Parameter config: Configuration for the new instance. /// - Returns: A configured `PostHogSDK` instance. @objc public static func with(_ config: PostHogConfig) -> PostHogSDK { @@ -3119,6 +3241,8 @@ let maxRetryDelay = 30.0 #if os(iOS) /// Returns whether session replay is currently recording. /// + /// posthog-capability: is-session-replay-active + /// /// - Returns: `true` only when replay is active, a session ID exists, and remote config allows recording. @objc public func isSessionReplayActive() -> Bool { if !isEnabled() { @@ -3157,6 +3281,8 @@ let maxRetryDelay = 30.0 /// Capture a Swift Error or NSError /// + /// posthog-capability: capture-exception + /// /// Captures an error as a `$exception` event with full stack trace and error chain information. /// The error will be marked as handled by default. /// @@ -3191,6 +3317,8 @@ let maxRetryDelay = 30.0 /// Capture a Swift Error or NSError without additional properties /// + /// posthog-capability: capture-exception + /// /// Convenience overload for Objective-C callers so `properties:` doesn't need to be passed as `nil`. /// /// - Parameter error: The error to capture (can be any Error or NSError) @@ -3204,6 +3332,8 @@ let maxRetryDelay = 30.0 /// Capture an NSException /// + /// posthog-capability: capture-exception + /// /// Captures an NSException as a `$exception` event with full stack trace. /// This is useful for Objective-C code that uses NSException. /// @@ -3238,6 +3368,8 @@ let maxRetryDelay = 30.0 /// Capture an NSException without additional properties /// + /// posthog-capability: capture-exception + /// /// Convenience overload for Objective-C callers so `properties:` doesn't need to be passed as `nil`. /// /// - Parameter exception: The NSException to capture @@ -3251,6 +3383,8 @@ let maxRetryDelay = 30.0 /// Record an exception step (breadcrumb-style context record). /// + /// posthog-capability: exception-steps + /// /// 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 @@ -3305,6 +3439,8 @@ let maxRetryDelay = 30.0 /// Record an exception step without additional properties. /// + /// posthog-capability: exception-steps + /// /// Convenience overload for Objective-C callers so `properties:` doesn't need to be passed as `nil`. /// /// - Parameter message: A short, non-empty description of what happened.