flux-analytics-sdk 1.0.0

package/package.json

@@ -0,0 +1,20 @@
+{
+    "name": "flux-analytics-sdk",
+    "version": "1.0.0",
+    "description": "Flux Analytics SDK for JavaScript/Web",
+    "main": "src/index.js",
+    "scripts": {
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "keywords": [
+        "flux",
+        "analytics",
+        "sdk",
+        "web"
+    ],
+    "author": "Flux Team",
+    "license": "ISC",
+    "dependencies": {
+        "uuid": "^9.0.1"
+    }
+}

package/src/Flux.js

@@ -0,0 +1,467 @@
+
+const Flux = (function () {
+    // Private state
+    let _appId = null;
+    let _firmId = null;
+    let _userId = null;
+    let _debug = false;
+    let _isProcessingQueue = false;
+
+    // Session Management
+    let _sessionId = null;
+    let _sessionStartTime = null;
+    let _initialized = false;
+
+    // Base URL for API
+    let _baseUrl = 'https://cnpawrfdekifurtkdblw.supabase.co/rest/v1';
+    let _apiKey = null;
+
+    // Constants
+    const _queueKey = 'flux_event_queue';
+    const _installKey = 'flux_app_installed';
+    const _propsKey = 'flux_user_properties';
+    const _anonIdKey = 'flux_anonymous_id';
+    const _sessionKey = 'flux_session_id'; // To persist session ID if needed
+
+    let _campaignId = null;
+    let _userProperties = {};
+    let _anonymousId = null;
+    const _screenTimers = {};
+
+    // MMP / Attribution Data
+    let _attributionData = {};
+    let _clickId = null;
+
+    // Helper: Generate UUID (Simple v4 implementation for browser if library not available)
+    function uuidv4() {
+        if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+            return crypto.randomUUID();
+        }
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+            const r = (Math.random() * 16) | 0,
+                v = c === 'x' ? r : (r & 0x3) | 0x8;
+            return v.toString(16);
+        });
+    }
+
+    // Helper: Get Device Info
+    function getDeviceInfo() {
+        const ua = navigator.userAgent;
+        const platform = navigator.platform || 'unknown';
+        const language = navigator.language || 'en-US';
+        const screenRes = `${window.screen.width}x${window.screen.height}`;
+        const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+
+        return {
+            platform: 'web',
+            os_version: platform, // Web specific
+            device_model: ua, // User Agent as model
+            language: language,
+            timezone: timeZone,
+            resolution: screenRes,
+            user_agent: ua
+        };
+    }
+
+    // Helper: LocalStorage Wrapper
+    const Storage = {
+        get: (key) => localStorage.getItem(key),
+        set: (key, value) => localStorage.setItem(key, value),
+        remove: (key) => localStorage.removeItem(key),
+        getJSON: (key) => {
+            try {
+                return JSON.parse(localStorage.getItem(key));
+            } catch (e) {
+                return null;
+            }
+        },
+        setJSON: (key, value) => localStorage.setItem(key, JSON.stringify(value))
+    };
+
+
+    // ----------------------------------------------------------------------
+    // Private Methods
+    // ----------------------------------------------------------------------
+
+    async function _initAnonymousId() {
+        try {
+            // 1. Check Storage
+            _anonymousId = Storage.get(_anonIdKey);
+
+            if (!_anonymousId) {
+                // 2. Generate new if not exists
+                _anonymousId = uuidv4();
+                Storage.set(_anonIdKey, _anonymousId);
+                if (_debug) console.log('Flux: New Anonymous ID generated:', _anonymousId);
+            } else {
+                if (_debug) console.log('Flux: Existing Anonymous ID loaded:', _anonymousId);
+            }
+        } catch (e) {
+            if (_debug) console.error('Flux: Error initializing Anonymous ID:', e);
+            _anonymousId = 'unknown_device';
+        }
+    }
+
+    async function _loadUserProperties() {
+        try {
+            const props = Storage.getJSON(_propsKey);
+            if (props) {
+                _userProperties = props;
+            }
+        } catch (e) {
+            if (_debug) console.error('Flux Load Props Error:', e);
+        }
+    }
+
+    async function _checkAttribution() {
+        // Web attribution logic can be implemented here
+        // Checking URL parameters for campaign_id, click_id, gclid etc.
+        const urlParams = new URLSearchParams(window.location.search);
+
+        // Example: ?campaign_id=...&click_id=...
+        const campId = urlParams.get('campaign_id') || urlParams.get('utm_campaign');
+        const clickId = urlParams.get('click_id') || urlParams.get('gclid');
+
+        if (campId) _campaignId = campId;
+        if (clickId) _clickId = clickId;
+
+        // Save if found
+        if (campId || clickId) {
+            // Logic to persist attribution if needed
+            if (_debug) console.log(`Flux: Attribution found. Campaign: ${campId}, Click: ${clickId}`);
+        }
+    }
+
+    async function _startSession() {
+        if (_sessionId) return; // Session already active
+
+        // Check if we can recover a session from storage (optional, for page reloads)
+        // For now, let's treat every page load/init as a new session start for simplicity in Web Context
+        // OR implement session timeout logic (e.g. 30 mins inactivity)
+
+        _sessionId = uuidv4();
+        _sessionStartTime = new Date();
+
+        if (_debug) console.log('Flux: Session Started (ID: ' + _sessionId + ')');
+
+        // Sessions tablosuna oturum başlattığımızı bildir
+        await _trackSessionData({ isStart: true });
+
+        // Otomatik "session_start" olayı kaydı
+        await track('session_start');
+    }
+
+    async function _trackSessionData({ isStart }) {
+        const deviceInfo = getDeviceInfo();
+
+        const sessionData = {
+            session_id: _sessionId,
+            device_id: _anonymousId,
+            user_id: _userId || _anonymousId,
+            app_id: _appId,
+            firm_id: _firmId,
+            session_start: _sessionStartTime.toISOString(),
+            platform: deviceInfo.platform,
+            is_crashed: false // Hard to detect crashes on web in same way
+        };
+
+        if (!isStart) {
+            const now = new Date();
+            sessionData.session_end = now.toISOString();
+            if (_sessionStartTime) {
+                sessionData.duration = Math.floor((now - _sessionStartTime) / 1000);
+            }
+        }
+
+        await _addToQueue('sessions', sessionData);
+    }
+
+    // Handle Page Visibility API for Session End/Resume?
+    // For web, "session end" is tricky (tab close). existing 'beforeunload' event is unreliable for async calls.
+    // relying on 'sendBeacon' or simple keep-alive is better.
+    // For now, we will just track session_start.
+
+    async function _checkInstall() {
+        try {
+            const isInstalled = Storage.get(_installKey);
+
+            if (!isInstalled) {
+                if (_debug) console.log('Flux: First visit (Install) detected...');
+
+                // 1. Installs tablosuna kaydet
+                await _trackInstall();
+
+                await track('app_install'); // Log as event too
+                await track('first_open');
+
+                Storage.set(_installKey, 'true');
+                if (_debug) console.log('Flux: First visit marked.');
+            }
+        } catch (e) {
+            if (_debug) console.error('Flux Install Check Error:', e);
+        }
+    }
+
+    async function _trackInstall() {
+        const deviceInfo = getDeviceInfo();
+        const installData = {
+            id: uuidv4(),
+            firm_id: _firmId,
+            app_id: _appId,
+            user_id: _userId || _anonymousId,
+            device_id: _anonymousId,
+            anonymous_id: _anonymousId,
+            platform: deviceInfo.platform,
+            os_version: deviceInfo.os_version,
+            device_model: deviceInfo.device_model,
+            connection_type: navigator.connection ? navigator.connection.effectiveType : 'unknown',
+            install_date: new Date().toISOString(),
+            source: 'web_direct',
+            attribution_status: _campaignId ? 'attributed' : 'unattributed',
+            campaign_id: _campaignId
+        };
+        await _addToQueue('installs', installData);
+    }
+
+    async function _addToQueue(endpoint, data) {
+        try {
+            let currentQueue = Storage.getJSON(_queueKey) || [];
+            currentQueue.push({ endpoint, data });
+            Storage.setJSON(_queueKey, currentQueue);
+
+            // Trigger process
+            _processQueue();
+        } catch (e) {
+            if (_debug) console.error('Flux Error adding to queue:', e);
+        }
+    }
+
+    async function _processQueue() {
+        if (_isProcessingQueue) return;
+
+        // Check online status
+        if (!navigator.onLine) return;
+
+        _isProcessingQueue = true;
+
+        try {
+            // Processing loop
+            while (true) {
+                let currentQueue = Storage.getJSON(_queueKey) || [];
+                if (currentQueue.length === 0) break;
+
+                const item = currentQueue[0];
+                if (_debug) console.log(`Flux Processing Queue (${currentQueue.length} remaining)...`);
+
+                const success = await _sendToBackend(item.endpoint, item.data);
+
+                if (success) {
+                    // Remove from queue
+                    currentQueue = Storage.getJSON(_queueKey) || []; // Re-read to be safe
+                    if (currentQueue.length > 0) { // simple check, race condition possible but low risk single-thread JS
+                        currentQueue.shift();
+                        Storage.setJSON(_queueKey, currentQueue);
+                    }
+                } else {
+                    if (_debug) console.log('Flux: Queue processing paused usage due to failure.');
+                    break;
+                }
+            }
+        } catch (e) {
+            if (_debug) console.error('Flux Queue Error:', e);
+        } finally {
+            _isProcessingQueue = false;
+        }
+    }
+
+    async function _sendToBackend(endpoint, data) {
+        if (!_apiKey) {
+            if (_debug) console.warn('Flux Warning: API Key is missing.');
+            return false;
+        }
+
+        try {
+            let url;
+            let headers = {
+                'Content-Type': 'application/json',
+                'apikey': _apiKey,
+                'Authorization': `Bearer ${_apiKey}`
+            };
+            let body = JSON.stringify(data);
+
+            // Special handling for 'events' -> RPC
+            if (endpoint === 'events') {
+                url = `${_baseUrl}/rpc/insert_event_v2`;
+                body = JSON.stringify({ event_data: data });
+            } else if (endpoint === 'sessions') {
+                url = `${_baseUrl}/sessions?on_conflict=session_id`;
+                headers['Prefer'] = 'return=representation,resolution=merge-duplicates';
+            } else if (endpoint === 'installs') {
+                url = `${_baseUrl}/installs`;
+                headers['Prefer'] = 'return=representation';
+            } else {
+                url = `${_baseUrl}/${endpoint}`;
+            }
+
+            if (_debug) console.log(`Flux: Posting to ${url}`, body);
+
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: headers,
+                body: body
+            });
+
+            // 2xx success, 409 conflict (duplicate) is also success
+            if (response.ok || response.status === 409) {
+                return true;
+            } else {
+                if (_debug) console.error(`Flux Error: ${response.status} - ${response.statusText}`);
+                const text = await response.text();
+                if (_debug) console.error('Response:', text);
+                return false;
+            }
+
+        } catch (e) {
+            if (_debug) console.error('Flux Network Error:', e);
+            return false;
+        }
+    }
+
+    // Auto tracking
+    function _setupAutoTrack() {
+        // Track visibility change to manage session
+        document.addEventListener("visibilitychange", () => {
+            if (document.visibilityState === 'visible') {
+                // Resume or start new session?
+                // For now, keep simple. 
+            } else {
+                // Hidden
+            }
+        });
+
+        // Online/Offline listeners
+        window.addEventListener('online', _processQueue);
+    }
+
+
+    // ----------------------------------------------------------------------
+    // Public API
+    // ----------------------------------------------------------------------
+
+    /**
+     * Initialize Flux SDK
+     * @param {string} appId - The Application ID (UUID)
+     * @param {string} firmId - The Firm ID (UUID)
+     * @param {object} config - Optional config { apiKey, baseUrl, debug }
+     */
+    async function init(appId, firmId, config = {}) {
+        _appId = appId;
+        _firmId = firmId;
+        _apiKey = config.apiKey || null;
+        if (config.baseUrl) _baseUrl = config.baseUrl;
+        _debug = config.debug || false;
+
+        if (_debug) console.log('Flux SDK Initializing...');
+
+        await _initAnonymousId();
+        await _checkAttribution();
+        await _loadUserProperties();
+        await _startSession();
+        await _checkInstall();
+
+        _setupAutoTrack();
+        _processQueue(); // Process any old events
+
+        _initialized = true;
+    }
+
+    /**
+     * Identify a user
+     * @param {string} userId
+     */
+    function identify(userId) {
+        _userId = userId;
+        if (_debug) console.log('Flux Identified User:', _userId);
+        // Maybe trigger an identify event?
+    }
+
+    /**
+     * Track an event
+     * @param {string} eventName
+     * @param {object} metadata
+     */
+    async function track(eventName, metadata = {}) {
+        if (!_appId || !_firmId) {
+            console.error('Flux: SDK not initialized.');
+            return;
+        }
+
+        const deviceInfo = getDeviceInfo();
+
+        const payload = {
+            id: uuidv4(),
+            firm_id: _firmId,
+            app_id: _appId,
+            user_id: _userId || _anonymousId, // fallback to anon if no user
+            anonymous_id: _anonymousId,
+            campaign_id: _campaignId,
+            session_id: _sessionId,
+            device_id: _anonymousId,
+            game_type: eventName, // reusing this field for event name as per schema
+            latency_ms: 0,
+            is_error: false,
+            error_details: null,
+            metadata: {
+                ..._userProperties,
+                ...metadata,
+                ..._attributionData,
+                platform: deviceInfo.platform,
+                os_version: deviceInfo.os_version,
+                device_model: deviceInfo.device_model, // User Agent
+                // app_version: ???
+                language: deviceInfo.language,
+                timezone: deviceInfo.timezone,
+                resolution: deviceInfo.resolution,
+                page_url: window.location.href,
+                page_title: document.title,
+                referrer: document.referrer
+            },
+            created_at: new Date().toISOString()
+        };
+
+        if (_debug) console.log(`Flux Tracked: ${eventName}`, payload);
+
+        await _addToQueue('events', payload);
+    }
+
+    /**
+     * Track a page view
+     * @param {string} name - Optional page name
+     * @param {object} metadata
+     */
+    async function trackScreen(name, metadata = {}) {
+        const screenName = name || document.title || window.location.pathname;
+        await track('screen_view', {
+            screen_name: screenName,
+            ...metadata
+        });
+    }
+
+
+    return {
+        init,
+        identify,
+        track,
+        trackScreen,
+        // Expose for debugging if needed
+        _debug: () => _debug
+    };
+
+})();
+
+// Export for module systems
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = Flux;
+} else if (typeof window !== 'undefined') {
+    window.Flux = Flux;
+}

