Ce guide explique comment installer et utiliser le SDK Clickstream de SurveyAnalytica sur les plateformes mobiles : React Native, Flutter, iOS (Swift) et Android (Kotlin). Pour les projets web, consultez le guide du SDK Web.

Avant de commencer, effectuez la configuration du workflow pour obtenir votre clé API et votre URL de point de terminaison.

React Native

Installation

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

Initialisation

Appelez init une seule fois au démarrage de votre application, avant le rendu de toute navigation :

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

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

Suivre les écrans et les événements

// Vue d'écran (à appeler depuis useEffect dans chaque composant d'écran)
SAClickstream.page('ProductDetailScreen');

// Événement personnalisé
SAClickstream.track('add_to_cart', { productId: 'sku-9821', quantity: 2 });

// Identifier après connexion
SAClickstream.identify('contact-id-from-your-backend');

// Révoquer le consentement
SAClickstream.setConsent(false);

---

Flutter

Installation

flutter pub add sa_clickstream

Initialisation

Appelez initialize dans main() avant 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());
}

Suivi automatique des écrans

Ajoutez SARouteObserver à votre MaterialApp pour suivre automatiquement les transitions d’écran :

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

Suivre les événements et identifier les utilisateurs

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 — dans Xcode, allez dans File → Add Package Dependencies et saisissez :

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

Sélectionnez la version 1.0.0 ou ultérieure.

CocoaPods — ajoutez à votre Podfile :

pod 'SAClickstream', '~> 1.0'

Puis exécutez pod install.

Initialisation

Appelez initialize dans votre AppDelegate ou votre structure @main avant l’apparition de la première scène :

import SAClickstream

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

Suivre les écrans et les événements

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

// Événement personnalisé
SAClickstream.track("button_tapped", properties: ["label": "Buy Now"])

// Identifier après connexion
SAClickstream.identify("contact-id-from-your-backend")

// Révoquer le consentement
SAClickstream.setConsent(false)

---

Android (Kotlin)

Installation

Ajoutez le dépôt GitHub Packages et la dépendance à votre 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")
}

Initialisation

Appelez initialize dans votre 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"
        )
    }
}

Suivre les écrans et les événements

// Dans Activity.onResume ou Fragment.onResume
SAClickstream.page("ProductDetailActivity")

// Événement personnalisé
SAClickstream.track("button_tapped", mapOf("label" to "Buy Now"))

// Identifier après connexion
SAClickstream.identify("contact-id-from-your-backend")

// Révoquer le consentement
SAClickstream.setConsent(false)

Comment les événements sont envoyés (toutes plateformes)

Sur toutes les plateformes, le SDK fonctionne de la même manière : les événements sont mis en file d’attente localement et transmis toutes les 500 millisecondes, ou immédiatement lorsque 20 événements se sont accumulés. Chaque transmission envoie une seule requête groupée. Les requêtes échouées sont retentées jusqu’à trois fois avec des délais croissants. L’identité anonyme attribuée au premier lancement est conservée entre les sessions afin que les utilisateurs soient identifiés de manière cohérente jusqu’à ce que vous appeliez identify.

Dépannage

Les événements n’apparaissent pas dans mon workflow

• Confirmez que le workflow est à l’état Actif dans SurveyAnalytica.
• Vérifiez les journaux de votre appareil ou simulateur pour détecter d’éventuelles erreurs réseau.
• Vérifiez que la clé API correspond exactement à la KEY dans le tiroir de déclenchement.
• Assurez-vous que initialize / init est appelé avant tout appel de suivi.

Android : dépendance introuvable

Le SDK Android est distribué via GitHub Packages. Assurez-vous que votre fichier gradle.properties ou votre environnement CI inclut un gpr.user et un gpr.token valides (un jeton d’accès personnel GitHub avec la permission read:packages).