@athena-tracker/tracker

Behavioral analytics tracker with edge AI for React Native and Web

Features

• ✅ 90+ Behavioral Event Types - Auto-captured touch, navigation, lifecycle events
• ✅ Dual-Mode ML Inference - On-device (ONNX) or server-side (auto-fallback)
• ✅ Purchase Intent Prediction - Real-time predictions for e-commerce (0.0-1.0)
• ✅ 5 User Archetypes - Fast Mover, On Track, Slow Adopter, At Risk, Different Path
• ✅ Cross-Platform - Works on Web, iOS, Android (React Native)
• ✅ Privacy-First - Optional on-device inference (data never leaves device)
• ✅ Zero Config - Smart auto-detection of best inference mode
• ✅ TypeScript Support - Full type definitions included

Installation

npm install @athena-tracker/tracker

For React Native with On-Device Inference

npm install @athena-tracker/tracker onnxruntime-react-native

For OTA Updates (Server-Side Inference)

npm install @athena-tracker/tracker

(No onnxruntime-react-native required - will automatically fall back to server-side inference)

⚠️ Getting Credentials (Required Before Installation)

Before you can use this package, you need an appToken from Pascal.

For B2B Platform Partners (App Generators like Anything.com, Bubble.io)

If you're building a platform that generates apps for customers:

1. Contact Markopolo to get partner credentials:

   • Email: [email protected]
   • Request: ATHENA B2B partner workspace

2. Receive credentials:

   • Workspace ID: ws_your_company_com
   • JWT Token: eyJhbGc... (perpetual token)

3. Provision apps via API:

// Your backend code
const axios = require('axios');

async function provisionApp(appDetails) {
  const response = await axios.post(
    'https://tracker.pascal.cx/api/athena/provision',
    {
      workspaceId: process.env.ATHENA_WORKSPACE_ID,
      appId: appDetails.id,
      appName: appDetails.name,
      platform: ['web', 'ios', 'android']
    },
    {
      headers: {
        'Authorization': `Bearer ${process.env.ATHENA_WORKSPACE_JWT}`,
        'Content-Type': 'application/json'
      }
    }
  );

  const { appToken } = response.data;

  // Store appToken in your database
  await db.apps.update({
    id: appDetails.id,
    athena_app_token: appToken
  });

  return appToken;
}

4. Inject token into generated apps (see Quick Start below)

For Agencies/Merchants (Website Integration)

If you're integrating tracking for merchant websites:

1. Contact Markopolo for a partner API key:

   • Email: [email protected]
   • Request: Partner merchant provisioning

2. Provision merchants via API:

const response = await axios.post(
  'https://tracker.pascal.cx/api/partners/YOUR_PARTNER_NAME/merchants',
  {
    merchant_id: 'merchant_001',
    merchant_email: '[email protected]',
    webhook_url: 'https://your-platform.com/webhooks/pascal'
  },
  {
    headers: {
      'Authorization': `Bearer ${process.env.PASCAL_PARTNER_API_KEY}`,
      'Content-Type': 'application/json'
    }
  }
);

const { api_key } = response.data;  // This IS your appToken

Testing with Demo Token

For testing purposes, you can use a demo token:

// ⚠️ FOR TESTING ONLY - NOT FOR PRODUCTION
AthenaTracker.init({
  appToken: 'at_demo_test_mode_no_predictions',
  debug: true
});

📖 Complete Guide: See PARTNER_INTEGRATION_GUIDE.md for full details on both integration patterns.

Quick Start

React Native

import AthenaTracker from '@athena-tracker/tracker';

// Initialize tracker
AthenaTracker.init({
  appToken: 'at_live_xxxxx',
  inferenceMode: 'auto', // Auto-detects environment
  webhook: {
    url: 'https://your-backend.com/webhooks/athena',
    enabled: true
  }
});

Web

<script src="https://tracker.pascal.cx/v1/tracker.min.js"></script>
<script>
  const tracker = new PascalTracker({
    projectId: 'your-app-token',
    edgeAI: {
      enabled: true,
      modelPath: 'https://tracker.pascal.cx/models/base_model_int8.onnx'
    }
  });
