Primeros pasos

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

bun add @capgo/capacitor-rudderstack
bunx cap sync

Importar

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

Inicio rápido

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' } });

Ejemplo: seguimiento de pantallas

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

Errores comunes

• Inicializa una vez: repetidas initialize() las llamadas pueden duplicar el estado de SDK, protégelo en el bootstrap de tu app.
• Limpiar antes de ir a segundo plano: llama a flush() cuando iOS o Android puedan suspender tu proceso durante un upload.
• IDs de publicidad: activa los helpers solo si tu política de privacidad cubre la recopilación de IDFA o GAID.

Resumen de API

initialize

Inicializa el cliente de RudderStack.

El método mantiene la firma de Cordova, por lo que el segundo argumento puede ser un objeto de configuración o un objeto de opciones de Rudder.

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

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

identify

Envía una llamada identify para el user id proporcionado.

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

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

group

Envía una llamada group para el group id proporcionado.

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

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

track

Envía una llamada track para el nombre de evento proporcionado.

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

await nativePlugin.track('event');

screen

Envía una llamada screen para el nombre de pantalla proporcionado.

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

await nativePlugin.screen('screen');

alias

Crea un alias del usuario actual con un nuevo identificador.

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

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

reset

Restablece el estado de identidad actual de RudderStack.

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

await nativePlugin.reset();

flush

Envía inmediatamente los eventos en cola.

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

await nativePlugin.flush();

putDeviceToken

Configura el push token que RudderStack envía a los destinos compatibles.

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

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

setAdvertisingId

Consulta las definiciones en el código fuente para el contrato actual.

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

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

putAdvertisingId

Sets a custom advertising id value.

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

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

setAnonymousId

Consulta las definiciones en el código fuente para el contrato actual.

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

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

putAnonymousId

Establece un valor personalizado de ID anónimo.

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

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

optOut

Toggles RudderStack tracking opt-out.

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

await nativePlugin.optOut(true);

Referencia de tipos

RudderConfiguration

Claves de configuración compatibles para los SDK nativos de RudderStack.

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

Opciones de RudderStack por cada llamada.

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

Payload de traits aceptado por identify y group.

export type RudderTraits = Record<string, any>;

RudderProperties

Payload de properties aceptado por track y screen.

export type RudderProperties = Record<string, any>;

PluginVersionResult

Payload de la versión del plugin.

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

RudderLogLevelValue

Valores de nivel de log de RudderStack expuestos para facilitar la migración.

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

Fuente de verdad

Esta página se genera a partir del plugin src/definitions.ts. Vuelve a ejecutar el sync cuando el API público cambie en upstream.

Continúa desde Getting Started

Si estás usando Primeros pasos para planificar las operaciones del dashboard y de API, conéctalo con Uso de @capgo/capacitor-rudderstack para la capacidad nativa en Uso de @capgo/capacitor-rudderstack, Resumen de API para los detalles de implementación en API Overview, Introducción para los detalles de implementación en la Introducción, Claves de API para los detalles de implementación en las claves de API, y Dispositivos para el detalle de implementación en Devices.