Getting Started

Copy a setup prompt with the install steps and the full markdown guide for this plugin.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-rudderstack`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/rudderstack/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

Install

bun add @capgo/capacitor-rudderstack
bunx cap sync

Import

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

API Overview

`initialize`

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.

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

await nativePlugin.initialize('value');

`identify`

Sends an identify call for the provided user id.

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

await nativePlugin.identify('value');

`group`

Sends a group call for the provided group id.

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

await nativePlugin.group('value');

`track`

Sends a track call for the provided event name.

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

await nativePlugin.track('value');

`screen`

Sends a screen call for the provided screen name.

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

await nativePlugin.screen('value');

`alias`

Aliases the current user to a new identifier.

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

await nativePlugin.alias('value');

`reset`

Resets the current RudderStack identity state.

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

await nativePlugin.reset();

`flush`

Flushes queued events immediately.

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

await nativePlugin.flush();

`putDeviceToken`

Sets the push token that RudderStack forwards to supported destinations.

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

await nativePlugin.putDeviceToken('value');

`setAdvertisingId`

See the source definitions for the current contract.

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

await nativePlugin.setAdvertisingId('value');

`putAdvertisingId`

Sets a custom advertising id value.

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

await nativePlugin.putAdvertisingId('value');

`setAnonymousId`

See the source definitions for the current contract.

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

await nativePlugin.setAnonymousId('value');

`putAnonymousId`

Sets a custom anonymous id value.

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

await nativePlugin.putAnonymousId('value');

`optOut`

Toggles RudderStack tracking opt-out.

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

await nativePlugin.optOut(true);

Type Reference

`RudderConfiguration`

Supported configuration keys for the underlying RudderStack native SDKs.

export interface RudderConfiguration {
  /**
   * RudderStack data plane URL.
   */
  dataPlaneUrl?: string;

  /**
   * Number of events to batch before a flush.
   */
  flushQueueSize?: number;

  /**
   * Database row threshold that triggers pruning on Android and iOS.
   */
  dbCountThreshold?: number;

  /**
   * Server config refresh interval in hours.
   */
  configRefreshInterval?: number;

  /**
   * RudderStack log verbosity.
   */
  logLevel?: RudderLogLevelValue;

  /**
   * Sleep timeout / sleep count used by the native SDK.
   */
  sleepTimeOut?: number;

  /**
   * Android only. Lets the native SDK collect the advertising identifier automatically.
   */
  autoCollectAdvertId?: boolean;

  /**
   * Tracks `Application Installed`, `Application Updated`, and `Application Opened` automatically.
   */
  trackLifecycleEvents?: boolean;

  /**
   * RudderStack control plane URL.
   */
  controlPlaneUrl?: string;

  /**
   * Enables automatic screen tracking where supported by the native SDK.
   */
  recordScreenViews?: boolean;

  /**
   * 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.
   */
  factories?: any[];
}

`RudderOptions`

RudderStack per-call options.

export interface RudderOptions {
  /**
   * External identifiers forwarded with the event.
   */
  externalIds?: Record<string, string>;

  /**
   * Destination enablement flags keyed by integration name.
   */
  integrations?: Record<string, boolean>;
}

`RudderTraits`

Traits payload accepted by identify and group.

export type RudderTraits = Record<string, any>;

`RudderProperties`

Properties payload accepted by track and screen.

export type RudderProperties = Record<string, any>;

`PluginVersionResult`

Plugin version payload.

export interface PluginVersionResult {
  /**
   * Version identifier returned by the platform implementation.
   */
  version: string;
}

`RudderLogLevelValue`

RudderStack log level values exposed for migration convenience.

export type RudderLogLevelValue = 0 | 1 | 2 | 3 | 4 | 5;

Source Of Truth

This page is generated from the plugin’s src/definitions.ts. Re-run the sync when the public API changes upstream.

Keep going from Getting Started

If you are using Getting Started to plan dashboard and API operations, connect it with Using @capgo/capacitor-rudderstack for the native capability in Using @capgo/capacitor-rudderstack, API Overview for the implementation detail in API Overview, Introduction for the implementation detail in Introduction, API Keys for the implementation detail in API Keys, and Devices for the implementation detail in Devices.