kewa-react-native 1.0.0

package/src/core/KewaAnalytics.ts

@@ -0,0 +1,419 @@
+import { AppState, AppStateStatus } from 'react-native';
+
+import {
+  KewaConfig,
+  DeviceInfo,
+  BaseEventData,
+  UserLoginEvent,
+  UserRegistrationEvent,
+  ScreenViewEvent,
+  ErrorEvent,
+  AppLaunchEvent,
+  ContactData,
+} from '../types';
+import { StorageManager } from '../utils/StorageManager';
+import { NetworkManager } from '../utils/NetworkManager';
+import { EventManager } from '../core/EventManager';
+import { DeviceInfoCollector } from '../utils/DeviceInfo';
+import { KEWA_CONSTANTS } from '../utils/constants';
+import { kewaDebug, setDebugLogging } from '../utils/debug';
+
+interface IdentityCache {
+  ktcId: string | null;
+  deviceId: string | null;
+  userProperties: ContactData;
+}
+
+export class KewaAnalytics {
+  private config: KewaConfig | null = null;
+  private networkManager: NetworkManager | null = null;
+  private eventManager: EventManager | null = null;
+  private isInitialized: boolean = false;
+  private deviceInfo: DeviceInfo | null = null;
+  private appStateSubscription: { remove: () => void } | null = null;
+  private hasLaunched: boolean = false;
+  private currentAppState: AppStateStatus = 'active';
+  private identityCache: IdentityCache = {
+    ktcId: null,
+    deviceId: null,
+    userProperties: {},
+  };
+
+  async init(config: KewaConfig): Promise<void> {
+    try {
+      this.config = this.normalizeConfig(config);
+      setDebugLogging(this.config.enableDebugLogging ?? false);
+
+      if (this.config.disableTracking) {
+        this.isInitialized = true;
+        kewaDebug('Kewa Analytics SDK initialized with tracking disabled');
+        return;
+      }
+
+      if (!this.config.projectId) {
+        throw new Error('Kewa Analytics SDK: projectId is required when tracking is enabled');
+      }
+
+      this.networkManager = new NetworkManager(
+        this.config.appUrl,
+        this.config.apiKey,
+        this.config.projectId,
+      );
+      this.eventManager = new EventManager(this.networkManager, this.config);
+      this.deviceInfo = await DeviceInfoCollector.collect();
+      await this.refreshIdentityCache();
+
+      if (!this.isAppStateTrackingDisabled() && !this.isInitialized) {
+        this.setupAppStateMonitoring();
+      }
+
+      await this.eventManager.processQueuedEvents();
+
+      this.isInitialized = true;
+      this.hasLaunched = true;
+
+      if (!this.isEventTrackingDisabled()) {
+        await this.trackAppLaunch();
+      }
+
+      kewaDebug('Kewa Analytics SDK initialized successfully');
+    } catch (error) {
+      console.warn('Failed to initialize Kewa Analytics SDK:', error);
+    }
+  }
+
+  private normalizeConfig(config: KewaConfig): KewaConfig {
+    const appUrl = config.appUrl ?? config.apiUrl;
+    if (!appUrl) {
+      throw new Error('Kewa Analytics SDK: appUrl is required');
+    }
+
+    return {
+      batchSize: KEWA_CONSTANTS.DEFAULTS.BATCH_SIZE,
+      maxQueueSize: KEWA_CONSTANTS.DEFAULTS.MAX_QUEUE_SIZE,
+      disableTracking: false,
+      disableEventTracking: false,
+      disableAppStateTracking: false,
+      disableScreenViewTracking: false,
+      enableDebugLogging: false,
+      ...config,
+      appUrl,
+    };
+  }
+
+  private isTrackingDisabled(): boolean {
+    return this.config?.disableTracking ?? false;
+  }
+
+  private isEventTrackingDisabled(): boolean {
+    return this.isTrackingDisabled() || (this.config?.disableEventTracking ?? false);
+  }
+
+  private isAppStateTrackingDisabled(): boolean {
+    return this.isTrackingDisabled() || (this.config?.disableAppStateTracking ?? false);
+  }
+
+  isAutoScreenViewTrackingEnabled(): boolean {
+    if (this.isTrackingDisabled() || this.isEventTrackingDisabled()) {
+      return false;
+    }
+    return !(this.config?.disableScreenViewTracking ?? false);
+  }
+
+  private async refreshIdentityCache(): Promise<void> {
+    const [ktcId, deviceId, userProperties] = await Promise.all([
+      StorageManager.getKtcId(),
+      StorageManager.getDeviceId(),
+      StorageManager.getUserProperties(),
+    ]);
+
+    this.identityCache = { ktcId, deviceId, userProperties };
+  }
+
+  private async trackAppLaunch(): Promise<void> {
+    const isFirstLaunch = !(await StorageManager.getDeviceId());
+
+    const launchData: AppLaunchEvent = {
+      ...this.deviceInfo,
+      isFirstLaunch,
+      timestamp: new Date().toISOString(),
+    };
+
+    await this.emitEvent(KEWA_CONSTANTS.EVENTS.APP_LAUNCH, launchData);
+  }
+
+  private setupAppStateMonitoring(): void {
+    this.appStateSubscription = AppState.addEventListener('change', (nextAppState: AppStateStatus) => {
+      if (!this.hasLaunched || this.currentAppState === nextAppState) {
+        return;
+      }
+
+      const previousState = this.currentAppState;
+      this.currentAppState = nextAppState;
+
+      if (nextAppState === 'active' && (previousState === 'background' || previousState === 'inactive')) {
+        void this.handleAppForeground();
+      } else if (nextAppState === 'background' && (previousState === 'active' || previousState === 'inactive')) {
+        // Fire immediately without awaiting — the OS may suspend the app before async work finishes
+        void this.handleAppBackground();
+      }
+    });
+  }
+
+  private async handleAppForeground(): Promise<void> {
+    this.backgroundEventPending = false;
+    await this.emitAppStateEvent(KEWA_CONSTANTS.EVENTS.APP_FOREGROUND);
+
+    if (this.eventManager) {
+      await this.eventManager.processQueuedEvents();
+    }
+  }
+
+  private backgroundEventPending = false;
+
+  private async handleAppBackground(): Promise<void> {
+    if (this.backgroundEventPending) {
+      return;
+    }
+
+    this.backgroundEventPending = true;
+
+    try {
+      await this.emitAppStateEvent(KEWA_CONSTANTS.EVENTS.APP_BACKGROUND);
+    } finally {
+      // Reset when app returns to foreground
+      if (AppState.currentState === 'active') {
+        this.backgroundEventPending = false;
+      }
+    }
+  }
+
+  private async emitAppStateEvent(eventName: string): Promise<void> {
+    if (this.isAppStateTrackingDisabled()) {
+      return;
+    }
+
+    if (!this.isInitialized || !this.eventManager || !this.deviceInfo) {
+      return;
+    }
+
+    const { ktcId, deviceId, userProperties } = this.identityCache;
+
+    await this.eventManager.processAppStateEvent(
+      eventName,
+      {
+        ...this.deviceInfo,
+        timestamp: new Date().toISOString(),
+      },
+      {
+        id: ktcId || undefined,
+        ...userProperties,
+      },
+      deviceId,
+      this.deviceInfo,
+    );
+
+    await this.refreshIdentityCache();
+  }
+
+  private async emitEvent(
+    eventName: string,
+    eventData: BaseEventData = {},
+    contactData?: ContactData,
+    options?: { identity?: IdentityCache; skipIdentityRefresh?: boolean },
+  ): Promise<void> {
+    if (!this.isInitialized) {
+      console.warn('Kewa Analytics SDK not initialized. Call init() first.');
+      return;
+    }
+
+    if (!this.eventManager || !this.deviceInfo) {
+      console.warn('Kewa Analytics SDK not properly initialized');
+      return;
+    }
+
+    const identity = options?.identity ?? this.identityCache;
+    const { ktcId, deviceId, userProperties } = identity;
+
+    await this.eventManager.processEvent(
+      eventName,
+      eventData,
+      {
+        id: ktcId || undefined,
+        ...userProperties,
+        ...contactData,
+      },
+      deviceId,
+      this.deviceInfo,
+    );
+
+    if (!options?.skipIdentityRefresh) {
+      await this.refreshIdentityCache();
+    }
+  }
+
+  async trackEvent(eventName: string, eventData: BaseEventData = {}, contactData?: ContactData): Promise<void> {
+    if (this.isEventTrackingDisabled()) {
+      return;
+    }
+
+    await this.emitEvent(eventName, eventData, contactData);
+  }
+
+  async setUserProperties(properties: ContactData): Promise<void> {
+    if (this.isTrackingDisabled()) {
+      return;
+    }
+
+    if (!this.networkManager) {
+      console.warn('Kewa Analytics SDK not properly initialized');
+      return;
+    }
+
+    const currentUserProperties = await StorageManager.getUserProperties();
+    const userProperties = { ...currentUserProperties, ...properties };
+    await StorageManager.setUserProperties(userProperties);
+
+    const contact: ContactData = {
+      ...properties,
+    };
+
+    await this.refreshIdentityCache();
+
+    if (!this.networkManager.getNetworkStatus()) {
+      kewaDebug('Offline — user properties saved locally only');
+      return;
+    }
+
+    try {
+      kewaDebug('Kewa Analytics SDK: Updating contact:', contact);
+
+      const response = await this.networkManager.updateContact(contact);
+      await this.applyIdentityFromResponse(response);
+
+      kewaDebug('Kewa Analytics SDK: Contact update response:', response);
+    } catch (error) {
+      console.warn('Kewa Analytics SDK: Failed to update contact on Kewa:', error);
+    }
+  }
+
+  private async applyIdentityFromResponse(response: { id?: string; device_id?: string }): Promise<void> {
+    const ktcId = await StorageManager.getKtcId();
+    const deviceId = await StorageManager.getDeviceId();
+
+    if (response.id && response.id !== ktcId) {
+      await StorageManager.setKtcId(response.id);
+    }
+
+    if (response.device_id && response.device_id !== deviceId) {
+      await StorageManager.setDeviceId(response.device_id);
+    }
+
+    await this.refreshIdentityCache();
+  }
+
+  async trackLogin(userData: Partial<UserLoginEvent>): Promise<void> {
+    const loginData: UserLoginEvent = {
+      loginMethod: 'custom',
+      ...userData,
+      userId: userData.userId || '',
+      timestamp: new Date().toISOString(),
+    };
+
+    await this.trackEvent(KEWA_CONSTANTS.EVENTS.USER_LOGIN, loginData);
+  }
+
+  async trackLogout(): Promise<void> {
+    if (this.isTrackingDisabled()) {
+      return;
+    }
+
+    const logoutIdentity = { ...this.identityCache };
+
+    // Clear identity immediately so concurrent navigation events (screen_view) use no id
+    this.identityCache = { ktcId: null, deviceId: null, userProperties: {} };
+
+    if (!this.isEventTrackingDisabled()) {
+      await this.emitEvent(
+        KEWA_CONSTANTS.EVENTS.USER_LOGOUT,
+        { timestamp: new Date().toISOString() },
+        undefined,
+        { identity: logoutIdentity, skipIdentityRefresh: true },
+      );
+    }
+
+    await this.clearLocalIdentity();
+    kewaDebug('Kewa Analytics SDK: Logout complete — identity cleared');
+  }
+
+  async trackRegistration(userData: Partial<UserRegistrationEvent>): Promise<void> {
+    const registrationData: UserRegistrationEvent = {
+      registrationMethod: 'email',
+      ...userData,
+      userId: userData.userId || '',
+      timestamp: new Date().toISOString(),
+    };
+
+    await this.trackEvent(KEWA_CONSTANTS.EVENTS.USER_REGISTRATION, registrationData);
+  }
+
+  async trackScreenView(screenName: string, additionalData: Partial<ScreenViewEvent> = {}): Promise<void> {
+    const screenData: ScreenViewEvent = {
+      screenName,
+      ...additionalData,
+      timestamp: new Date().toISOString(),
+    };
+
+    await this.trackEvent(KEWA_CONSTANTS.EVENTS.SCREEN_VIEW, screenData);
+  }
+
+  async trackError(error: Error, context: Record<string, any> = {}, isFatal = false): Promise<void> {
+    const errorData: ErrorEvent = {
+      errorMessage: error.message,
+      errorStack: error.stack,
+      errorName: error.name,
+      isFatal,
+      context,
+      timestamp: new Date().toISOString(),
+    };
+
+    await this.trackEvent(KEWA_CONSTANTS.EVENTS.ERROR, errorData);
+  }
+
+  async reset(): Promise<void> {
+    await this.clearLocalIdentity();
+  }
+
+  private async clearLocalIdentity(): Promise<void> {
+    await StorageManager.removeKtcId();
+    await StorageManager.removeDeviceId();
+    await StorageManager.removeUserProperties();
+    this.identityCache = { ktcId: null, deviceId: null, userProperties: {} };
+    this.backgroundEventPending = false;
+  }
+
+  async getKtcId(): Promise<string | null> {
+    return await StorageManager.getKtcId();
+  }
+
+  async getDeviceId(): Promise<string | null> {
+    return await StorageManager.getDeviceId();
+  }
+
+  getUserProperties(): Promise<ContactData> {
+    return StorageManager.getUserProperties();
+  }
+
+  isSDKInitialized(): boolean {
+    return this.isInitialized;
+  }
+
+  cleanup(): void {
+    if (this.appStateSubscription) {
+      this.appStateSubscription.remove();
+    }
+    if (this.networkManager) {
+      this.networkManager.cleanup();
+    }
+  }
+}

