@capgo/capacitor-rudderstack

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: '[email protected]',
  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. |

Type Aliases

RudderLogLevelValue

RudderStack log level values exposed for migration convenience.

0 | 1 | 2 | 3 | 4 | 5

Record

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

{ [P in K]: T; }

RudderTraits

Traits payload accepted by identify and group.

Record<string, any>

RudderProperties

Properties payload accepted by track and screen.

Record<string, any>