Integration Best Practices

Building a robust health data integration requires more than API calls. This guide covers permission flows, error handling, data sync strategies, privacy compliance, and production deployment best practices.

1. Permission & Onboarding Flow

✅ Good Permission Flow (Progressive)

// Before showing system permission dialog
showCustomDialog({
  title: "Enable Sleep Tracking",
  message: "We'll analyze your sleep patterns to recommend optimal bedtimes and detect sleep debt.",
  benefits: ["Personalized sleep schedule", "Sleep quality trends", "Energy predictions"],
  onAccept: () => requestHealthKitPermission('sleepAnalysis')
})

❌ Bad Permission Flow (All-or-Nothing)

// DON'T DO THIS
onAppLaunch() {
  requestHealthKitPermission([
    'stepCount', 'heartRate', 'sleepAnalysis',
    'activeEnergy', 'weight', 'bodyFat',
    'bloodPressure', 'vo2Max', 'respiratoryRate'
  ])
  // 10+ permissions at once = user panic
}

// System dialog with no context
"MyApp would like to access your Health data"
[Don't Allow] [OK]

// User thinks: "Why? What data? No thanks."

2. Data Sync Strategy

Real-time vs Batch Sync

Webhook Implementation Best Practices

// ✅ GOOD: Webhook endpoint with signature verification
app.post('/webhooks/sahha', async (req, res) => {
  // 1. Verify signature (prevent spoofing)
  const signature = req.headers['x-signature']
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex')

  if (signature !== expectedSignature) {
    return res.status(401).json({ error: 'Invalid signature' })
  }

  // 2. Acknowledge immediately (respond within 5 seconds)
  res.status(200).json({ received: true })

  // 3. Process asynchronously (don't block response)
  processWebhookAsync(req.body)
    .catch(err => logger.error('Webhook processing failed', err))
})

async function processWebhookAsync(payload) {
  // 4. Idempotency check (prevent duplicate processing)
  const eventId = payload.id
  const processed = await db.query('SELECT 1 FROM processed_events WHERE id = ?', [eventId])
  if (processed.length > 0) return

  // 5. Process event
  await handleSleepScoreUpdate(payload)

  // 6. Mark as processed
  await db.query('INSERT INTO processed_events (id, processed_at) VALUES (?, NOW())', [eventId])
}

Background Sync (Mobile Apps)

// ✅ iOS Background Fetch (every 1-6 hours)
func application(_ application: UIApplication,
                 performFetchWithCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {

  syncHealthData { result in
    switch result {
    case .newData:
      completionHandler(.newData)
    case .noData:
      completionHandler(.noData)
    case .failed:
      completionHandler(.failed)
    }
  }
}

// ✅ Android WorkManager (periodic sync)
val syncWork = PeriodicWorkRequestBuilder(
  repeatInterval = 6, repeatIntervalTimeUnit = TimeUnit.HOURS
).setConstraints(
  Constraints.Builder()
    .setRequiredNetworkType(NetworkType.CONNECTED)
    .setRequiresBatteryNotLow(true)
    .build()
).build()

WorkManager.getInstance(context).enqueue(syncWork)

3. Error Handling & Retry Logic

✅ Robust Error Handling

// ✅ GOOD: Exponential backoff with max retries
async function syncWithRetry(userId, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const data = await fetchHealthData(userId)
      return data

    } catch (error) {
      if (error.status === 429) {
        // Rate limit - wait longer
        const waitTime = Math.pow(2, attempt) * 1000 // 2s, 4s, 8s
        await sleep(waitTime)
        continue

      } else if (error.status === 401) {
        // Token expired - refresh and retry
        await refreshToken(userId)
        continue

      } else if (error.status === 403) {
        // Permissions revoked - notify user, stop retrying
        await notifyPermissionsRevoked(userId)
        throw error

      } else if (error.status >= 500) {
        // Server error - retry with backoff
        if (attempt < maxRetries) {
          await sleep(Math.pow(2, attempt) * 1000)
          continue
        }
      }

      // Unrecoverable error or max retries reached
      throw error
    }
  }
}

