references/usage.md · 24000
ant: "variant-key") PostHogSDK.shared.captureFeatureInteraction(flag: "flag-key", flagVariant: "variant-key")
### Bootstrapping flags
Since there is a delay between initializing PostHog and fetching feature flags, feature flags are not always available immediately. This makes them unusable if you want to do something like redirecting a user to a different page based on a feature flag.
To have your feature flags available immediately, you can initialize PostHog with precomputed values until it has had a chance to fetch them. This is called bootstrapping. After the SDK fetches feature flags from PostHog, it will use those flag values instead of bootstrapped ones.
Set `config.bootstrap` before calling `setup()` to seed identity and flag values before the first `/flags` response (requires iOS SDK `3.66.0`+):
```swift
let config = PostHogConfig(projectToken: "<ph_project_token>", host: "https://us.i.posthog.com")
config.bootstrap = PostHogBootstrapConfig(
distinctId: "distinct_id_of_your_user",
isIdentifiedId: true,
featureFlags: [
"flag-1": true,
"variant-flag": "control"
],
featureFlagPayloads: nil
)
PostHogSDK.shared.setup(config)
- Bootstrapped identity applies during setup. On a fresh install, setting it before
setup()means events captured synchronously during initialization (likeApplication Installed) carry your distinct ID instead of the SDK-generated UUID.- An anonymous bootstrap (
isIdentifiedId: false, the default) seeds the anonymous ID only when none is persisted yet. Once an anonymous ID exists on disk, or the person has been identified, the SDK ignores it. - An identified bootstrap (
isIdentifiedId: true) is for a signed-in identity available to your app (for example, from a backend session token). On a fresh install, it seeds the distinct ID, marks the person identified, and generates a separate device ID. On a returning install, a matching anonymous ID is marked identified without emitting$identify; a different anonymous ID is merged viaidentify()when person profiles are enabled. This emits$identifyunless capturing is opted out. A different, already-identified person is left untouched.
- An anonymous bootstrap (
- Bootstrapped flags are served until the first
/flagsresponse, then replaced. A complete/flagsresponse takes over entirely, so bootstrapped-only keys don't persist past it. Only enabled flags are seeded: atrueboolean or a non-empty variant string. Afalseor empty value is dropped, matching posthog-js. Seed payloads with the separatefeatureFlagPayloadsoption. Flag values and payloads must be JSON-serializable, or they're dropped. Bootstrapped flags are cleared onreset().
The feature-flags-loaded signal fires as soon as bootstrapped flags are applied, so startup logic can read them immediately. These SDKs don't support the sessionID bootstrap option. When person profiles are set to never, the SDK preserves a different anonymous identity instead of merging it into an identified bootstrap.
See the SDK bootstrapping guide for the cross-SDK overview.
Experiments (A/B tests)
Since experiments use feature flags, the code for running an experiment is very similar to the feature flags code. See adding experiment code for iOS examples.
It's also possible to run experiments without using feature flags.
A note about IDFA (identifier for advertisers) collection in iOS 14
Starting with iOS 14, Apple will further restrict apps that track users. Any references to Apple's AdSupport framework, even in strings, will trip the App Store's static analysis.
Hence starting with posthog-ios version 1.2.0 we have removed all references to Apple's AdSupport framework.
Session replay
Note: Session replay is currently only available on iOS. For future macOS support, please follow and upvote this GitHub issue.
To set up session replay in your project, all you need to do is install the iOS SDK, enable "Record user sessions" in your project settings and enable the sessionReplay option.
Surveys
Surveys launched with popover presentation are automatically shown to users matching the display conditions you set up.
Error tracking
To set up error tracking in your project, see the error tracking docs.
Debug mode
If you're not seeing the expected events being captured, the feature flags being evaluated, or the surveys being shown, you can enable debug mode to see what's happening.
You can enable debug mode by setting the debug option to true in the PostHogConfig object. A common pattern is to set this to true in development environments only for local development.
let config = PostHogConfig(projectToken: "<ph_project_token>", host: "https://us.i.posthog.com")
config.debug = true
PostHogSDK.shared.setup(config)
This will enable verbose logs about the inner workings of the SDK.
You can also toggle debug by calling the PostHogSDK.shared.debug() method in your code.
// Enable debug mode
PostHogSDK.shared.debug(true)
// Disable debug mode
PostHogSDK.shared.debug(false)