Это руководство описывает установку и использование SurveyAnalytica Clickstream SDK на мобильных платформах: React Native, Flutter, iOS (Swift) и Android (Kotlin). Для веб-проектов см. руководство по Web SDK.

Прежде чем начать, выполните настройку workflow, чтобы получить API Key и Endpoint URL.

React Native

Установка

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

Инициализация

Вызовите init один раз при запуске приложения, до отрисовки любой навигации:

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

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

Отслеживание экранов и событий

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

Установка

flutter pub add sa_clickstream

Инициализация

Вызовите initialize в main() перед 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());
}

Автоматическое отслеживание экранов

Добавьте SARouteObserver в ваш MaterialApp, чтобы автоматически отслеживать переходы между экранами:

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

Отслеживание событий и идентификация пользователей

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

---

iOS (Swift)

Установка

Swift Package Manager — в Xcode перейдите в File → Add Package Dependencies и введите:

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

Выберите версию 1.0.0 или новее.

CocoaPods — добавьте в ваш Podfile:

pod 'SAClickstream', '~> 1.0'

Затем выполните pod install.

Инициализация

Вызовите initialize в вашем AppDelegate или структуре @main до появления первой сцены:

import SAClickstream

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

Отслеживание экранов и событий

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

Установка

Добавьте репозиторий GitHub Packages и зависимость в ваш 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")
}

Инициализация

Вызовите initialize в вашем 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"
        )
    }
}

Отслеживание экранов и событий

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

Как отправляются события (все платформы)

На всех платформах SDK работает одинаково: события ставятся в локальную очередь и отправляются каждые 500 миллисекунд, либо немедленно, когда накопится 20 событий. Каждая отправка представляет собой один пакетный запрос. Неудачные запросы повторяются до трёх раз с увеличивающимися задержками. Анонимный идентификатор, присвоенный при первом запуске, сохраняется между сессиями, поэтому пользователи идентифицируются последовательно, пока вы не вызовете identify.

Устранение неполадок

События не появляются в моём workflow

• Убедитесь, что workflow находится в состоянии Active в SurveyAnalytica.
• Проверьте логи устройства или симулятора на наличие сетевых ошибок.
• Убедитесь, что API Key точно совпадает с KEY в панели триггера.
• Убедитесь, что initialize / init вызывается до любых вызовов отслеживания.

Android: зависимость не найдена

Android SDK распространяется через GitHub Packages. Убедитесь, что ваш gradle.properties или окружение CI содержит корректные gpr.user и gpr.token (персональный токен доступа GitHub с разрешением read:packages).