Install

npm install @dhrimz/capacitor-mixpanel

Add the following plugin configuration:

{
  ...
  "Mixpanel": {
    "token": "token-abcdefg1234",
    "trackAutomaticEvents": true, // optional, default: true
    "optOutTrackingByDefault": false, // optional, default: false
    "disableIosIpCollection": true, // optional, default: false
    "serverURL": "https://api-eu.mixpanel.com/", // optional, default: "https://api.mixpanel.com/"
    "persistence": "localStorage", // optional (WEB ONLY), default: "cookie"
    "track_pageview": true, // optional (WEB ONLY), default: false
  },
  ...
}

Sync capacitor configuration

npx cap sync

API

• initialize(...)
• distinctId()
• track(...)
• identify(...)
• alias(...)
• reset()
• clearSuperProperties()
• currentSuperProperties()
• registerSuperProperties(...)
• setProfile(...)
• setProfileUnion(...)
• deleteProfile()
• trackCharge(...)
• flush()
• optInTracking(...)
• optOutTracking()
• hasOptedOutTracking()
• startSessionRecording()
• stopSessionRecording()
• getSessionReplayUrl()
• getSessionRecordingProperties()
• getFeatureFlagVariant(...)
• getFeatureFlagValue(...)
• isFeatureFlagEnabled(...)
• areFlagsReady()
• updateFeatureFlagContext(...)
• Interfaces
• Type Aliases

initialize(...)

initialize(options: InitializeOptions) => Promise<void>

Initialize the plugin with your Mixpanel token and configuration.

> Platform: Web only — on iOS and Android, Mixpanel is initialized > automatically via the capacitor.config.json plugin configuration.

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | InitializeOptions |

distinctId()

distinctId() => Promise<{ value: string; }>

Returns the current distinct id of the user. This is either the id automatically generated by the library or the id that has been passed by a call to identify().

> Platforms: iOS, Android, Web

Returns: Promise<{ value: string; }>

track(...)

track(options: TrackOptions) => Promise<void>

Tracks an event with properties. Properties are optional and can be added only if needed.

> Platforms: iOS, Android, Web

| Param | Type | | ------------- | ----------------------------------------------------- | | options | TrackOptions |

identify(...)

identify(options: IdentifyOptions) => Promise<void>

Identify a user with a unique ID to track user activity across devices, tie a user to their events, and create a user profile. If you never call this method, unique visitors are tracked using a UUID generated the first time they visit the site.

> Platforms: iOS, Android, Web

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | IdentifyOptions |

alias(...)

alias(options: AliasOptions) => Promise<void>

The alias method creates an alias which Mixpanel will use to remap one id to another. Multiple aliases can point to the same identifier.

> Platforms: iOS, Android, Web

| Param | Type | | ------------- | ----------------------------------------------------- | | options | AliasOptions |

reset()

reset() => Promise<void>

Clears super properties and generates a new random distinct_id for this instance. Useful for clearing data when a user logs out.

> Platforms: iOS, Android, Web

clearSuperProperties()

clearSuperProperties() => Promise<void>

Clears all currently set super properties.

> Platforms: iOS, Android, Web

currentSuperProperties()

currentSuperProperties() => Promise<{ properties: any; }>

Returns the currently set super properties.

> Platforms: iOS, Android, Web

Returns: Promise<{ properties: any; }>

registerSuperProperties(...)

registerSuperProperties(options: SuperPropertyOptions) => Promise<void>

Register super properties that will be sent with every event.

> Platforms: iOS, Android, Web

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | SuperPropertyOptions |

setProfile(...)

setProfile(options: ProfileProperties) => Promise<void>

Set properties on the current user in Mixpanel People.

> Platforms: iOS, Android, Web

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | ProfileProperties |

setProfileUnion(...)

setProfileUnion(options: ProfileProperties) => Promise<void>

Union list properties.

> Platforms: iOS, Android, Web

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | ProfileProperties |

deleteProfile()

deleteProfile() => Promise<void>

Permanently deletes the current people analytics profile from Mixpanel (using the current distinctId).

> Platforms: iOS, Android, Web

trackCharge(...)

trackCharge(options: ChargeOptions) => Promise<void>

Track money spent by the current user for revenue analytics and associate properties with the charge. Properties is optional.

> Platforms: iOS, Android, Web

| Param | Type | | ------------- | ------------------------------------------------------- | | options | ChargeOptions |

flush()

flush() => Promise<void>

Uploads queued data to the Mixpanel server.

