@capgo/capacitor-rudderstack

Send analytics events and user identities to RudderStack from your Capacitor app with the native RudderStack SDKs. A Capacitor port of rudder-sdk-cordova.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-rudderstack in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-rudderstack to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Setup: initialize() with your write key and data plane URL.
• Tracking: track(), screen(), identify(), group() and alias().
• Identity: reset(), putAnonymousId(), putAdvertisingId() and putDeviceToken().
• Privacy and delivery: optOut() and flush().
• Easy migration: follows the Cordova plugin API shape.
• Platforms: iOS and Android. Uses the RudderStack iOS and Android SDKs. Web has API-compatible stubs that do not send events.

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

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.

identify(...)

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

Sends an identify call for the provided user id.

group(...)

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

Sends a group call for the provided group id.

track(...)

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

Sends a track call for the provided event name.

screen(...)

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

Sends a screen call for the provided screen name.

alias(...)

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

Aliases the current user to a new identifier.

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.

setAdvertisingId(...)

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

putAdvertisingId(...)

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

Sets a custom advertising id value.

setAnonymousId(...)

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

putAnonymousId(...)

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

Sets a custom anonymous id value.

optOut(...)

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

Toggles RudderStack tracking opt-out.

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.

RudderOptions

RudderStack per-call options.

PluginVersionResult

Plugin version payload.

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>