package/src/index.tsx

@@ -0,0 +1,89 @@
+import {
+  KewaProvider,
+  useKewa,
+  getDefaultKewaInstance,
+} from './KewaProvider';
+
+export * from './types';
+
+export { KEWA_CONSTANTS } from './utils/constants';
+export { DeviceInfoCollector } from './utils/DeviceInfo';
+export { KewaProvider, useKewa };
+
+const Kewa = getDefaultKewaInstance();
+export default Kewa;
+
+export class KewaTracker {
+  static setupNavigationTracking(navigationRef: any) {
+    const kewa = getDefaultKewaInstance();
+    const routeNameRef = { current: '' };
+
+    return {
+      onReady: () => {
+        const currentRoute = navigationRef.current?.getCurrentRoute();
+        if (currentRoute) {
+          routeNameRef.current = currentRoute.name;
+        }
+      },
+      onStateChange: async () => {
+        if (!kewa.isAutoScreenViewTrackingEnabled()) {
+          return;
+        }
+
+        const previousRouteName = routeNameRef.current;
+        const currentRoute = navigationRef.current?.getCurrentRoute();
+
+        if (currentRoute && previousRouteName !== currentRoute.name) {
+          await kewa.trackScreenView(currentRoute.name, {
+            previousScreen: previousRouteName,
+            params: currentRoute.params,
+          });
+          routeNameRef.current = currentRoute.name;
+        }
+      },
+    };
+  }
+
+  static trackButtonPress(buttonName: string, additionalData: Record<string, any> = {}) {
+    const kewa = getDefaultKewaInstance();
+    return async () => {
+      await kewa.trackEvent('button_press', {
+        buttonName,
+        ...additionalData,
+      });
+    };
+  }
+
+  static trackFormSubmission(formName: string, formData: Record<string, any> = {}) {
+    const kewa = getDefaultKewaInstance();
+    return async () => {
+      await kewa.trackEvent('form_submit', {
+        formName,
+        ...formData,
+      });
+    };
+  }
+
+  static trackError(error: Error, context: Record<string, any> = {}) {
+    return getDefaultKewaInstance().trackError(error, context);
+  }
+}
+
+export const KewaAutoTracker = KewaTracker;
+
+export function useAutoTracker() {
+  const kewa = useKewa();
+
+  return {
+    setupNavigationTracking: KewaTracker.setupNavigationTracking,
+    trackButtonPress: (buttonName: string, additionalData: Record<string, any> = {}) =>
+      async () => {
+        await kewa.trackEvent('button_press', { buttonName, ...additionalData });
+      },
+    trackFormSubmission: (formName: string, formData: Record<string, any> = {}) =>
+      async () => {
+        await kewa.trackEvent('form_submit', { formName, ...formData });
+      },
+    trackError: kewa.trackError.bind(kewa),
+  };
+}