</script>

Configuration

AthenaConfig

interface AthenaConfig {
  appToken: string;              // Required: App token from ATHENA provisioning
  apiUrl?: string;               // Optional: API base URL (default: https://tracker.pascal.cx)
  inferenceMode?: 'auto' | 'on-device' | 'server'; // Optional: Inference mode
  modelPath?: string;            // Optional: ONNX model path (for on-device)
  serverInferenceUrl?: string;   // Optional: Server inference endpoint
  webhook?: WebhookConfig;       // Optional: Webhook configuration
  batching?: BatchingConfig;     // Optional: Event batching
  debug?: boolean;               // Optional: Debug mode
}

Inference Modes

Auto Mode (Recommended)

Automatically detects whether onnxruntime-react-native is available:

AthenaTracker.init({
  appToken: 'at_live_xxxxx',
  inferenceMode: 'auto' // Default
});

On-Device Mode (Forced)

Force on-device inference (requires onnxruntime-react-native):

AthenaTracker.init({
  appToken: 'at_live_xxxxx',
  inferenceMode: 'on-device',
  modelPath: '/path/to/model.onnx'
});

Server Mode (Forced)

Force server-side inference:

AthenaTracker.init({
  appToken: 'at_live_xxxxx',
  inferenceMode: 'server',
  // ⚠️ REQUIRED for predictions - this is a separate service from apiUrl
  serverInferenceUrl: 'https://pascal-ml-api-cgn7rucynq-uc.a.run.app/v1/predict'
});

⚠️ CRITICAL: The serverInferenceUrl parameter is REQUIRED for ML predictions. This is a separate service from apiUrl:

