Esta guía explica cómo instalar y usar el SDK de Clickstream de SurveyAnalytica en plataformas móviles: React Native, Flutter, iOS (Swift) y Android (Kotlin). Para proyectos web, consulta la guía del SDK web.

Antes de comenzar, completa la configuración del flujo de trabajo para obtener tu clave de API y la URL del endpoint.

React Native

Instalación

npm install @surveyanalytica/clickstream-rn @react-native-async-storage/async-storage

Inicializar

Llama a init una vez cuando se inicie tu app, antes de que se renderice cualquier navegación:

import { SAClickstream } from '@surveyanalytica/clickstream-rn';

await SAClickstream.init('YOUR_WORKFLOW_ID', 'YOUR_API_KEY', {
  endpoint: 'YOUR_ENDPOINT_URL'
});

Rastrear pantallas y eventos

// Screen view (call from useEffect in each screen component)
SAClickstream.page('ProductDetailScreen');

// Custom event
SAClickstream.track('add_to_cart', { productId: 'sku-9821', quantity: 2 });

// Identify after login
SAClickstream.identify('contact-id-from-your-backend');

// Revoke consent
SAClickstream.setConsent(false);

---

Flutter

Instalación

flutter pub add sa_clickstream

Inicializar

Llama a initialize en main() antes de runApp:

import 'package:sa_clickstream/sa_clickstream.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await SAClickstream.initialize(
    workflowId: 'YOUR_WORKFLOW_ID',
    apiKey: 'YOUR_API_KEY',
    saEndpoint: 'YOUR_ENDPOINT_URL',
  );
  runApp(const MyApp());
}

Seguimiento automático de pantallas

Agrega SARouteObserver a tu MaterialApp para rastrear las transiciones de pantalla automáticamente:

MaterialApp(
  navigatorObservers: [SARouteObserver()],
  ...
)

Rastrear eventos e identificar usuarios

SAClickstream.track('button_tapped', properties: {'label': 'Buy Now'});
SAClickstream.page('CheckoutScreen');
SAClickstream.identify('contact-id-from-your-backend');
SAClickstream.setConsent(false);

---

iOS (Swift)

Instalación

Swift Package Manager — en Xcode ve a File → Add Package Dependencies e ingresa:

https://github.com/aphougat/clickstream-ios

Selecciona la versión 1.0.0 o posterior.

CocoaPods — agrega a tu Podfile:

pod 'SAClickstream', '~> 1.0'

Luego ejecuta pod install.

Inicializar

Llama a initialize en tu AppDelegate o estructura @main antes de que aparezca la primera escena:

import SAClickstream

SAClickstream.initialize(
    workflowId: "YOUR_WORKFLOW_ID",
    apiKey: "YOUR_API_KEY",
    saEndpoint: "YOUR_ENDPOINT_URL"
)

Rastrear pantallas y eventos

// In viewDidAppear
SAClickstream.page("ProductDetailViewController")

// Custom event
SAClickstream.track("button_tapped", properties: ["label": "Buy Now"])

// Identify after login
SAClickstream.identify("contact-id-from-your-backend")

// Revoke consent
SAClickstream.setConsent(false)

---

Android (Kotlin)

Instalación

Agrega el repositorio de GitHub Packages y la dependencia a tu build.gradle.kts:

repositories {
    maven {
        url = uri("https://maven.pkg.github.com/aphougat/clickstream-android")
        credentials {
            username = providers.gradleProperty("gpr.user").orElse("").get()
            password = providers.gradleProperty("gpr.token").orElse("").get()
        }
    }
}

dependencies {
    implementation("com.surveyanalytica:clickstream-android:1.0.0")
}

Inicializar

Llama a initialize en tu Application.onCreate():

import com.surveyanalytica.clickstream.SAClickstream

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        SAClickstream.initialize(
            context = this,
            workflowId = "YOUR_WORKFLOW_ID",
            apiKey = "YOUR_API_KEY",
            saEndpoint = "YOUR_ENDPOINT_URL"
        )
    }
}

Rastrear pantallas y eventos

// In Activity.onResume or Fragment.onResume
SAClickstream.page("ProductDetailActivity")

// Custom event
SAClickstream.track("button_tapped", mapOf("label" to "Buy Now"))

// Identify after login
SAClickstream.identify("contact-id-from-your-backend")

// Revoke consent
SAClickstream.setConsent(false)

Cómo se envían los eventos (todas las plataformas)

En todas las plataformas el SDK funciona de la misma manera: los eventos se ponen en cola localmente y se envían cada 500 milisegundos, o inmediatamente cuando se acumulan 20 eventos. Cada envío realiza una única solicitud por lotes. Las solicitudes fallidas se reintentan hasta tres veces con retrasos crecientes. La identidad anónima asignada en el primer inicio se conserva entre sesiones, de modo que los usuarios se identifican de forma consistente hasta que llames a identify.

Solución de problemas

Los eventos no aparecen en mi flujo de trabajo

• Confirma que el flujo de trabajo esté en estado Activo en SurveyAnalytica.
• Revisa los registros de tu dispositivo o simulador en busca de errores de red.
• Verifica que la clave de API coincida exactamente con la KEY en el panel del disparador.
• Asegúrate de que initialize / init se llame antes de cualquier llamada de rastreo.

Android: no se encuentra la dependencia

El SDK de Android se distribuye a través de GitHub Packages. Asegúrate de que tu gradle.properties o entorno de CI incluya un gpr.user y gpr.token válidos (un token de acceso personal de GitHub con permiso read:packages).