Dieser Leitfaden beschreibt die Installation und Verwendung des SurveyAnalytica Clickstream SDK auf mobilen Plattformen: React Native, Flutter, iOS (Swift) und Android (Kotlin). Für Web-Projekte siehe den Web-SDK-Leitfaden.

Bevor Sie beginnen, schließen Sie das Workflow-Setup ab, um Ihren API-Schlüssel und Ihre Endpoint-URL zu erhalten.

React Native

Installation

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

Initialisieren

Rufen Sie init einmal beim Start Ihrer App auf, bevor jegliche Navigation gerendert wird:

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

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

Bildschirme und Ereignisse tracken

// 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

Installation

flutter pub add sa_clickstream

Initialisieren

Rufen Sie initialize in main() auf, bevor runApp aufgerufen wird:

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

Automatisches Screen-Tracking

Fügen Sie SARouteObserver zu Ihrer MaterialApp hinzu, um Bildschirmübergänge automatisch zu verfolgen:

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

Ereignisse tracken und Nutzer identifizieren

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

---

iOS (Swift)

Installation

Swift Package Manager — gehen Sie in Xcode zu File → Add Package Dependencies und geben Sie Folgendes ein:

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

Wählen Sie Version 1.0.0 oder höher.

CocoaPods — fügen Sie Folgendes zu Ihrem Podfile hinzu:

pod 'SAClickstream', '~> 1.0'

Führen Sie anschließend pod install aus.

Initialisieren

Rufen Sie initialize in Ihrem AppDelegate oder @main-Struct auf, bevor die erste Szene erscheint:

import SAClickstream

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

Bildschirme und Ereignisse tracken

// 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)

Installation

Fügen Sie das GitHub-Packages-Repository und die Abhängigkeit zu Ihrer build.gradle.kts hinzu:

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")
}

Initialisieren

Rufen Sie initialize in Ihrer Application.onCreate() auf:

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"
        )
    }
}

Bildschirme und Ereignisse tracken

// 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)

Wie Ereignisse gesendet werden (alle Plattformen)

Auf allen Plattformen funktioniert das SDK auf dieselbe Weise: Ereignisse werden lokal in eine Warteschlange gestellt und alle 500 Millisekunden gesendet, oder sofort, wenn sich 20 Ereignisse angesammelt haben. Jeder Flush sendet eine einzelne Batch-Anfrage. Fehlgeschlagene Anfragen werden bis zu dreimal mit zunehmenden Verzögerungen wiederholt. Die beim ersten Start zugewiesene anonyme Identität bleibt über Sitzungen hinweg erhalten, sodass Nutzer konsistent identifiziert werden, bis Sie identify aufrufen.

Fehlerbehebung

Ereignisse erscheinen nicht in meinem Workflow

• Stellen Sie sicher, dass sich der Workflow in SurveyAnalytica im Status Active befindet.
• Überprüfen Sie die Logs Ihres Geräts oder Simulators auf Netzwerkfehler.
• Vergewissern Sie sich, dass der API-Schlüssel exakt mit dem KEY in der Trigger-Schublade übereinstimmt.
• Stellen Sie sicher, dass initialize / init vor allen Tracking-Aufrufen aufgerufen wird.

Android: Abhängigkeit nicht gefunden

Das Android-SDK wird über GitHub Packages verteilt. Stellen Sie sicher, dass Ihre gradle.properties oder CI-Umgebung einen gültigen gpr.user und gpr.token enthält (ein GitHub Personal Access Token mit read:packages-Berechtigung).