Questa guida illustra l’installazione e l’utilizzo dell’SDK Clickstream di SurveyAnalytica sulle piattaforme mobili: React Native, Flutter, iOS (Swift) e Android (Kotlin). Per i progetti web, consulta la guida all’SDK Web.

Prima di iniziare, completa la configurazione del workflow per ottenere la tua API Key e l’URL dell’Endpoint.

React Native

Installazione

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

Inizializzazione

Chiama init una sola volta all’avvio dell’app, prima che venga eseguito il rendering di qualsiasi navigazione:

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

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

Tracciamento di schermate ed eventi

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

Installazione

flutter pub add sa_clickstream

Inizializzazione

Chiama initialize in main() prima di 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());
}

Tracciamento automatico delle schermate

Aggiungi SARouteObserver alla tua MaterialApp per tracciare automaticamente le transizioni tra schermate:

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

Tracciamento di eventi e identificazione degli utenti

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

---

iOS (Swift)

Installazione

Swift Package Manager — in Xcode vai su File → Add Package Dependencies e inserisci:

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

Seleziona la versione 1.0.0 o successiva.

CocoaPods — aggiungi al tuo Podfile:

pod 'SAClickstream', '~> 1.0'

Quindi esegui pod install.

Inizializzazione

Chiama initialize nel tuo AppDelegate o nella struct @main prima che appaia la prima scena:

import SAClickstream

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

Tracciamento di schermate ed eventi

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

Installazione

Aggiungi il repository GitHub Packages e la dipendenza al tuo 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")
}

Inizializzazione

Chiama initialize nel tuo 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"
        )
    }
}

Tracciamento di schermate ed eventi

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

Come vengono inviati gli eventi (tutte le piattaforme)

Su tutte le piattaforme l’SDK funziona allo stesso modo: gli eventi vengono accodati localmente e inviati ogni 500 millisecondi, oppure immediatamente quando si accumulano 20 eventi. Ogni invio effettua un’unica richiesta batch. Le richieste non riuscite vengono ritentate fino a tre volte con ritardi crescenti. L’identità anonima assegnata al primo avvio viene mantenuta tra le sessioni, così gli utenti restano identificati in modo coerente finché non chiami identify.

Risoluzione dei problemi

Gli eventi non compaiono nel mio workflow

• Verifica che il workflow sia in stato Active su SurveyAnalytica.
• Controlla i log del tuo dispositivo o simulatore per eventuali errori di rete.
• Verifica che l’API Key corrisponda esattamente alla KEY nel trigger drawer.
• Assicurati che initialize / init venga chiamato prima di qualsiasi chiamata di tracciamento.

Android: dipendenza non trovata

L’SDK Android viene distribuito tramite GitHub Packages. Assicurati che il tuo gradle.properties o l’ambiente CI includano un gpr.user e un gpr.token validi (un personal access token GitHub con permesso read:packages).