Analytics Tracking Guide

Guide to implement analytics tracking in 54VIE Super App.

Setup

Host App

import { AnalyticsProvider } from '@54vie/analytics';

function App() {
  return (
    <AnalyticsProvider config={{
      appId: '54vie-host',
      apiKey: process.env.ANALYTICS_API_KEY,
      apiEndpoint: 'https://analytics.54vie.vn',
      debug: __DEV__,
    }}>
      <MainApp />
    </AnalyticsProvider>
  );
}

Mini-App

Mini-apps use the SDK - events are automatically attributed to the mini-app:

import { analytics } from '@54vie/miniapp-sdk';

analytics.track('event_name', { property: 'value' });

Event Tracking

Screen Views

// Automatic (in host with navigation integration)
// Or manual:
const { screen } = useAnalytics();

useEffect(() => {
  screen('ProductScreen', { product_id: productId });
}, []);

Custom Events

const { track } = useAnalytics();

// Button click
track('button_clicked', {
  button_name: 'add_to_cart',
  screen: 'ProductDetail',
});

// Search
track('search', {
  query: 'iphone',
  results_count: 25,
});

// Form submission
track('form_submitted', {
  form_name: 'checkout',
  fields_count: 5,
});

Standard Events

Use standard event names for consistency:

import { StandardEvents } from '@54vie/analytics';

// Auth
track(StandardEvents.LOGIN, { method: 'email' });
track(StandardEvents.SIGN_UP, { method: 'google' });
track(StandardEvents.LOGOUT);

// E-commerce
track(StandardEvents.VIEW_PRODUCT, {
  product_id: '123',
  product_name: 'iPhone 15',
  price: 25000000,
  currency: 'VND',
  category: 'phones',
});

track(StandardEvents.ADD_TO_CART, {
  product_id: '123',
  quantity: 1,
  price: 25000000,
});

track(StandardEvents.PURCHASE, {
  order_id: 'order_456',
  total: 25000000,
  currency: 'VND',
  items: [
    { product_id: '123', quantity: 1, price: 25000000 },
  ],
});

// Mini-app
track(StandardEvents.MINI_APP_OPEN, { app_id: 'com.54vie.shopping' });
track(StandardEvents.MINI_APP_CLOSE, { app_id: 'com.54vie.shopping', duration: 120000 });

User Identification

const { identify, reset } = useAnalytics();

// After login
identify('user_123', {
  name: 'John Doe',
  email: 'john@example.com',
  phone: '+84901234567',
  plan: 'premium',
  created_at: '2024-01-15',
});

// After logout
reset();

User Properties

const { setProperty, increment } = useUserProperties();

// Set property
setProperty('favorite_category', 'electronics');

// Increment counter
increment('purchase_count');
increment('total_spent', 500000);

Revenue Tracking

import { Analytics } from '@54vie/analytics';

Analytics.trackRevenue({
  amount: 500000,
  currency: 'VND',
  productId: 'premium_monthly',
  productName: 'Premium Subscription',
  orderId: 'order_789',
});

Timed Events

const { startTimer, endTimer } = useAnalytics();

// Start timing
startTimer('checkout_flow');

// ... user completes checkout ...

// End timing (auto-tracks with duration)
endTimer('checkout_flow', {
  payment_method: 'card',
  success: true,
});
// Tracks: checkout_flow { duration: 45000, payment_method: 'card', success: true }

Funnel Tracking

Track user journey through a funnel:

// Step 1: View product
track('funnel_product_viewed', { funnel: 'purchase', step: 1 });

// Step 2: Add to cart
track('funnel_added_to_cart', { funnel: 'purchase', step: 2 });

// Step 3: Start checkout
track('funnel_checkout_started', { funnel: 'purchase', step: 3 });

// Step 4: Payment entered
track('funnel_payment_entered', { funnel: 'purchase', step: 4 });

// Step 5: Purchase completed
track('funnel_purchase_completed', { funnel: 'purchase', step: 5 });

A/B Testing

import { useExperiment, useFeatureFlag } from '@54vie/analytics';

// Experiment
function CheckoutScreen() {
  const { variant } = useExperiment('checkout_v2');

  if (variant === 'new') {
    return <NewCheckout />;
  }
  return <OldCheckout />;
}

// Feature flag
function NewFeature() {
  const isEnabled = useFeatureFlag('new_feature');

  if (!isEnabled) return null;
  return <FeatureComponent />;
}

// Track conversion
const { trackConversion } = useExperimentConversion('checkout_v2');

const handlePurchase = () => {
  trackConversion('purchase', orderTotal);
};

Best Practices

1. Use consistent naming

// ✅ Good - snake_case, action_object pattern
track('button_clicked', { button_name: 'checkout' });
track('product_viewed', { product_id: '123' });

// ❌ Bad - inconsistent
track('ButtonClick', {});
track('viewedProduct', {});

2. Include relevant context

// ✅ Good - include context
track('product_viewed', {
  product_id: '123',
  product_name: 'iPhone 15',
  price: 25000000,
  category: 'phones',
  source: 'search',
  position: 3,
});

// ❌ Bad - missing context
track('product_viewed', { id: '123' });

3. Track failures too

// ✅ Good - track both success and failure
track('payment_success', { order_id, amount });
track('payment_failed', { order_id, error_code, error_message });

// ❌ Bad - only tracking success
track('payment_completed', { order_id });

4. Don't over-track

// ❌ Bad - too granular
track('input_focused');
track('input_char_typed');
track('input_blurred');

// ✅ Good - meaningful events
track('form_field_completed', { field: 'email' });

Debug Mode

// Enable in development
<AnalyticsProvider config={{ debug: __DEV__ }}>

// Events logged to console:
// [Analytics] Queued: track:button_clicked
// [Analytics] Flushed 5 events

// Force flush
const { flush } = useAnalytics();
await flush();