Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

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

Nutze dann diesen Prompt:

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

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

bun add @capgo/capacitor-rudderstack
bunx cap sync

Importieren

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

Quickstart

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

await nativePlugin.initialize({
  writeKey: 'YOUR_WRITE_KEY',
  dataPlaneUrl: 'https://your.dataplane.rudderstack.com',
});
await nativePlugin.identify({ userId: 'user_123', traits: { plan: 'pro' } });
await nativePlugin.track({ event: 'Signed Up', properties: { source: 'mobile' } });

Beispiel: Screen-Tracking

await nativePlugin.screen({
  screen: 'Checkout',
  properties: { step: 'payment' },
});

Häufige Stolperfallen

• Einmalige Initialisierung: wiederholte initialize() Aufrufe können den SDK Status duplizieren; schütze dies durch dein App-Bootstrap.
• Vor dem Hintergrundmodus leeren: aufrufen flush() wenn iOS oder Android deinen Prozess während eines Uploads unterbrechen könnten.
• Advertising IDs: Opt-in-Helfer nur nutzen, wenn deine Datenschutzerklärung die Erfassung von IDFA oder GAID abdeckt.

API Übersicht

initialize

Initialisiert den RudderStack-Client.

Die Methode behält die Cordova-Signatur bei, sodass das zweite Argument entweder ein Config-Objekt oder ein Rudder-Options-Objekt sein kann.

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

await nativePlugin.initialize('write-key-123');

identify

Sendet einen identify-Call für die angegebene User-ID.

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

await nativePlugin.identify('user-id-123');

group

Sendet einen group-Call für die angegebene Group-ID.

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

await nativePlugin.group('group-id-123');

track

Sendet einen track-Call für den angegebenen Event-Namen.

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

await nativePlugin.track('event');

screen

Sendet einen screen-Call für den angegebenen Screen-Namen.

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

await nativePlugin.screen('screen');

alias

Setzt einen Alias für den aktuellen User auf eine neue ID.

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

await nativePlugin.alias('new-id-123');

reset

Setzt den aktuellen RudderStack-Identitätsstatus zurück.

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

await nativePlugin.reset();

flush

Flusht gepufferte Events sofort.

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

await nativePlugin.flush();

putDeviceToken

Setzt den Push-Token, den RudderStack an unterstützte Ziele weiterleitet.

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

await nativePlugin.putDeviceToken('device-token-123');

setAdvertisingId

Sieh dir die Source-Definitionen für den aktuellen Contract an.

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

await nativePlugin.setAdvertisingId('advertising-id-123');

putAdvertisingId

Setzt einen benutzerdefinierten Advertising-ID-Wert.

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

await nativePlugin.putAdvertisingId('advertising-id-123');

setAnonymousId

Sieh dir die Source-Definitionen für den aktuellen Contract an.

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

await nativePlugin.setAnonymousId('anonymous-id-123');

putAnonymousId

Setzt einen benutzerdefinierten anonymen ID-Wert.

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

await nativePlugin.putAnonymousId('anonymous-id-123');

optOut

Schaltet das Opt-out für das RudderStack-Tracking um.

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

await nativePlugin.optOut(true);

Typreferenz

RudderConfiguration

Unterstützte Konfigurationsschlüssel für die zugrunde liegenden 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 Optionen pro Aufruf.

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

Akzeptiertes Traits-Payload von identify und group.

export type RudderTraits = Record<string, any>;

RudderProperties

Akzeptiertes Properties-Payload von track und screen.

export type RudderProperties = Record<string, any>;

PluginVersionResult

Payload der Plugin-Version.

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

RudderLogLevelValue

RudderStack Log-Level-Werte für eine einfache Migration.

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

Source of Truth

Diese Seite wird aus dem Plugin generiert src/definitions.ts. Führe den Sync erneut aus, wenn sich das öffentliche API upstream ändert.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte um Dashboard- und API-Operationen zu planen, verbinde es mit @capgo/capacitor-rudderstack verwenden für die native Funktionalität in „@capgo/capacitor-rudderstack verwenden“, API Übersicht für Details zur Implementierung im API Overview, Einführung für die Implementierungsdetails in der Einleitung, API Schlüssel für das Implementierungsdetail in API Keys und Geräte für das Implementierungsdetail in Devices.