package/src/types/config.ts

@@ -0,0 +1,33 @@
+export interface KewaConfig {
+  appUrl: string;
+  apiKey: string;
+  projectId?: string;
+  disableTracking?: boolean;
+  disableEventTracking?: boolean;
+  disableAppStateTracking?: boolean;
+  disableScreenViewTracking?: boolean;
+  batchSize?: number;
+  maxQueueSize?: number;
+  enableDebugLogging?: boolean;
+  /** @deprecated Use appUrl instead */
+  apiUrl?: string;
+}
+
+export interface DeviceInfo {
+  appName: string;
+  platform: string;
+  userAgent: string;
+  platformVersion: string | number;
+  appVersion: string;
+  deviceName?: string;
+  buildNumber?: string;
+  deviceModel: string;
+  deviceId?: string;
+  screenWidth: number;
+  screenHeight: number;
+  timezone: string;
+  carrier?: string;
+  isTablet?: boolean;
+  brand?: string;
+  manufacturer?: string;
+}

package/src/types/events.ts

@@ -0,0 +1,123 @@
+import { DeviceInfo } from "./config";
+
+export interface BaseEventData {
+  timestamp?: string;
+  screenName?: string;
+  previousScreen?: string;
+  [key: string]: any;
+}
+
+export interface KewaEvent {
+  eventName: string;
+  eventData: BaseEventData;
+  contactData?: ContactData;
+  deviceId?: string | null;
+  deviceInfo?: DeviceInfo;
+  metadata?: EventMetadata;
+  timestamp: string;
+}
+
+export interface ContactData {
+  id?: string;
+  title?: string;
+  firstname?: string;
+  lastname?: string;
+  company?: string;
+  position?: string;
+  email?: string;
+  mobile?: string;
+  phone?: string;
+  points?: number;
+  fax?: string;
+  address1?: string;
+  address2?: string;
+  city?: string;
+  state?: string;
+  zipcode?: string;
+  country?: string;
+  preferred_locale?: string;
+  timezone?: string;
+  last_active?: string;
+  attribution_date?: string;
+  attribution?: number;
+  website?: string;
+  facebook?: string;
+  foursquare?: string;
+  instagram?: string;
+  linkedin?: string;
+  skype?: string;
+  twitter?: string;
+  companyaddress1?: string;
+  companyaddress2?: string;
+  companyemail?: string;
+  companyphone?: string;
+  companycity?: string;
+  companystate?: string;
+  companyzipcode?: string;
+  companycountry?: string;
+  companyname?: string;
+  companywebsite?: string;
+  companynumber_of_employees?: number;
+  companyfax?: string;
+  companyannual_revenue?: number;
+  companyindustry?: string;
+  companydescription?: string;
+  [key: string]: any;
+}
+
+export interface EventMetadata {
+  eventId: string;
+  attemptCount?: number;
+  queuedAt?: string;
+  sentAt?: string;
+}
+
+
+export interface AppLaunchEvent extends BaseEventData {
+  isFirstLaunch: boolean;
+  installSource?: string;
+  referrer?: string;
+  campaignId?: string;
+}
+
+export interface UserLoginEvent extends BaseEventData {
+  userId: string;
+  email?: string;
+  loginMethod: 'email' | 'google' | 'facebook' | 'apple' | 'phone' | 'custom';
+}
+
+export interface UserRegistrationEvent extends BaseEventData {
+  userId: string;
+  email?: string;
+  registrationMethod: 'email' | 'google' | 'facebook' | 'apple' | 'phone';
+}
+
+
+export interface ScreenViewEvent extends BaseEventData {
+  screenName: string;
+  screenClass?: string;
+  loadTime?: number;
+}
+
+export interface ErrorEvent extends BaseEventData {
+  errorMessage: string;
+  errorStack?: string;
+  errorName: string;
+  isFatal?: boolean;
+  context?: Record<string, any>;
+}
+
+export interface AppForegroundEvent extends BaseEventData {
+  timestamp: string;
+}
+
+export interface AppBackgroundEvent extends BaseEventData {
+  timestamp: string;
+}
+
+export type PredefinedEvents =
+  | AppLaunchEvent
+  | UserLoginEvent
+  | UserRegistrationEvent
+  | ScreenViewEvent
+  | ErrorEvent;

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export * from './config';
+export * from './events';
+export * from './response';

