@capgo/capacitor-rudderstack

June 16, 2026 · View on GitHub

➡️ Get Instant updates for your App with Capgo

Missing a feature? We’ll build the plugin for you 💪

Capacitor plugin for RudderStack analytics and event tracking.

This package is a Capacitor port of rudder-sdk-cordova with native Android and iOS bridges built for Capacitor 8.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/rudderstack/

Compatibility

Plugin version	Capacitor compatibility	Maintained
v8..	v8..	✅
v7..	v7..	On demand
v6..	v6..	❌

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation. Only the latest major version is actively maintained.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-rudderstack` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

bun add @capgo/capacitor-rudderstack
bunx cap sync

Usage

import { RudderStack } from '@capgo/capacitor-rudderstack';

await RudderStack.initialize('YOUR_WRITE_KEY', {
  dataPlaneUrl: 'https://your-dataplane.rudderstack.com',
  trackLifecycleEvents: true,
  logLevel: RudderStack.LogLevel.INFO,
});

await RudderStack.identify('user_123', {
  email: 'user@example.com',
  plan: 'pro',
});

await RudderStack.track('Checkout Started', {
  value: 49,
  currency: 'EUR',
});

The API intentionally follows the Cordova plugin shape so existing Rudder Cordova integrations can migrate with minimal call-site changes.

Behavior

Android uses the RudderStack Android SDK and exposes the Cordova-compatible analytics surface through a Capacitor bridge.
iOS uses the RudderStack iOS SDK with a Swift bridge that matches the same public API.
Web is a lightweight compatibility implementation intended for development and API parity. It does not send events to RudderStack.
config.factories from the Cordova plugin is currently ignored. Native destination factory companion plugins are not part of this first Capacitor port.

API

initialize(...)
identify(...)
group(...)
track(...)
screen(...)
alias(...)
reset()
flush()
putDeviceToken(...)
setAdvertisingId(...)
putAdvertisingId(...)
setAnonymousId(...)
putAnonymousId(...)
optOut(...)
getPluginVersion()
Interfaces
Type Aliases

Capacitor API that mirrors the public surface of rudder-sdk-cordova.

initialize(...)

initialize(writeKey: string, config?: RudderConfiguration | RudderOptions | undefined, options?: RudderOptions | undefined) => Promise<void>

Initializes the RudderStack client.

The method keeps the Cordova signature, so the second argument may be either a config object or a Rudder options object.

Param	Type
`writeKey`	`string`
`config`	`RudderConfiguration \| RudderOptions`
`options`	`RudderOptions`

identify(...)

identify(userId: string, traits?: RudderOptions | RudderTraits | undefined, options?: RudderOptions | undefined) => Promise<void>

Sends an identify call for the provided user id.

Param	Type
`userId`	`string`
`traits`	`RudderOptions \| RudderTraits`
`options`	`RudderOptions`

group(...)

group(groupId: string, groupTraits?: RudderOptions | RudderTraits | undefined, options?: RudderOptions | undefined) => Promise<void>

Sends a group call for the provided group id.

Param	Type
`groupId`	`string`
`groupTraits`	`RudderOptions \| RudderTraits`
`options`	`RudderOptions`

track(...)

track(eventName: string, properties?: RudderOptions | RudderProperties | undefined, options?: RudderOptions | undefined) => Promise<void>

Sends a track call for the provided event name.

Param	Type
`eventName`	`string`
`properties`	`RudderOptions \| RudderProperties`
`options`	`RudderOptions`

screen(...)

screen(screenName: string, properties?: RudderOptions | RudderProperties | undefined, options?: RudderOptions | undefined) => Promise<void>

Sends a screen call for the provided screen name.

Param	Type
`screenName`	`string`
`properties`	`RudderOptions \| RudderProperties`
`options`	`RudderOptions`

alias(...)

alias(newId: string, options?: RudderOptions | undefined) => Promise<void>

Aliases the current user to a new identifier.

Param	Type
`newId`	`string`
`options`	`RudderOptions`

reset()

reset() => Promise<void>

Resets the current RudderStack identity state.

flush()

flush() => Promise<void>

Flushes queued events immediately.

putDeviceToken(...)

putDeviceToken(deviceToken: string) => Promise<void>

Sets the push token that RudderStack forwards to supported destinations.

Param	Type
`deviceToken`	`string`

setAdvertisingId(...)

setAdvertisingId(advertisingId: string) => Promise<void>

Param	Type
`advertisingId`	`string`

putAdvertisingId(...)

putAdvertisingId(advertisingId: string) => Promise<void>

Sets a custom advertising id value.

Param	Type
`advertisingId`	`string`

setAnonymousId(...)

setAnonymousId(anonymousId: string) => Promise<void>

Param	Type
`anonymousId`	`string`

putAnonymousId(...)

putAnonymousId(anonymousId: string) => Promise<void>

Sets a custom anonymous id value.

Param	Type
`anonymousId`	`string`

optOut(...)

optOut(optOut: boolean) => Promise<void>

Toggles RudderStack tracking opt-out.

Param	Type
`optOut`	`boolean`

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the plugin version marker from the native implementation.

Returns: Promise<PluginVersionResult>

Interfaces

RudderConfiguration

Supported configuration keys for the underlying RudderStack native SDKs.

Prop	Type	Description
`dataPlaneUrl`	`string`	RudderStack data plane URL.
`flushQueueSize`	`number`	Number of events to batch before a flush.
`dbCountThreshold`	`number`	Database row threshold that triggers pruning on Android and iOS.
`configRefreshInterval`	`number`	Server config refresh interval in hours.
`logLevel`	`RudderLogLevelValue`	RudderStack log verbosity.
`sleepTimeOut`	`number`	Sleep timeout / sleep count used by the native SDK.
`autoCollectAdvertId`	`boolean`	Android only. Lets the native SDK collect the advertising identifier automatically.
`trackLifecycleEvents`	`boolean`	Tracks `Application Installed`, `Application Updated`, and `Application Opened` automatically.
`controlPlaneUrl`	`string`	RudderStack control plane URL.
`recordScreenViews`	`boolean`	Enables automatic screen tracking where supported by the native SDK.
`factories`	`any[]`	Ignored in this Capacitor port. The Cordova SDK uses this field to bootstrap native destination factories from companion plugins. Those extension packages are not implemented in this first Capacitor release.

RudderOptions

RudderStack per-call options.

Prop	Type	Description
`externalIds`	`Record<string, string>`	External identifiers forwarded with the event.
`integrations`	`Record<string, boolean>`	Destination enablement flags keyed by integration name.

PluginVersionResult

Plugin version payload.

Prop	Type	Description
`version`	`string`	Version identifier returned by the platform implementation.