Troubleshooting

Common issues and solutions when using the Tappd Mobile SDK.

SDK Not Initializing

Problem: SDK fails to initialize

Symptoms:

• Error: "App ID is required"
• Events not tracking

Solutions:

// ❌ Wrong: Missing appId
const tappd = new TappdSDK({});

// ✅ Correct: Include appId
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID'
});

Check:

1. App ID is correct from dashboard
2. App ID is not empty or undefined
3. SDK is imported correctly

---

Events Not Tracking

Problem: Events not appearing in dashboard

Symptoms:

• track() calls complete without errors
• No events visible in dashboard

Solutions:

1. Enable debug mode:

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  debug: true // Enable console/logging
});

2. Check network requests:

   • Use React Native debugger or Flipper
   • Check Network tab for API requests
   • Verify requests are being sent
   • Check response status codes

3. Verify API URL:

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  apiUrl: 'https://sdk.gotappd.com/api/v1/sdk' // Verify URL
});

4. Check async/await:

// ❌ Wrong: Not awaiting
tappd.track('event');

// ✅ Correct: Await the promise
await tappd.track('event');

---

Anonymous Data Not Merging

Problem: Anonymous events not linked after identification

Solutions:

1. Ensure identify() is called with external_id:

// Events tracked while anonymous
await tappd.track('event_1');
await tappd.track('event_2');

// Identify user (merges previous events)
await tappd.identify({
  external_id: 'user_123',  // Required: Your internal user ID
  email: 'john@example.com'
});

2. Check anonymous ID:

const anonymousId = tappd.getAnonymousId();
console.log('Anonymous ID:', anonymousId);

---

Session Issues

Problem: Sessions not starting or expiring incorrectly

Solutions:

1. Check session timeout:

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  sessionTimeout: 60 // Increase timeout (minutes)
});

2. Verify session ID:

const sessionId = tappd.getSessionId();
console.log('Session ID:', sessionId);
// Should not be null after initialization

---

Screen Tracking Not Working

Problem: Screen views not tracked

Symptoms:

• Only some screens tracked
• Screen views missing

Solutions:

1. Manual tracking with useFocusEffect:

import { useFocusEffect } from '@react-navigation/native';

function MyScreen() {
  useFocusEffect(
    React.useCallback(() => {
      tappd.trackScreen('MyScreen');
    }, [])
  );
}

2. Check React Navigation setup:
   • Ensure NavigationContainer is properly configured
   • Verify screen names are consistent

---

Push Token Registration Fails

Problem: registerPushToken() fails

Symptoms:

• Error: "User must be identified first"
• Token not registering

Solutions:

1. Identify user first:

// ✅ Correct: Identify before registering token
await tappd.identify({
  external_id: 'user_123',  // Required: Your internal user ID
  email: 'john@example.com'
});
await tappd.registerPushToken(token, 'ios');

2. Check FCM/APNs setup:

   • Verify Firebase configuration
   • Check APNs certificates for iOS
   • Verify google-services.json for Android

3. Verify token:

const token = await messaging().getToken();
console.log('FCM Token:', token);
// Should not be null or empty

---

AsyncStorage Issues

Problem: Anonymous ID not persisting

Symptoms:

• New anonymous ID on every app launch
• User appears as new each time

Solutions:

1. Check AsyncStorage installation:

npm install @react-native-async-storage/async-storage
cd ios && pod install && cd ..

2. Verify AsyncStorage works:

import AsyncStorage from '@react-native-async-storage/async-storage';

AsyncStorage.setItem('test', 'value').then(() => {
  AsyncStorage.getItem('test').then((value) => {
    console.log('AsyncStorage works:', value === 'value');
  });
});

---

Build Errors

Problem: Build fails with SDK

iOS:

1. Run pod install:

cd ios && pod install && cd ..

2. Clean build:

cd ios
rm -rf build
rm -rf Pods
pod install
cd ..

Android:

1. Clean build:

cd android
./gradlew clean
cd ..

2. Check dependencies:
   • Verify all required packages installed
   • Check for version conflicts

---

TypeScript Errors

Problem: Type errors in TypeScript projects

Solutions:

1. Install types:

npm install --save-dev @types/react-native

2. Import types:

import TappdSDK, { TappdConfig, CustomerAttributes } from '@tappd/mobile-sdk';

const config: TappdConfig = {
  appId: 'YOUR_APP_ID'
};

const tappd = new TappdSDK(config);

---

Debug Mode

Enable debug mode to troubleshoot:

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  debug: true
});

// Check logs/console for:
// [Tappd SDK] Initialized with App ID: a1b2c3d4...
// [Tappd SDK] New session started: sess_abc123
// [Tappd SDK] Event tracked: purchase
// [Tappd SDK] Customer identified: user_123

Getting Help

If you're still experiencing issues:

1. Check logs in React Native debugger
2. Enable debug mode and review logs
3. Verify network requests in Network tab
4. Check SDK version - ensure using latest
5. Contact support with:
   • Error messages
   • Platform (iOS/Android)
   • React Native version
   • SDK version
   • Debug logs

Common Error Messages

"App ID is required"

• Cause: Missing or empty appId
• Fix: Provide valid appId from dashboard

"User must be identified first"

• Cause: Calling methods that require identification
• Fix: Call identify() before these methods

"Request failed: ..."

• Cause: Network or API error
• Fix: Check API URL, network connection

"AsyncStorage error"

• Cause: AsyncStorage not installed or configured
• Fix: Install @react-native-async-storage/async-storage and run pod install

---

Next Steps

• API Reference - Review method documentation
• Configuration - Check configuration options
• Examples - See working examples