package/src/types/response.ts

@@ -0,0 +1,16 @@
+export interface KewaResponse {
+  success: boolean;
+  id?: string;
+  sid?: string;
+  device_id?: string;
+  message?: string;
+}
+
+export interface KewaBatchResponse {
+  success: boolean;
+  user_id?: string;
+  processed_count: number;
+  failed_count: number;
+  errors?: string[];
+  timestamp?: string;
+}

package/src/utils/DeviceInfo.ts

@@ -0,0 +1,29 @@
+import { Platform, Dimensions } from 'react-native';
+import { DeviceInfo as DeviceInfoType } from '../types'
+import DeviceInfo from 'react-native-device-info';
+
+export class DeviceInfoCollector {
+  static async collect(): Promise<DeviceInfoType> {
+    const { width, height } = Dimensions.get('window');
+
+    const deviceInfo: DeviceInfoType = {
+      appName: DeviceInfo.getApplicationName(),
+      platform: Platform.OS,
+      platformVersion: Platform.Version,
+      userAgent: await DeviceInfo.getUserAgent(),
+      appVersion: DeviceInfo.getReadableVersion(),
+      buildNumber: DeviceInfo.getBuildNumber(),
+      deviceName: await DeviceInfo.getDeviceName(),
+      deviceModel: DeviceInfo.getModel(),
+      screenWidth: width,
+      screenHeight: height,
+      timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+      carrier: await DeviceInfo.getCarrier(),
+      brand: DeviceInfo.getBrand(),
+      manufacturer: await DeviceInfo.getManufacturer(),
+      isTablet: DeviceInfo.isTablet(),
+    };
+
+    return deviceInfo;
+  }
+}