feat: add session tracking (#25)

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).
 
+## [1.4.0] - 2026-02-12
+
+### Added
+
+- Session tracking with automatic SESSION_START lifecycle events
+
 ## [1.3.0] - 2026-01-15
 
 ### Added

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clix-so/react-native-sdk",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Clix - Mobile push for builders",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

src/core/Clix.ts

@@ -6,6 +6,7 @@ import { EventService } from '../services/EventService';
 import { LiveActivityAPIService } from '../services/LiveActivityAPIService';
 import { LiveActivityService } from '../services/LiveActivityService';
 import { NotificationService } from '../services/NotificationService';
+import { SessionService } from '../services/SessionService';
 import { StorageService } from '../services/StorageService';
 import { TokenService } from '../services/TokenService';
 import { ClixLogger, ClixLogLevel } from '../utils/logging/ClixLogger';
@@ -29,6 +30,7 @@ export class Clix {
   tokenService?: TokenService;
   eventService?: EventService;
   deviceService?: DeviceService;
+  sessionService?: SessionService;
   notificationService?: NotificationService;
   liveActivityService?: LiveActivityService;
 
@@ -68,10 +70,16 @@ export class Clix {
         eventApiService,
         this.shared.deviceService
       );
+      this.shared.sessionService = new SessionService(
+        this.shared.storageService,
+        this.shared.eventService,
+        config.sessionTimeoutMs ?? 30000
+      );
       this.shared.notificationService = new NotificationService(
         this.shared.deviceService,
         this.shared.tokenService,
-        this.shared.eventService
+        this.shared.eventService,
+        this.shared.sessionService
       );
       this.shared.liveActivityService = new LiveActivityService(
         this.shared.deviceService,
@@ -81,6 +89,7 @@ export class Clix {
       this.shared.storageService.set(this.configKey, config);
       this.shared.liveActivityService.initialize();
       await this.shared.notificationService.initialize(); // NOTE(nyanxyz): must be initialized before any await calls
+      await this.shared.sessionService.start();
       await this.shared.deviceService.initialize();
 
       ClixLogger.debug('Clix SDK initialized successfully');

src/core/ClixConfig.ts

@@ -6,4 +6,5 @@ export interface ClixConfig {
   endpoint: string;
   logLevel: ClixLogLevel;
   extraHeaders: Record<string, string>;
+  sessionTimeoutMs?: number;
 }

src/services/NotificationService.ts

@@ -19,6 +19,7 @@ import type { ClixPushNotificationPayload } from '../models/ClixPushNotification
 import { ClixLogger } from '../utils/logging/ClixLogger';
 import { DeviceService } from './DeviceService';
 import { EventService } from './EventService';
+import { SessionService } from './SessionService';
 import { TokenService } from './TokenService';
 
 type NotificationData = Record<string, any>;
@@ -66,7 +67,8 @@ export class NotificationService {
   constructor(
     private readonly deviceService: DeviceService,
     private readonly tokenService: TokenService,
-    private readonly eventService: EventService
+    private readonly eventService: EventService,
+    private readonly sessionService?: SessionService
   ) {}
 
   async initialize(): Promise<void> {
@@ -438,6 +440,7 @@ export class NotificationService {
     payload: ClixPushNotificationPayload
   ): Promise<void> {
     try {
+      this.sessionService?.setPendingMessageId(payload.messageId);
       await this.eventService.trackEvent(
         'PUSH_NOTIFICATION_TAPPED',
         {},

src/services/SessionService.ts

@@ -0,0 +1,103 @@
+import { AppState, type AppStateStatus } from 'react-native';
+import { ClixLogger } from '../utils/logging/ClixLogger';
+import type { EventService } from './EventService';
+import type { StorageService } from './StorageService';
+
+enum SessionEvent {
+  SESSION_START = 'SESSION_START',
+}
+
+export class SessionService {
+  private static readonly LAST_ACTIVITY_KEY = 'clix_session_last_activity';
+
+  private pendingMessageId?: string;
+  private readonly effectiveTimeoutMs: number;
+  private appStateSubscription?: { remove: () => void };
+  private lastAppState: AppStateStatus;
+
+  constructor(
+    private readonly storageService: StorageService,
+    private readonly eventService: EventService,
+    sessionTimeoutMs: number
+  ) {
+    this.effectiveTimeoutMs = Math.max(sessionTimeoutMs, 5000);
+    this.lastAppState = AppState.currentState;
+  }
+
+  async start(): Promise<void> {
+    this.appStateSubscription = AppState.addEventListener(
+      'change',
+      this.handleAppStateChange.bind(this)
+    );
+
+    const lastActivity = this.storageService.get<number>(
+      SessionService.LAST_ACTIVITY_KEY
+    );
+    if (lastActivity) {
+      const elapsed = Date.now() - lastActivity;
+      if (elapsed <= this.effectiveTimeoutMs) {
+        this.pendingMessageId = undefined;
+        this.updateLastActivity();
+        ClixLogger.debug('Continuing existing session');
+        return;
+      }
+    }
+    await this.startNewSession();
+  }
+
+  private async handleAppStateChange(
+    nextAppState: AppStateStatus
+  ): Promise<void> {
+    const previousAppState = this.lastAppState;
+    this.lastAppState = nextAppState;
+
+    if (previousAppState === 'background' && nextAppState === 'active') {
+      // Small delay to allow notification tap handlers to set pendingMessageId
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      const lastActivity = this.storageService.get<number>(
+        SessionService.LAST_ACTIVITY_KEY
+      );
+      if (lastActivity) {
+        const elapsed = Date.now() - lastActivity;
+        if (elapsed <= this.effectiveTimeoutMs) {
+          this.pendingMessageId = undefined;
+          this.updateLastActivity();
+          return;
+        }
+      }
+      await this.startNewSession();
+    } else if (nextAppState === 'background') {
+      this.updateLastActivity();
+    }
+  }
+
+  setPendingMessageId(messageId?: string): void {
+    this.pendingMessageId = messageId;
+  }
+
+  private async startNewSession(): Promise<void> {
+    const messageId = this.pendingMessageId;
+    this.pendingMessageId = undefined;
+    this.updateLastActivity();
+
+    try {
+      await this.eventService.trackEvent(
+        SessionEvent.SESSION_START,
+        {},
+        messageId
+      );
+      ClixLogger.debug(`${SessionEvent.SESSION_START} tracked`);
+    } catch (error) {
+      ClixLogger.error(`Failed to track ${SessionEvent.SESSION_START}`, error);
+    }
+  }
+
+  private updateLastActivity(): void {
+    this.storageService.set(SessionService.LAST_ACTIVITY_KEY, Date.now());
+  }
+
+  cleanup(): void {
+    this.appStateSubscription?.remove();
+  }
+}