feat: add session tracking (#7)

Co-authored-by: 박건우 <gunwoo@baggeon-uui-MacBookPro.local>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.4] - 2026-02-12
+
+### Added
+
+- Session tracking with automatic SESSION_START lifecycle events
+
 ## [0.0.3] - 2025-12-01
 
 ### Added

lib/src/core/clix.dart

@@ -6,6 +6,7 @@ import '../services/device_service.dart';
 import '../services/event_api_service.dart';
 import '../services/event_service.dart';
 import '../services/notification_service.dart';
+import '../services/session_service.dart';
 import '../services/storage_service.dart';
 import '../services/token_service.dart';
 import '../utils/clix_error.dart';
@@ -31,6 +32,7 @@ class Clix {
   StorageService? _storageService;
   EventService? _eventService;
   DeviceService? _deviceService;
+  SessionService? _sessionService;
   NotificationService? _notificationService;
 
   Clix._();
@@ -101,14 +103,25 @@ class Clix {
       deviceService: _deviceService!,
     );
 
+    // Initialize session service
+    _sessionService = SessionService(
+      storageService: _storageService!,
+      eventService: _eventService!,
+      sessionTimeoutMs: config.sessionTimeoutMs,
+    );
+
     // Initialize notification service
     _notificationService = NotificationService();
     await _notificationService!.initialize(
       eventService: _eventService!,
       storageService: _storageService!,
       deviceService: _deviceService!,
       tokenService: tokenService,
+      sessionService: _sessionService,
     );
+
+    // Start session (after notification service so initial notification can set pendingMessageId)
+    await _sessionService!.start();
   }
 
   /// Wait for initialization with timeout protection

lib/src/core/clix_config.dart

