MixpanelOptions

Property keys that ingestion or identity resolution require and that will never be stripped by excludeProperties, even if a customer lists them. Single source of truth for both the runtime filter (see Track.applyExcludeProperties) and the documentation.

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Property keys that will be stripped from outgoing event and People payloads before they are persisted and sent to Mixpanel. Defaults to empty (no filtering, zero per-payload overhead).

Use this to reduce payload size or to suppress properties the project has no interest in. Matching is exact and case-sensitive.

Keys in reservedPropertyKeys are never stripped, even if listed — they are required for ingestion and identity resolution.

Scope:

• Events — applied at the persistence chokepoint, covering super properties, caller properties, and SDK auto-properties uniformly.
• People $set and $set_once — applied after the SDK merges AutomaticProperties.peopleProperties (the auto-injected $ios_* device keys) so those auto-injected keys are subject to the same exclude set as event auto-properties.

Not in scope:

• Other People operators ($add, $append, $union, $unset, $merge, $remove, $delete) are pass-through. Their property keys are operands rather than a bag to mutate, and filtering inside them would silently change semantics (e.g. dropping a name from an $unset list).
• Group updates never merge auto-properties, so there is nothing the filter would contribute that the caller couldn’t omit themselves.
• $mp_metadata is a sibling of properties in the event envelope and is structurally outside the filter’s scope by design.

Recommended: do not strip mp_lib or $lib_version. Mixpanel does not need them for ingestion or identity resolution, so stripping them is permitted — but they are how Mixpanel identifies which SDK (and which version) produced an event. Removing them limits reporting accuracy (e.g. per-platform breakdowns) and makes it harder for support to debug issues on your project. If either key is included here, the SDK logs a warning at instance creation time.

Undocumented

Undocumented

Grouped configuration for feature flags behavior.

When provided to the initializer, this takes precedence over the featureFlagsEnabled and featureFlagsContext parameters.

A closure that provides a custom device ID.

Use this to control device ID generation instead of relying on the SDK’s default behavior (random UUID or IDFV based on useUniqueDistinctId).

Important: Choose your device ID strategy up front. This closure is called:

• Once during initialization (if no persisted identity exists)
• On each call to reset()
• On each call to optOutTracking()

Controlling Reset Behavior:

• Return the same value each time = Device ID never changes (persistent identity)
• Return a different value each time = Device ID changes on reset (ephemeral identity)
• Return nil = Use SDK’s default device ID (useful for error handling)

Thread Safety: This closure is called synchronously while holding internal locks. Keep implementations fast and non-blocking. For Keychain or network-fetched IDs, retrieve and cache the value at app launch, then return the cached value from the provider.

Warning: Adding a deviceIdProvider to an existing app that previously used the default device ID may cause identity discontinuity. The SDK will log a warning if the provider returns a value different from the persisted anonymous ID.

Example - Persistent Device ID (cached at launch):

// Cache the device ID at app launch (before Mixpanel init)
let cachedDeviceId = MyKeychainHelper.getOrCreatePersistentId()

let options = MixpanelOptions(
    token: "YOUR_TOKEN",
    deviceIdProvider: { cachedDeviceId }  // Return cached value
)

Example - Ephemeral Device ID (resets each time):

let options = MixpanelOptions(
    token: "YOUR_TOKEN",
    deviceIdProvider: {
        return UUID().uuidString
    }
)

Configuration for automatic event capture (clicks, rage clicks, dead clicks).

Autocapture is disabled by default. Provide an AutocaptureOptions instance to enable automatic capture of user interactions.

Example — Enable autocapture with defaults:

let options = MixpanelOptions(
    token: "YOUR_TOKEN",
    autocaptureOptions: AutocaptureOptions()
)

Note: Autocapture is only available on iOS. It is not supported when the app runs as a Mac Catalyst build; the options are accepted so shared iOS sources still compile, but no automatic capture takes place there.

Undocumented