> Platform: iOS, Android only — no-op on Web.

optInTracking(...)

optInTracking(options: OptInOptions) => Promise<void>

Opt in tracking. Use this method to opt in an already opted out user from tracking. People updates and track calls will be sent to Mixpanel after using this method.

> Platforms: iOS, Android, Web

| Param | Type | | ------------- | ----------------------------------------------------- | | options | OptInOptions |

optOutTracking()

optOutTracking() => Promise<void>

Opt out tracking. This method is used to opt out tracking. This causes all events and people request no longer to be sent back to the Mixpanel server.

> Platforms: iOS, Android, Web

hasOptedOutTracking()

hasOptedOutTracking() => Promise<{ value: boolean; }>

Returns the current opt-out status.

> Platforms: iOS, Android, Web

Returns: Promise<{ value: boolean; }>

startSessionRecording()

startSessionRecording() => Promise<void>

Start recording the current session.

> Platform: Web only

stopSessionRecording()

stopSessionRecording() => Promise<void>

Stop the current session recording.

> Platform: Web only

getSessionReplayUrl()

getSessionReplayUrl() => Promise<{ value: string; }>

Get a URL to view the current session replay in the Mixpanel UI.

> Platform: Web only

Returns: Promise<{ value: string; }>

getSessionRecordingProperties()

getSessionRecordingProperties() => Promise<{ properties: any; }>

Get session recording properties (e.g., $mp_replay_id) for the current recording.

> Platform: Web only

Returns: Promise<{ properties: any; }>

getFeatureFlagVariant(...)

getFeatureFlagVariant(options: FeatureFlagOptions) => Promise<FeatureFlagVariantResult>

Get the variant for a feature flag.

> Platform: Web only

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | FeatureFlagOptions |

Returns: Promise<FeatureFlagVariantResult>

getFeatureFlagValue(...)

getFeatureFlagValue(options: FeatureFlagValueOptions) => Promise<{ value: any; }>

Get the value of a feature flag variant.

> Platform: Web only

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | FeatureFlagValueOptions |

Returns: Promise<{ value: any; }>

isFeatureFlagEnabled(...)

isFeatureFlagEnabled(options: FeatureFlagEnabledOptions) => Promise<{ value: boolean; }>

Check if a feature flag is enabled.

> Platform: Web only

| Param | Type | | ------------- | ------------------------------------------------------------------------------- | | options | FeatureFlagEnabledOptions |

Returns: Promise<{ value: boolean; }>

areFlagsReady()

areFlagsReady() => Promise<{ value: boolean; }>

Check if feature flags have been fetched and are ready.

> Platform: Web only

Returns: Promise<{ value: boolean; }>

updateFeatureFlagContext(...)

updateFeatureFlagContext(options: FeatureFlagContextOptions) => Promise<void>

Update the context variables used for feature flag evaluation.

> Platform: Web only

| Param | Type | | ------------- | ------------------------------------------------------------------------------- | | options | FeatureFlagContextOptions |

Interfaces

InitializeOptions

| Prop | Type | Description | Default | | ---------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | | token | string | Your Mixpanel API token | | | autotrack | boolean | Enable or disable autotracking | true | | optOutByDefault | boolean | Opting users out of tracking by this Mixpanel instance by default | false | | debug | boolean | Enable or disable debug mode | false | | ipCollection | boolean | Enable or disable IP collection for geolocation | true | | serverURL | string | Mixpanel cluster URL or EU server URL | null | | persistence | 'cookie' | 'localStorage' | [WebOnly] Type of persistence store for super properties if set to 'localStorage', any existing mixapanel cookie value with the same persistence_name will be transferred to localStorage and deleted | 'cookie' | | track_pageview | boolean | [WebOnly] Enable automatic page view tracking using default page view events through the track_pageview() method. | false | | recordSessionsPercent | number | [WebOnly] Percentage of sessions to record (0-100). Set to a value > 0 to enable session recording. | 0 | | recordBlockClass | string | [WebOnly] CSS class name to block from session recording | 'mp-block' | | recordBlockSelector | string | [WebOnly] CSS selector to block from session recording | | | recordMaskTextClass | string | [WebOnly] CSS class name to mask text in session recording | 'mp-mask' | | recordMaskTextSelector | string | [WebOnly] CSS selector to mask text in session recording | | | recordCollectFonts | boolean | [WebOnly] Whether to collect fonts during session recording | false | | recordIdleTimeoutMs | number | [WebOnly] Idle timeout in milliseconds before stopping recording | 300000 | | recordMaxMs | number | [WebOnly] Maximum recording length in milliseconds | 1800000 | | recordMinMs | number | [WebOnly] Minimum recording length in milliseconds before sending | | | recordCanvas | boolean | [WebOnly] Whether to record canvas elements | false | | recordHeatmapData | boolean | [WebOnly] Whether to capture click events for heatmaps | false | | recordConsole | boolean | [WebOnly] Whether to include console logs in session recordings | false | | autocapture | boolean | AutocaptureOptions | [WebOnly] Enable autocapture for automatic tracking of clicks, form submissions, page views, and scrolls. Pass true to enable with defaults, or an AutocaptureOptions object to customize. | false | | flags | { context?: Record<string, any>; } | [WebOnly] Enable feature flags with optional context variables. | |