• apiUrl (default: https://tracker.pascal.cx) - Handles event ingestion only
• serverInferenceUrl - Handles ML inference and predictions (separate Cloud Run service)

Without serverInferenceUrl, predictions will fail with HTTP 404 errors. See troubleshooting below for details.

Webhook Integration

Receive real-time predictions via webhooks:

AthenaTracker.init({
  appToken: 'at_live_xxxxx',
  webhook: {
    url: 'https://your-backend.com/webhooks/athena',
    enabled: true,
    retry: {
      maxAttempts: 3,
      backoffMs: 1000
    }
  }
});

Webhook Payload

{
  "user_id": "user_abc",
  "session_id": "sess_123",
  "predicted_class": "engaged_explorer",
  "confidence": 0.85,
  "archetype": "on_track",
  "purchase_intent": 0.72,
  "cart_abandonment_risk": 0.15,
  "recommended_action": "Show 10% discount offer",
  "urgency": "high",
  "trigger_reason": "High-value cart ($249), 80% scroll depth, 45s time-on-page",
  "timestamp": "2026-02-24T12:34:56Z"
}

User Archetypes

| Archetype | Description | Similarity Score | |-----------|-------------|------------------| | fast_mover | High purchase intent, quick decision-maker | >85% | | on_track | Steady browsing, likely to convert | 60-85% | | slow_adopter | Needs guidance, price-sensitive | 40-60% | | at_risk | Low engagement, high abandonment risk | <40% | | different_path | Unconventional browsing pattern | Unique |

API Reference

AthenaTracker

class AthenaTracker {
  static init(config: AthenaConfig): Promise<void>
  static identify(userId: string, traits?: Record<string, any>): void
  static track(eventType: string, properties?: Record<string, any>): void
  static getInferenceMode(): 'on-device' | 'server' | null
  static getSessionId(): string | null
}

Methods

init(config)

Initialize the tracker with configuration.

await AthenaTracker.init({
  appToken: 'at_live_xxxxx'
});

identify(userId, traits?)

Identify a user.

AthenaTracker.identify('user_123', {
  email: '[email protected]',
  name: 'John Doe'
});

track(eventType, properties?)

Track a custom event.

AthenaTracker.track('button_click', {
  button_id: 'checkout',
  page: '/cart'
});

React Native Components

AthenaOTAWrapper

For apps using Expo OTA updates, wrap your app with AthenaOTAWrapper:

import { AthenaOTAWrapper } from '@athena-tracker/tracker';

export default function App() {
  return (
    <AthenaOTAWrapper
      loadingMessage="Loading..."
      updateMessage="Updating..."
    >
      <YourApp />
    </AthenaOTAWrapper>
  );
}

What it does:

• Checks for OTA updates on app launch
• Fetches and applies updates automatically
• Forces immediate reload (<2 seconds)
• Displays loading spinner during update

Props:

• loadingMessage (string, optional): Message during initial load (default: "Loading...")
• updateMessage (string, optional): Message during update (default: "Updating...")

ReactNativeEventCapture

Advanced event capture for custom use cases:

import { ReactNativeEventCapture } from '@athena-tracker/tracker';

const capture = new ReactNativeEventCapture({
  captureTouch: true,
  captureNavigation: true,
  captureLifecycle: true,
  captureNetworkErrors: true,
  batchSize: 10,
  batchIntervalMs: 10000
});

// Start capturing
capture.start();

// Track screen view manually
capture.trackScreenView('ProductDetails', { productId: '123' });

// Track custom event
capture.track('AddToCart', { productId: '123', price: 49.99 });

// Stop capturing
capture.stop();

Configuration:

• captureTouch (boolean): Capture touch events (Tap, Swipe, LongPress)
• captureNavigation (boolean): Capture screen navigation
• captureLifecycle (boolean): Capture app lifecycle (Open, Background, Foreground)
• captureNetworkErrors (boolean): Capture failed network requests
• batchSize (number): Events per batch (default: 10)
• batchIntervalMs (number): Batch interval in milliseconds (default: 10000)

Captured Events:

• AppOpen, AppForeground, AppBackground, AppInactive
• Tap, Swipe, LongPress
• ScreenView
• NetworkError

Performance

• Bundle size: ~10MB (includes ONNX model for on-device mode)
• On-device inference latency: <10ms P95
• Server-side inference latency: <100ms P95
• Memory overhead: <50MB
• Battery impact: Negligible (<1%)

Troubleshooting

"Server inference failed: 404 Not Found" Error

Symptom: Predictions fail with 404 errors in console logs.

Cause: Missing or incorrect serverInferenceUrl configuration.

Solution: Explicitly set the serverInferenceUrl parameter:

AthenaTracker.init({
  appToken: 'at_live_xxxxx',
  apiUrl: 'https://tracker.pascal.cx', // Event ingestion
  serverInferenceUrl: 'https://pascal-ml-api-cgn7rucynq-uc.a.run.app/v1/predict', // ML inference
  inferenceMode: 'server'
});

Event Tracking Works But No Predictions

Cause: Event tracking and ML predictions use separate endpoints.

Solution: Verify serverInferenceUrl is set correctly. Test with:

curl -X POST https://pascal-ml-api-cgn7rucynq-uc.a.run.app/v1/predict \
  -H "Content-Type: application/json" \
  -d '{"app_token":"your_token","events":[...]}'

What's New in v1.1.0

• ✅ Updated ML inference endpoint to latest production URL
• ✅ 70+ event types supported via EVENT_MAPPING (cart_viewed, coupon_applied, etc.)
• ✅ Enhanced documentation with critical configuration requirements
• ✅ React Native integration validated with production test app
• ✅ Improved error messages for missing serverInferenceUrl

Browser Support

• Chrome/Edge 90+
• Safari 14+
• Firefox 88+
• React Native 0.70+

License

MIT

Documentation

• Full documentation: https://docs.athena.ai/tracker
• Integration guide: See ATHENA_HANDOVER_DOCUMENTATION.md
• API reference: https://tracker.pascal.cx/docs

Support

• Issues: https://github.com/RubaiyatF/Pascal/issues
• Email: [email protected]
• Slack: #athena-integration (for partners)