@@ -10,13 +10,15 @@ class ClixConfig {
   final String endpoint;
   final ClixLogLevel logLevel;
   final Map<String, String>? extraHeaders;
+  final int sessionTimeoutMs;
 
   const ClixConfig({
     required this.projectId,
     required this.apiKey,
     this.endpoint = 'https://api.clix.so',
     this.logLevel = ClixLogLevel.error,
     this.extraHeaders,
+    this.sessionTimeoutMs = 30000,
   });
 
   Map<String, dynamic> toJson() => _$ClixConfigToJson(this);

lib/src/core/clix_config.g.dart

@@ -17,6 +17,7 @@ import '../services/event_api_service.dart';
 import '../utils/logging/clix_logger.dart';
 import 'device_service.dart';
 import 'event_service.dart';
+import 'session_service.dart';
 import 'storage_service.dart';
 import 'token_service.dart';
 
@@ -41,6 +42,7 @@ class NotificationService {
   StorageService? _storageService;
   DeviceService? _deviceService;
   TokenService? _tokenService;
+  SessionService? _sessionService;
 
   bool _isInitialized = false;
   String? _currentToken;
@@ -53,6 +55,7 @@ class NotificationService {
     required StorageService storageService,
     DeviceService? deviceService,
     TokenService? tokenService,
+    SessionService? sessionService,
     Function(Map<String, dynamic>)? onPushReceived,
     Function(Map<String, dynamic>)? onPushTapped,
   }) async {
@@ -62,14 +65,15 @@ class NotificationService {
     _storageService = storageService;
     _deviceService = deviceService;
     _tokenService = tokenService;
+    _sessionService = sessionService;
     this.onPushReceived = onPushReceived;
     this.onPushTapped = onPushTapped;
 
     try {
       ClixLogger.info('Initializing notification service');
 
       await _initializeLocalNotifications();
-      _setupMessageHandlers();
+      await _setupMessageHandlers();
       await _getAndUpdateTokenIfPermitted();
       _firebaseMessaging.onTokenRefresh.listen(_onTokenRefresh);
 
@@ -169,11 +173,11 @@ class NotificationService {
     return settings;
   }
 
-  void _setupMessageHandlers() {
+  Future<void> _setupMessageHandlers() async {
     FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);
     FirebaseMessaging.onMessage.listen(_onForegroundMessage);
     FirebaseMessaging.onMessageOpenedApp.listen(_onMessageOpenedApp);
-    _handleInitialMessage();
+    await _handleInitialMessage();
   }
 
   Future<void> _onForegroundMessage(RemoteMessage message) async {
@@ -343,6 +347,8 @@ class NotificationService {
     try {
       final clixPayload = parseClixPayload(userInfo);
       if (clixPayload != null) {
+        final messageId = clixPayload['message_id'] as String?;
+        _sessionService?.setPendingMessageId(messageId);
         await _trackPushEvent('PUSH_NOTIFICATION_TAPPED', clixPayload);
       }
       onPushTapped?.call(userInfo);

lib/src/services/notification_service.dart

@@ -0,0 +1,116 @@
+import 'package:flutter/widgets.dart';
+
+import '../utils/logging/clix_logger.dart';
+import 'event_service.dart';
+import 'storage_service.dart';
+
+enum SessionEvent {
+  sessionStart('SESSION_START');
+
+  final String value;
+  const SessionEvent(this.value);
+}
+
+class SessionService with WidgetsBindingObserver {
+  static const String _lastActivityKey = 'clix_session_last_activity';
+
+  final StorageService _storageService;
+  final EventService _eventService;
+  final int _effectiveTimeoutMs;
+
+  String? _pendingMessageId;
+
+  SessionService({
+    required StorageService storageService,
+    required EventService eventService,
+    required int sessionTimeoutMs,
+  })  : _storageService = storageService,
+        _eventService = eventService,
+        _effectiveTimeoutMs = sessionTimeoutMs < 5000 ? 5000 : sessionTimeoutMs;
+
+  Future<void> start() async {
+    WidgetsBinding.instance.addObserver(this);
+
+    try {
+      final lastActivity = await _storageService.get<int>(_lastActivityKey);
+      if (lastActivity != null) {
+        final elapsed = DateTime.now().millisecondsSinceEpoch - lastActivity;
+        if (elapsed <= _effectiveTimeoutMs) {
+          _pendingMessageId = null;
+          await _updateLastActivity();
+          ClixLogger.debug('Continuing existing session');
+          return;
+        }
+      }
+      await _startNewSession();
+    } catch (e) {
+      ClixLogger.error('Failed to start session', e);
+    }
+  }
+
+  @override
+  void didChangeAppLifecycleState(AppLifecycleState state) {
+    if (state == AppLifecycleState.resumed) {
+      _onResumed();
+    } else if (state == AppLifecycleState.paused) {
+      _onPaused();
+    }
+  }
+
+  void setPendingMessageId(String? messageId) {
+    _pendingMessageId = messageId;
+  }
+
+  Future<void> _onResumed() async {
+    try {
+      // Small delay to allow notification tap handlers to set pendingMessageId
+      await Future.delayed(const Duration(milliseconds: 100));
+
+      final lastActivity = await _storageService.get<int>(_lastActivityKey);
+      if (lastActivity != null) {
+        final elapsed = DateTime.now().millisecondsSinceEpoch - lastActivity;
+        if (elapsed <= _effectiveTimeoutMs) {
+          _pendingMessageId = null;
+          await _updateLastActivity();
+          return;
+        }
+      }
+      await _startNewSession();
+    } catch (e) {
+      ClixLogger.error('Failed to handle app resumed', e);
+    }
+  }
+
+  Future<void> _onPaused() async {
+    try {
+      await _updateLastActivity();
+    } catch (e) {
+      ClixLogger.error('Failed to handle app paused', e);
+    }
+  }
+
+  Future<void> _startNewSession() async {
+    final messageId = _pendingMessageId;
+    _pendingMessageId = null;
+    await _updateLastActivity();
+
+    try {
+      await _eventService.trackEvent(
+        SessionEvent.sessionStart.value,
+        messageId: messageId,
+      );
+      ClixLogger.debug('${SessionEvent.sessionStart.value} tracked');
+    } catch (e) {
+      ClixLogger.error('Failed to track ${SessionEvent.sessionStart.value}', e);
+    }
+  }
+
+  void cleanup() {
+    WidgetsBinding.instance.removeObserver(this);
+  }
+
+  Future<void> _updateLastActivity() async {
+    await _storageService.set<int>(
+        _lastActivityKey, DateTime.now().millisecondsSinceEpoch);
+  }
+}

lib/src/services/session_service.dart

@@ -1,7 +1,7 @@
 name: clix_flutter
 description: Clix - Clix - Mobile push for builders
 
-version: 0.0.3
+version: 0.0.4
 homepage: https://clix.so
 repository: https://github.com/clix-so/clix-flutter-sdk