❌ Bad Error Handling

// ❌ DON'T DO THIS: No retry, no context
async function syncHealthData(userId) {
  try {
    const data = await fetchHealthData(userId)
    return data
  } catch (error) {
    console.log('Failed to sync') // Vague error, no recovery
    return null // Silent failure - user never knows
  }
}

4. Privacy & Compliance

Data Minimization

// Fitness app only needs activity data
const dataTypes = [
  'stepCount',
  'activeEnergy',
  'distanceWalking'
]
// Don't request: heart rate, sleep, weight, etc.

// DON'T DO THIS
const dataTypes = [
  'stepCount', 'heartRate', 'sleepAnalysis',
  'weight', 'bodyFat', 'bloodPressure',
  'bloodGlucose', 'vo2Max', 'respiratoryRate',
  'menstrualFlow', 'sexualActivity'
  // ... 50+ more biomarkers you don't use
]

5. Performance Optimization

Reduce API Calls

// GOOD: Single query for multiple biomarkers
const data = await sahha.getBiomarkers({
  types: ['sleep', 'activity', 'readiness'],
  startDate: '2025-10-01',
  endDate: '2025-10-16'
})
// 1 API call for 3 biomarker types

// BAD: Separate query per biomarker
const sleep = await sahha.getSleep(...)
const activity = await sahha.getActivity(...)
const readiness = await sahha.getReadiness(...)
// 3 API calls (3x latency, 3x rate limit usage)

Cache Intelligently

// ✅ GOOD: Cache with TTL (Time To Live)
async function getHealthData(userId, date) {
  const cacheKey = `health:${userId}:${date}`

  // Check cache first
  const cached = await redis.get(cacheKey)
  if (cached) return JSON.parse(cached)

  // Fetch from API
  const data = await sahha.getBiomarkers({ userId, date })

  // Cache with appropriate TTL
  const ttl = isToday(date) ? 3600 : 86400 // 1 hour for today, 24 hours for past
  await redis.setex(cacheKey, ttl, JSON.stringify(data))

  return data
}

Pagination for Large Datasets

// ✅ GOOD: Paginate when fetching historical data
async function fetchAllBiomarkers(userId, startDate, endDate) {
  let allData = []
  let page = 1
  const pageSize = 100

  while (true) {
    const response = await sahha.getBiomarkers({
      userId,
      startDate,
      endDate,
      page,
      pageSize
    })

    allData = allData.concat(response.data)

    if (response.data.length < pageSize) break // Last page
    page++
  }

  return allData
}

6. User Experience Best Practices

Handle Missing Data Gracefully

Loading States

// ✅ GOOD: Progressive loading with skeleton UI
function HealthDashboard() {
  const [data, setData] = useState(null)
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    fetchHealthData().then(data => {
      setData(data)
      setLoading(false)
    })
  }, [])

  if (loading) {
    return  // Show layout with animated placeholders
  }

  return 
}

7. Testing Strategy

Staging Environment Best Practices

// ✅ GOOD: Separate staging credentials
const config = {
  production: {
    apiKey: process.env.SAHHA_PROD_API_KEY,
    webhookUrl: 'https://api.myapp.com/webhooks/sahha'
  },
  staging: {
    apiKey: process.env.SAHHA_STAGING_API_KEY,
    webhookUrl: 'https://staging.myapp.com/webhooks/sahha'
  }
}

// Use test/demo profiles in staging
const userId = IS_PRODUCTION ? user.id : 'demo-user-001'

8. Monitoring & Alerts

Key Metrics to Track

Logging Best Practices

// ✅ GOOD: Structured logging with context
logger.info('Health data sync started', {
  userId: user.id,
  dataTypes: ['sleep', 'activity'],
  dateRange: { start: '2025-10-01', end: '2025-10-16' },
  platform: 'sahha'
})

logger.error('Sync failed', {
  userId: user.id,
  error: err.message,
  errorCode: err.status,
  retryCount: 3,
  platform: 'sahha'
})

// Enables filtering: "Show all Sahha errors for userId=123"

9. Production Deployment Checklist

10. Common Pitfalls to Avoid