Gunma Behavioral Tracking SDK for React Native

Professional-grade behavioral tracking for React Native mobile applications (iOS & Android).

Installation

# Install dependencies
npm install axios @react-native-async-storage/async-storage react-native-device-info

# For iOS, install pods
cd ios && pod install && cd ..

Setup

1. Configure the tracker in your App.tsx

import { behavioralTracker } from './sdk/react-native/src';

// Configure on app start
useEffect(() => {
  behavioralTracker.setConfig({
    apiUrl: process.env.EXPO_PUBLIC_API_URL || 'http://192.168.1.100:8000',
    enabled: true,
    consentRequired: true,
    debugMode: __DEV__,
  });
}, []);

2. Environment Variables

# .env
EXPO_PUBLIC_API_URL=http://192.168.1.100:8000

Usage

Product Screen

import { useBehavioralTracking } from './sdk/react-native/src';

function ProductScreen({ route }) {
  const { product } = route.params;
  const { trackProductView, trackAddToCart } = useBehavioralTracking('ProductScreen');

  useEffect(() => {
    // Auto-track product view
    trackProductView(product.id, product.price);
  }, [product.id]);

  const handleAddToCart = () => {
    trackAddToCart(product.id, 1, product.price);
    // Your cart logic
  };

  return (
    <View>
      <Text>{product.name}</Text>
      <Button title="Add to Cart" onPress={handleAddToCart} />
    </View>
  );
}

Search Screen

function SearchScreen() {
  const { trackSearch } = useBehavioralTracking('SearchScreen');

  const handleSearch = async (query: string) => {
    const results = await searchProducts(query);
    trackSearch(query, results.length);
    setResults(results);
  };

  return (
    <TextInput
      placeholder="Search..."
      onSubmitEditing={(e) => handleSearch(e.nativeEvent.text)}
    />
  );
}

Cart Screen

function CartScreen() {
  const { trackCheckoutInitiated } = useBehavioralTracking('CartScreen');

  const handleCheckout = () => {
    const total = calculateTotal();
    trackCheckoutInitiated(cartItems.length, total);
    navigation.navigate('Checkout');
  };

  return (
    <Button title="Checkout" onPress={handleCheckout} />
  );
}

Order Confirmation

function OrderConfirmationScreen({ route }) {
  const { order } = route.params;
  const { trackOrderPlaced } = useBehavioralTracking('OrderConfirmation');

  useEffect(() => {
    if (order) {
      trackOrderPlaced(order.id, order.total);
    }
  }, [order]);

  return <Text>Order #{order.id} placed successfully!</Text>;
}

API Reference

useBehavioralTracking(screenName?: string)

Main tracking hook with auto screen view tracking.

Methods:

• trackProductView(productId: number, price?: number)
• trackAddToCart(productId: number, quantity: number, price: number)
• trackRemoveFromCart(productId: number)
• trackSearch(query: string, resultsCount: number)
• trackOrderPlaced(orderId: number, total?: number)
• trackCheckoutInitiated(itemCount?: number, total?: number)
• trackAddToWishlist(productId: number)
• trackRemoveFromWishlist(productId: number)
• trackCategoryView(categoryId: number)
• trackScreenView(screenName: string)
• trackEvent(eventType: EventType, data?: Partial<BehavioralEvent>)

behavioralTracker

Direct access to tracker instance.

Methods:

• setConfig(config: Partial<TrackingConfig>) - Configure tracker
• grantConsent() - Grant tracking consent
• revokeConsent() - Revoke tracking consent
• hasConsent() - Check if consent granted
• All tracking methods from hook

Consent Management

import { behavioralTracker } from './sdk/react-native/src';
import AsyncStorage from '@react-native-async-storage/async-storage';

function ConsentScreen() {
  const [hasConsent, setHasConsent] = useState(false);

  useEffect(() => {
    checkConsent();
  }, []);

  const checkConsent = async () => {
    const consent = await AsyncStorage.getItem('tracking_consent');
    setHasConsent(consent === 'true');
  };

  const handleAccept = async () => {
    await behavioralTracker.grantConsent();
    setHasConsent(true);
  };

  const handleDecline = async () => {
    await behavioralTracker.revokeConsent();
    setHasConsent(false);
  };

  return (
    <Modal visible={!hasConsent}>
      <View>
        <Text>We use tracking to improve your experience</Text>
        <Button title="Accept" onPress={handleAccept} />
        <Button title="Decline" onPress={handleDecline} />
      </View>
    </Modal>
  );
}

Navigation Tracking

Track screen views automatically:

import { NavigationContainer } from '@react-navigation/native';
import { behavioralTracker } from './sdk/react-native/src';

function App() {
  const navigationRef = useRef(null);

  const onNavigationStateChange = async () => {
    const currentRoute = navigationRef.current?.getCurrentRoute();
    if (currentRoute) {
      await behavioralTracker.trackScreenView(currentRoute.name);
    }
  };

  return (
    <NavigationContainer
      ref={navigationRef}
      onStateChange={onNavigationStateChange}
    >
      {/* Your navigation */}
    </NavigationContainer>
  );
}

Troubleshooting

Events not tracking:

1. Check API URL is correct (use device IP, not localhost)
2. Check backend queue worker is running
3. Check network permissions in AndroidManifest.xml
4. Check console for errors

iOS specific:

• Add App Transport Security settings if using HTTP

Android specific:

• Add INTERNET permission in AndroidManifest.xml

License

MIT