Troubleshooting

Common issues and solutions when working with Appizer

Solutions to common problems when integrating Appizer.

Authentication Issues

API Key Not Working

Symptom: Receiving 401 Unauthorized errors

Solution:

  1. Verify API Key Format
    Ensure your API key starts with `sk_live_` or `sk_test_`
  2. Check Environment Variables
    Confirm the API key is properly loaded from environment variables ```typescript console.log('API Key:', process.env.APPIZER_API_KEY?.substring(0, 10) + '...') ```
  3. Regenerate API Key
    If the key is compromised, generate a new one from your dashboard

Security

Never log your full API key. Only log the first few characters for debugging.

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:

typescript

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

Public vs Secret Keys

Use public keys (`pk_`) in browser environments and secret keys (`sk_`) on the server.

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

    typescript
    // ❌ Wrong
appizer.track({ name: 'signup' })

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

  3. Missing User Identifier

    • Events require either userId or anonymousId
    typescript
    appizer.track({
  event: 'page_view',
  userId: 'user_123', // or anonymousId
})

Duplicate Events

Symptom: Same event tracked multiple times

Solution:

Implement idempotency keys:

typescript
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:

typescript
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
      }
    }
  }
}

Batch requests

Use `batchTrack()` to send multiple events in a single request and reduce rate limit impact.

SDK Issues

TypeScript Type Errors

Symptom: Type errors when using the SDK

Solution:

Ensure you have the latest SDK version:

bash
npm install @appizer/sdk@latest

Add type definitions to your tsconfig.json:

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

Module Not Found

Symptom: Cannot find module '@appizer/sdk'

Solution:

  1. Reinstall Dependencies
    ```bash rm -rf node_modules package-lock.json npm install ```
  2. Check Package.json
    Verify the SDK is listed in dependencies
  3. Clear Build Cache
    ```bash 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:

typescript
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:

typescript
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

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

  2. Use Specific Filters

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

  3. Limit Result Size

    typescript
    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:

typescript
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?

Support Response Times

- **Critical Issues:** < 1 hour - **High Priority:** < 4 hours - **Normal Priority:** < 24 hours
On this page