package/src/index.js

@@ -0,0 +1,4 @@
+
+const Flux = require('./Flux');
+
+module.exports = Flux;

package/test.html

@@ -0,0 +1,38 @@
+
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Flux JS SDK Test</title>
+</head>
+<body>
+    <h1>Flux JS SDK Test</h1>
+    <button id="trackBtn">Track Event</button>
+    <button id="identifyBtn">Identify User</button>
+    <div id="status">Converting...</div>
+
+    <script src="src/Flux.js"></script>
+    <script>
+        const APP_ID = '93a6e925-04ee-4e5a-9ae0-bc59592f87c3'; // Example App ID
+        const FIRM_ID = '93a6e925-04ee-4e5a-9ae0-bc59592f87c3'; // Example Firm ID
+        const API_KEY = 'YOUR_SUPABASE_ANON_KEY'; // Need to replace this with real key for full test
+
+        console.log('Initializing Flux...');
+        Flux.init(APP_ID, FIRM_ID, {
+            debug: true,
+            // apiKey: API_KEY // Uncomment to test with real backend
+        }).then(() => {
+            document.getElementById('status').innerText = 'Flux Initialized!';
+        });
+
+        document.getElementById('trackBtn').addEventListener('click', () => {
+            Flux.track('button_click', { button_id: 'trackBtn' });
+        });
+
+        document.getElementById('identifyBtn').addEventListener('click', () => {
+            Flux.identify('user_' + Math.floor(Math.random() * 1000));
+        });
+    </script>
+</body>
+</html>