AutocaptureOptions

| Prop | Type | Description | Default | | ------------------------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------- | | click | boolean | Track element clicks | true | | input | boolean | Track when input is provided (not content) | true | | pageview | boolean | 'url-with-path' | 'url-with-path-and-query-string' | 'full-url' | Track page views. Set to true or a string format. | 'full-url' | | submit | boolean | Track form submissions | true | | scroll | boolean | Track page scrolls | true | | rageClick | boolean | RageClickOptions | Track rage clicks (multiple clicks in a short time on the same element) | true | | captureTextContent | boolean | Capture text content of clicked elements | false |

RageClickOptions

| Prop | Type | Description | Default | | ----------------- | ------------------- | ----------------------------------------------------------------------------- | ----------------- | | thresholdPx | number | Distance threshold in pixels for clicks to be considered within the same area | 30 | | timeoutMs | number | Time window in milliseconds for clicks to be considered rapid | 1000 | | clickCount | number | Number of clicks required to trigger a rage click event | 3 |

TrackOptions

| Prop | Type | Description | Default | | ---------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------- | | event | string | The name of the event. This can be anything the user does - 'Button Click', 'Sign Up', 'Item Purchased', etc. | | | properties | TrackProperties | A set of properties to include with the event you're sending. These describe the user who did the event or details about the event itself. | {} |

TrackProperties

IdentifyOptions

| Prop | Type | Description | | ---------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | distinctId | string | A string that uniquely identifies a user. If not provided, the distinct_id currently in the persistent store (cookie or localStorage) will be used. |

AliasOptions

| Prop | Type | Description | | ---------------- | ------------------- | --------------------------------------------------------------------- | | alias | string | A unique identifier that you want to use for this user in the future. | | distinctId | string | The current identifier being used for this user. |

SuperPropertyOptions

| Prop | Type | Description | | ---------------- | ---------------- | ---------------------------------------------------------- | | properties | any | An associative array of properties to store about the user |

ProfileProperties

| Prop | Type | Description | | ---------------- | ---------------- | ---------------------------------------------------------- | | properties | any | An associative array of properties to store about the user |

ChargeOptions

| Prop | Type | Description | Default | | ---------------- | ------------------- | ----------------------------------------------------------------- | --------------- | | amount | number | The amount of the transaction | | | properties | any | An associative array of properties to store about the transaction | {} |

OptInOptions

| Prop | Type | Description | | ---------------- | ------------------- | ---------------------------------------------------------- | | distinctId | string | String that uniquely identifies the current user. | | properties | any | An associative array of properties to store about the user |

FeatureFlagVariantResult

| Prop | Type | | ----------- | ------------------- | | key | string | | value | any |

FeatureFlagOptions

| Prop | Type | Description | | -------------- | ------------------- | --------------------------------------------- | | name | string | The name of the feature flag | | fallback | string | Fallback variant key if the flag is not found |

FeatureFlagValueOptions

| Prop | Type | Description | | ------------------- | ------------------- | --------------------------------------- | | name | string | The name of the feature flag | | fallbackValue | any | Fallback value if the flag is not found |

FeatureFlagEnabledOptions

| Prop | Type | Description | Default | | ------------------- | -------------------- | --------------------------------------- | ------------------ | | name | string | The name of the feature flag | | | fallbackValue | boolean | Fallback value if the flag is not found | false |

FeatureFlagContextOptions

| Prop | Type | Description | Default | | ------------- | ------------------------------------------------------------ | ------------------------------------------------------ | ------------------ | | context | Record<string, any> | Context variables for feature flag evaluation | | | replace | boolean | If true, replace the entire context instead of merging | false |

Type Aliases

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }