Troubleshooting

Common issues and solutions when using the Tappd Web SDK.

SDK Not Initializing

Problem: SDK fails to initialize

Symptoms:

• Error in console: "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 script is loaded before initialization

---

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:

   • Open browser DevTools → Network tab
   • Filter by "track" or "api"
   • 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 is correct
});

4. Check CORS issues:
   • Ensure API endpoint allows requests from your domain
   • Check browser console for CORS errors

---

Anonymous Data Not Merging

Problem: Anonymous events not linked after identification

Symptoms:

• Events tracked before identify() don't appear linked
• User journey incomplete

Solutions:

1. Ensure identify() is called with valid external_id:

// ❌ Wrong: Events tracked but user never identified
await tappd.track('page_view');
await tappd.track('button_click');
// Events tracked with anonymousId

// ✅ Correct: Identify user to merge data
await tappd.identify({
  external_id: 'user_123',  // Required: Your internal user ID
  email: 'john@example.com'
});
// Previous anonymous events now merged to user_123

2. What if identify() is never called?

   • User remains anonymous permanently
   • All events continue to be tracked with anonymousId
   • Events cannot be linked to a specific user later (unless you call identify() with the matching context)

3. What if external_id is invalid (null/undefined/empty)?

   • SDK will throw an error: "external_id is required in attributes"
   • Always provide a valid, non-empty external_id in the attributes object

4. Check anonymous ID:

const anonymousId = tappd.getAnonymousId();
console.log('Anonymous ID:', anonymousId);
// Should be same before and after identify()

3. Verify timing:

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

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

// Future events linked to user_123
await tappd.track('event_3');

---

Session Issues

Problem: Sessions not starting or expiring incorrectly

Symptoms:

• No session IDs in events
• Sessions restarting too frequently

Solutions:

1. Check session timeout:

// If sessions expire too quickly
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

3. Check page visibility:
   • Sessions pause when tab is hidden
   • This is expected behavior
   • Session resumes when tab becomes visible

---

SPA Navigation Not Tracking

Problem: Page views not tracked in Single Page App

Symptoms:

• Only initial page view tracked
• Route changes not captured

Solutions:

1. Enable autoTrack (default):

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  autoTrack: true // Should be true (default)
});

2. Manual tracking for custom routers:

// In your router
router.beforeEach((to, from) => {
  tappd.trackPageView(to.fullPath, {
    from: from.fullPath,
    routeName: to.name
  });
});

3. Check History API support:
   • SDK uses history.pushState interception
   • Works with most modern routers (Vue Router, React Router, etc.)

---

localStorage Issues

Problem: Anonymous ID not persisting

Symptoms:

• New anonymous ID on every page load
• User appears as new each visit

Solutions:

1. Check localStorage support:

if (typeof Storage === 'undefined') {
  console.error('localStorage not supported');
}

2. Check browser settings:

   • Ensure cookies/localStorage enabled
   • Not in incognito/private mode (or expect different behavior)

3. Check for conflicts:

   • Other scripts clearing localStorage
   • Browser extensions blocking storage

---

CORS Errors

Problem: CORS policy blocking requests

Symptoms:

• Console errors: "CORS policy" or "Access-Control-Allow-Origin"
• Network requests failing

Solutions:

1. Verify API endpoint:

   • Ensure https://sdk.gotappd.com is accessible
   • Check API server CORS configuration

2. Contact support:

   • If using custom domain, ensure CORS is configured
   • Provide your domain for whitelisting

---

TypeScript Errors

Problem: Type errors in TypeScript projects

Solutions:

1. Install types:

npm install --save-dev @types/node

2. Import types:

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

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

const tappd = new TappdSDK(config);

---

Build Tool Issues

Problem: SDK not working with Webpack/Vite/etc.

Solutions:

1. Check module resolution:

// ES Module
import { TappdSDK } from '@tappd/web-sdk';

// CommonJS
const { TappdSDK } = require('@tappd/web-sdk');

2. Check bundle size:

   • SDK is lightweight (~10KB)
   • Should not cause bundle size issues

3. Tree shaking:

   • SDK exports are optimized
   • Unused code should be eliminated

---

Debug Mode

Enable debug mode to troubleshoot:

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

// Console output:
// [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 browser console for errors
2. Enable debug mode and review logs
3. Verify network requests in DevTools
4. Check SDK version - ensure using latest
5. Contact support with:
   • Error messages
   • Browser/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, CORS

---

Next Steps

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