Troubleshooting

Solutions to common problems when integrating Appizer.

Authentication Issues

API Key Not Working

Symptom: Receiving 401 Unauthorized errors

Solution:

console.log('API Key:', process.env.APPIZER_API_KEY?.substring(0, 10) + '...')

CORS Errors in Browser

Symptom: CORS policy blocking requests from browser

Solution:

Browser-based applications should use the client-side SDK, not direct API calls:

import { AppizerClient } from '@appizer/client-sdk'

const appizer = new AppizerClient({
  publicKey: process.env.NEXT_PUBLIC_APPIZER_PUBLIC_KEY,
})

Event Tracking Issues

Events Not Appearing in Dashboard

Symptom: Events tracked but not visible in analytics

Possible Causes:

1. Processing Delay

   • Events may take 1-2 minutes to appear
   • Check the dashboard's time range filter

2. Invalid Event Format

   Copy

   // ❌ Wrong
   appizer.track({ name: 'signup' })
   
   // ✅ Correct
   appizer.track({ event: 'signup', userId: 'user_123' })
   

3. Missing User Identifier

   • Events require either userId or anonymousId
   Copy

   appizer.track({
     event: 'page_view',
     userId: 'user_123', // or anonymousId
   })
   

Duplicate Events

Symptom: Same event tracked multiple times

Solution:

Implement idempotency keys:

appizer.track({
  event: 'purchase_completed',
  userId: 'user_123',
  properties: {
    orderId: 'order_456',
  },
  idempotencyKey: 'order_456', // Prevents duplicates
})

Rate Limiting

429 Too Many Requests

Symptom: Receiving rate limit errors

Solution:

Implement exponential backoff and batch requests:

async function trackWithBackoff(event, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await appizer.track(event)
    } catch (error) {
      if (error.status === 429 && i < retries - 1) {
        const delay = Math.pow(2, i) * 1000
        await new Promise(resolve => setTimeout(resolve, delay))
      } else {
        throw error
      }
    }
  }
}

SDK Issues

TypeScript Type Errors

Symptom: Type errors when using the SDK

Solution:

Ensure you have the latest SDK version:

npm install @appizer/sdk@latest

Add type definitions to your tsconfig.json:

{
  "compilerOptions": {
    "types": ["@appizer/sdk"]
  }
}

Module Not Found

Symptom: Cannot find module '@appizer/sdk'

Solution:

rm -rf node_modules package-lock.json
npm install

npm run clean
npm run build

Push Notification Issues

Notifications Not Delivered

Symptom: Push notifications sent but not received

Checklist:

• Device token is valid and up-to-date
• User has granted notification permissions
• App is configured with correct FCM/APNS credentials
• Device is online and reachable
• Notification payload is valid

Debug Steps:

const result = await appizer.push.send({
  userId: 'user_123',
  notification: {
    title: 'Test',
    body: 'Testing notifications',
  },
})

console.log('Delivery status:', result.status)
console.log('Failed devices:', result.failed)

Invalid Device Token

Symptom: Error: "Invalid device token"

Solution:

Update the device token:

await appizer.identify({
  userId: 'user_123',
  traits: {
    deviceToken: 'new_valid_token',
    platform: 'ios', // or 'android', 'web'
  },
})

Analytics Query Issues

Slow Query Performance

Symptom: Analytics queries taking too long

Optimization Tips:

1. Add Time Range Filters

   Copy

   const metrics = await appizer.analytics.query({
     startDate: '2024-01-01',
     endDate: '2024-01-31', // Limit time range
   })
   

2. Use Specific Filters

   Copy

   const metrics = await appizer.analytics.query({
     filters: [
       { property: 'event', operator: 'equals', value: 'purchase' }
     ]
   })
   

3. Limit Result Size

   Copy

   const metrics = await appizer.analytics.query({
     limit: 1000, // Don't fetch more than needed
   })
   

Query Timeout

Symptom: Query times out before completing

Solution:

Break large queries into smaller chunks:

async function queryInChunks(startDate, endDate, chunkDays = 7) {
  const results = []
  let current = new Date(startDate)
  const end = new Date(endDate)
  
  while (current < end) {
    const chunkEnd = new Date(current)
    chunkEnd.setDate(chunkEnd.getDate() + chunkDays)
    
    const chunk = await appizer.analytics.query({
      startDate: current.toISOString(),
      endDate: chunkEnd.toISOString(),
    })
    
    results.push(chunk)
    current = chunkEnd
  }
  
  return results
}

Getting Help

Still Having Issues?