Every 5 minutes]) Start --> GetUsers[Get Users to Sync
Priority Queue] GetUsers --> CalcBatch{Calculate Batch Size
Based on Rate Limit} CalcBatch --> Priority[Prioritize Users:
1. Expires within 7 days
2. Billing issues
3. Recently cancelled
4. Stale cache 24h+
5. Random sample] Priority --> BatchLoop{More users
in batch?} BatchLoop -->|YES| FetchRC[Fetch from
RevenueCat V2 API] FetchRC --> Compare{Status
matches DB?} Compare -->|NO - Mismatch| SyncDB[Sync Database
with RevenueCat] Compare -->|YES - Match| LogSuccess[Log: In Sync] SyncDB --> UpdateMetrics[Update Sync Metrics] LogSuccess --> UpdateMetrics UpdateMetrics --> RateLimit[Sleep to respect
rate limit] RateLimit --> BatchLoop BatchLoop -->|NO| Complete[Log Completion
Report Discrepancies] Complete --> End([End]) style Start fill:#e1f5e1 style End fill:#e1e1e1 style FetchRC fill:#fff4e1 style SyncDB fill:#ffe1e1 style CalcBatch fill:#e1f0ff style Compare fill:#ffe1e1 style Priority fill:#f0f0f0 ``` *** ## Rate Limit Calculation ### RevenueCat API Limits **Hard Limit:** 480 requests per minute (8 requests per second) ### Safe Operating Parameters ```javascript theme={null} const RATE_LIMITS = { MAX_REQUESTS_PER_MINUTE: 480, SAFE_BUFFER: 0.7, // Use only 70% of limit (336 req/min) CRON_INTERVAL_MINUTES: 5, REQUESTS_PER_SECOND: 5.6, // 336 / 60 seconds MS_BETWEEN_REQUESTS: 179 // 1000ms / 5.6 }; // Calculate max users per cron run const MAX_USERS_PER_RUN = Math.floor( RATE_LIMITS.MAX_REQUESTS_PER_MINUTE * RATE_LIMITS.SAFE_BUFFER * RATE_LIMITS.CRON_INTERVAL_MINUTES ); // Result: 1,680 users per 5-minute run ``` ### Why 70% Buffer? 1. **Other API usage:** Your app makes real-time API calls 2. **Webhook responses:** RevenueCat may call your webhook handlers 3. **Burst protection:** Avoid hitting rate limit spikes 4. **Multiple services:** Other systems may use the same API key *** ## Implementation ### Core Sync Function ```javascript theme={null} const REVENUECAT_API_KEY = process.env.REVENUECAT_API_KEY; const REVENUECAT_PROJECT_ID = process.env.REVENUECAT_PROJECT_ID; // Rate limit configuration const RATE_LIMIT = { MAX_PER_MINUTE: 480, SAFE_BUFFER: 0.7, SAFE_REQUESTS_PER_MINUTE: 480 * 0.7, // 336 MS_BETWEEN_REQUESTS: (60 * 1000) / (480 * 0.7), // ~179ms MAX_PER_5MIN_RUN: 336 * 5 // 1,680 users }; /** * Main cron job function * Runs every 5 minutes */ async function syncSubscriptionsWithRevenueCat() { const startTime = Date.now(); console.log(' Starting subscription sync job...'); try { // Step 1: Get users to sync (prioritized) const usersToSync = await getUsersForSync(RATE_LIMIT.MAX_PER_5MIN_RUN); console.log(`Found ${usersToSync.length} users to sync`); // Step 2: Process in batches with rate limiting const results = { total: usersToSync.length, synced: 0, matched: 0, discrepancies: 0, errors: 0, notFound: 0 }; for (let i = 0; i < usersToSync.length; i++) { const user = usersToSync[i]; try { // Fetch from RevenueCat V2 const rcData = await fetchCustomerDataV2( user.app_user_id, REVENUECAT_PROJECT_ID ); if (!rcData) { results.notFound++; await logSyncResult(user.app_user_id, 'not_found'); continue; } // Compare with database const hasDiscrepancy = await detectDiscrepancy(user, rcData); if (hasDiscrepancy) { // Sync database with RevenueCat await syncDatabaseWithRevenueCat(user.app_user_id, rcData); results.discrepancies++; results.synced++; console.log(` Synced ${user.app_user_id} - discrepancy found`); await logSyncResult(user.app_user_id, 'synced', hasDiscrepancy); } else { results.matched++; await logSyncResult(user.app_user_id, 'matched'); } } catch (error) { results.errors++; console.error(` Error syncing ${user.app_user_id}:`, error.message); await logSyncError(user.app_user_id, error); } // Rate limiting: sleep between requests if (i < usersToSync.length - 1) { await sleep(RATE_LIMIT.MS_BETWEEN_REQUESTS); } // Progress logging every 100 users if ((i + 1) % 100 === 0) { console.log(`Progress: ${i + 1}/${usersToSync.length} users processed`); } } // Step 3: Log completion const duration = ((Date.now() - startTime) / 1000).toFixed(2); console.log(' Sync job completed', { duration: `${duration}s`, ...results, discrepancyRate: `${((results.discrepancies / results.total) * 100).toFixed(2)}%` }); // Step 4: Alert if discrepancy rate is high const discrepancyRate = results.discrepancies / results.total; if (discrepancyRate > 0.05) { await sendAlert('High subscription discrepancy rate', { rate: `${(discrepancyRate * 100).toFixed(2)}%`, total: results.total, discrepancies: results.discrepancies }); } // Step 5: Store metrics await storeSyncMetrics({ timestamp: new Date(), duration_seconds: duration, ...results }); return results; } catch (error) { console.error(' Sync job failed:', error); await sendAlert('Subscription sync job failed', { error: error.message }); throw error; } } /** * Get users for sync - prioritized queue */ async function getUsersForSync(limit) { // Priority 1: Subscriptions expiring within 7 days const expiringUsers = await db.query(` SELECT app_user_id, is_active, expires_at, last_revenuecat_sync_at FROM user_subscriptions WHERE is_active = true AND expires_at IS NOT NULL AND expires_at BETWEEN NOW() AND NOW() + INTERVAL '7 days' ORDER BY expires_at ASC LIMIT $1 `, [Math.floor(limit * 0.3)]); // 30% of quota // Priority 2: Billing issues const billingIssueUsers = await db.query(` SELECT app_user_id, is_active, expires_at, last_revenuecat_sync_at FROM user_subscriptions WHERE billing_issue = true AND is_active = true ORDER BY last_updated ASC LIMIT $1 `, [Math.floor(limit * 0.2)]); // 20% of quota // Priority 3: Recently cancelled (within 48 hours) const recentlyCancelledUsers = await db.query(` SELECT app_user_id, is_active, expires_at, last_revenuecat_sync_at FROM user_subscriptions WHERE subscription_status = 'cancelled' AND cancelled_at > NOW() - INTERVAL '48 hours' ORDER BY cancelled_at DESC LIMIT $1 `, [Math.floor(limit * 0.2)]); // 20% of quota // Priority 4: Stale cache (not synced in 24+ hours) const staleCacheUsers = await db.query(` SELECT app_user_id, is_active, expires_at, last_revenuecat_sync_at FROM user_subscriptions WHERE (last_revenuecat_sync_at IS NULL OR last_revenuecat_sync_at < NOW() - INTERVAL '24 hours') AND is_active = true ORDER BY last_revenuecat_sync_at ASC NULLS FIRST LIMIT $1 `, [Math.floor(limit * 0.2)]); // 20% of quota // Priority 5: Random sample of active users const randomUsers = await db.query(` SELECT app_user_id, is_active, expires_at, last_revenuecat_sync_at FROM user_subscriptions WHERE is_active = true ORDER BY RANDOM() LIMIT $1 `, [Math.floor(limit * 0.1)]); // 10% of quota // Combine and deduplicate const allUsers = [ ...expiringUsers.rows, ...billingIssueUsers.rows, ...recentlyCancelledUsers.rows, ...staleCacheUsers.rows, ...randomUsers.rows ]; // Remove duplicates by app_user_id const uniqueUsers = Array.from( new Map(allUsers.map(user => [user.app_user_id, user])).values() ); return uniqueUsers.slice(0, limit); } /** * Detect discrepancy between database and RevenueCat */ async function detectDiscrepancy(dbUser, rcData) { // Check if active status matches const dbIsActive = dbUser.is_active; const rcIsActive = rcData.active_entitlements?.items?.some( ent => ent.expires_at > Date.now() ); if (dbIsActive !== rcIsActive) { return { type: 'active_status', db: dbIsActive, rc: rcIsActive }; } // Check if entitlements match const dbEntitlements = dbUser.entitlements || {}; const rcEntitlements = {}; rcData.active_entitlements?.items?.forEach(ent => { if (ent.expires_at > Date.now()) { rcEntitlements[ent.entitlement_id] = ent.expires_at; } }); const dbEntIds = Object.keys(dbEntitlements).sort(); const rcEntIds = Object.keys(rcEntitlements).sort(); if (JSON.stringify(dbEntIds) !== JSON.stringify(rcEntIds)) { return { type: 'entitlements', db: dbEntIds, rc: rcEntIds }; } // Check if expiration dates match (within 1 minute tolerance) if (dbUser.expires_at && rcData.active_entitlements?.items?.length > 0) { const dbExpiresMs = new Date(dbUser.expires_at).getTime(); const rcExpiresMs = Math.max( ...rcData.active_entitlements.items.map(ent => ent.expires_at) ); const diffMs = Math.abs(dbExpiresMs - rcExpiresMs); if (diffMs > 60000) { // More than 1 minute difference return { type: 'expiration_date', db: new Date(dbExpiresMs).toISOString(), rc: new Date(rcExpiresMs).toISOString(), diff_minutes: (diffMs / 60000).toFixed(2) }; } } return null; // No discrepancy } /** * Utility: Sleep function for rate limiting */ function sleep(ms) { return new Promise(resolve => setTimeout(resolve, ms)); } /** * Log sync result to database */ async function logSyncResult(appUserId, status, discrepancy = null) { await db.query(` INSERT INTO sync_logs ( app_user_id, status, discrepancy, synced_at ) VALUES ($1, $2, $3, NOW()) `, [ appUserId, status, discrepancy ? JSON.stringify(discrepancy) : null ]); } /** * Log sync error */ async function logSyncError(appUserId, error) { await db.query(` INSERT INTO sync_errors ( app_user_id, error_message, error_stack, occurred_at ) VALUES ($1, $2, $3, NOW()) `, [ appUserId, error.message, error.stack ]); } /** * Store sync metrics for monitoring */ async function storeSyncMetrics(metrics) { await db.query(` INSERT INTO sync_metrics ( timestamp, duration_seconds, total_users, synced_count, matched_count, discrepancies_count, errors_count, not_found_count, discrepancy_rate ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9) `, [ metrics.timestamp, metrics.duration_seconds, metrics.total, metrics.synced, metrics.matched, metrics.discrepancies, metrics.errors, metrics.notFound, metrics.discrepancies / metrics.total ]); } /** * Send alert for critical issues */ async function sendAlert(title, details) { // TODO: Implement with your alerting system // Examples: Email, Slack, PagerDuty, etc. console.error(` ALERT: ${title}`, details); // Example Slack webhook: // await fetch(process.env.SLACK_WEBHOOK_URL, { // method: 'POST', // headers: { 'Content-Type': 'application/json' }, // body: JSON.stringify({ // text: ` ${title}`, // attachments: [{ text: JSON.stringify(details, null, 2) }] // }) // }); } module.exports = { syncSubscriptionsWithRevenueCat, getUsersForSync, detectDiscrepancy }; ``` *** ## Cron Schedule Configuration ### Node.js with node-cron ```javascript theme={null} const cron = require('node-cron'); const { syncSubscriptionsWithRevenueCat } = require('./sync-job'); // Run every 5 minutes cron.schedule('*/5 * * * *', async () => { console.log(' Cron job triggered:', new Date().toISOString()); try { await syncSubscriptionsWithRevenueCat(); } catch (error) { console.error('Cron job failed:', error); } }); console.log(' Cron job scheduled: Every 5 minutes'); ``` ### System Crontab ``` # Edit crontab crontab -e # Add this line (runs every 5 minutes) */5 * * * * /usr/bin/node /path/to/your/app/sync-job.js >> /var/log/revenuecat-sync.log 2>&1 ``` ### Vercel Cron (Next.js) ```javascript theme={null} // vercel.json { "crons": [ { "path": "/api/cron/sync-subscriptions", "schedule": "*/5 * * * *" } ] } // pages/api/cron/sync-subscriptions.js import { syncSubscriptionsWithRevenueCat } from '@/lib/sync-job'; export default async function handler(req, res) { // Verify cron secret if (req.headers.authorization !== `Bearer ${process.env.CRON_SECRET}`) { return res.status(401).json({ error: 'Unauthorized' }); } try { const results = await syncSubscriptionsWithRevenueCat(); return res.json({ success: true, results }); } catch (error) { return res.status(500).json({ error: error.message }); } } ``` ### AWS Lambda with EventBridge ```javascript theme={null} // handler.js exports.handler = async (event) => { const { syncSubscriptionsWithRevenueCat } = require('./sync-job'); try { const results = await syncSubscriptionsWithRevenueCat(); return { statusCode: 200, body: JSON.stringify(results) }; } catch (error) { console.error('Lambda sync failed:', error); return { statusCode: 500, body: JSON.stringify({ error: error.message }) }; } }; // EventBridge rule (CloudFormation/Terraform) // Rate: rate(5 minutes) ``` *** ## Database Schema ### Sync Logs Table ```sql theme={null} CREATE TABLE sync_logs ( id SERIAL PRIMARY KEY, app_user_id VARCHAR(255) NOT NULL, status VARCHAR(50) NOT NULL, -- matched, synced, not_found discrepancy JSONB, synced_at TIMESTAMP DEFAULT NOW() ); CREATE INDEX idx_sync_logs_user ON sync_logs(app_user_id); CREATE INDEX idx_sync_logs_status ON sync_logs(status); CREATE INDEX idx_sync_logs_synced_at ON sync_logs(synced_at); ``` ### Sync Errors Table ```sql theme={null} CREATE TABLE sync_errors ( id SERIAL PRIMARY KEY, app_user_id VARCHAR(255) NOT NULL, error_message TEXT, error_stack TEXT, occurred_at TIMESTAMP DEFAULT NOW() ); CREATE INDEX idx_sync_errors_user ON sync_errors(app_user_id); CREATE INDEX idx_sync_errors_occurred_at ON sync_errors(occurred_at); ``` ### Sync Metrics Table ```sql theme={null} CREATE TABLE sync_metrics ( id SERIAL PRIMARY KEY, timestamp TIMESTAMP NOT NULL, duration_seconds DECIMAL(10, 2), total_users INTEGER, synced_count INTEGER, matched_count INTEGER, discrepancies_count INTEGER, errors_count INTEGER, not_found_count INTEGER, discrepancy_rate DECIMAL(5, 4) ); CREATE INDEX idx_sync_metrics_timestamp ON sync_metrics(timestamp); ``` *** ## Monitoring and Alerts ### Key Metrics to Track ```javascript theme={null} async function getSyncHealthMetrics() { // Last 24 hours const metrics = await db.query(` SELECT COUNT(*) as total_runs, AVG(duration_seconds) as avg_duration, SUM(total_users) as total_users_processed, SUM(discrepancies_count) as total_discrepancies, AVG(discrepancy_rate) as avg_discrepancy_rate, SUM(errors_count) as total_errors FROM sync_metrics WHERE timestamp > NOW() - INTERVAL '24 hours' `); return metrics.rows[0]; } // Alert thresholds const ALERT_THRESHOLDS = { DISCREPANCY_RATE: 0.05, // 5% ERROR_RATE: 0.02, // 2% DURATION_SECONDS: 240, // 4 minutes (should complete in < 5 min) CONSECUTIVE_FAILURES: 3 }; ``` ### Health Check Endpoint ```javascript theme={null} // GET /api/health/sync-job async function handleSyncHealthCheck(req, res) { const metrics = await getSyncHealthMetrics(); const health = { status: 'healthy', metrics, issues: [] }; // Check discrepancy rate if (metrics.avg_discrepancy_rate > ALERT_THRESHOLDS.DISCREPANCY_RATE) { health.status = 'warning'; health.issues.push({ severity: 'warning', message: 'High discrepancy rate detected', value: `${(metrics.avg_discrepancy_rate * 100).toFixed(2)}%` }); } // Check error rate const errorRate = metrics.total_errors / metrics.total_users_processed; if (errorRate > ALERT_THRESHOLDS.ERROR_RATE) { health.status = 'warning'; health.issues.push({ severity: 'warning', message: 'High error rate detected', value: `${(errorRate * 100).toFixed(2)}%` }); } // Check if job ran recently (within 10 minutes) const lastRun = await db.query(` SELECT timestamp FROM sync_metrics ORDER BY timestamp DESC LIMIT 1 `); if (lastRun.rows[0]) { const minutesSinceLastRun = (Date.now() - new Date(lastRun.rows[0].timestamp).getTime()) / 60000; if (minutesSinceLastRun > 10) { health.status = 'unhealthy'; health.issues.push({ severity: 'critical', message: 'Sync job not running', value: `Last run: ${minutesSinceLastRun.toFixed(0)} minutes ago` }); } } return res.json(health); } ``` *** ## Best Practices ### 1. Gradual Rollout Start with a small percentage of users: ```javascript theme={null} // Phase 1: 10% of users const limit = Math.floor(RATE_LIMIT.MAX_PER_5MIN_RUN * 0.1); // Phase 2: 50% of users (after 1 week) const limit = Math.floor(RATE_LIMIT.MAX_PER_5MIN_RUN * 0.5); // Phase 3: 100% of users (after 2 weeks) const limit = RATE_LIMIT.MAX_PER_5MIN_RUN; ``` ### 2. Avoid Peak Hours Skip sync during high-traffic periods: ```javascript theme={null} function shouldSkipSync() { const hour = new Date().getUTCHours(); // Skip 12pm-2pm UTC (peak usage) if (hour >= 12 && hour < 14) { console.log(' Skipping sync during peak hours'); return true; } return false; } async function syncSubscriptionsWithRevenueCat() { if (shouldSkipSync()) { return { skipped: true, reason: 'peak_hours' }; } // ... rest of sync logic } ``` ### 3. Circuit Breaker Stop sync if too many errors occur: ```javascript theme={null} const CIRCUIT_BREAKER = { MAX_CONSECUTIVE_ERRORS: 50, RESET_AFTER_MS: 5 * 60 * 1000 // 5 minutes }; let consecutiveErrors = 0; let circuitOpenedAt = null; async function syncWithCircuitBreaker(user) { // Check if circuit is open if (circuitOpenedAt) { const timeSinceOpened = Date.now() - circuitOpenedAt; if (timeSinceOpened < CIRCUIT_BREAKER.RESET_AFTER_MS) { throw new Error('Circuit breaker open - too many errors'); } else { // Reset circuit circuitOpenedAt = null; consecutiveErrors = 0; } } try { const result = await syncUser(user); consecutiveErrors = 0; // Reset on success return result; } catch (error) { consecutiveErrors++; if (consecutiveErrors >= CIRCUIT_BREAKER.MAX_CONSECUTIVE_ERRORS) { circuitOpenedAt = Date.now(); await sendAlert('Circuit breaker opened', { consecutiveErrors, lastError: error.message }); } throw error; } } ``` ### 4. Exponential Backoff for Rate Limits ```javascript theme={null} async function fetchWithRetry(appUserId, projectId, maxRetries = 3) { for (let attempt = 0; attempt < maxRetries; attempt++) { try { return await fetchCustomerDataV2(appUserId, projectId); } catch (error) { if (error.message.includes('429') || error.message.includes('rate limit')) { const backoffMs = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s console.warn(`Rate limited. Retrying in ${backoffMs}ms...`); await sleep(backoffMs); } else { throw error; } } } throw new Error('Max retries exceeded'); } ``` *** ## Performance Optimization ### Batch Database Queries ```javascript theme={null} // Instead of querying one by one for (const user of users) { const dbUser = await db.query('SELECT * FROM user_subscriptions WHERE app_user_id = $1', [user.app_user_id]); // ... } // Batch query const userIds = users.map(u => u.app_user_id); const dbUsers = await db.query(` SELECT * FROM user_subscriptions WHERE app_user_id = ANY($1) `, [userIds]); const dbUserMap = new Map(dbUsers.rows.map(u => [u.app_user_id, u])); ``` ### Parallel Processing (with rate limit) ```javascript theme={null} const pLimit = require('p-limit'); // Limit to 6 concurrent requests (respects ~6 req/sec) const limit = pLimit(6); const promises = users.map(user => limit(() => syncUser(user)) ); const results = await Promise.allSettled(promises); ``` *** ## Testing ### Manual Test ```javascript theme={null} // Test with single user async function testSync(appUserId) { const user = await db.query( 'SELECT * FROM user_subscriptions WHERE app_user_id = $1', [appUserId] ); const rcData = await fetchCustomerDataV2(appUserId, REVENUECAT_PROJECT_ID); const discrepancy = await detectDiscrepancy(user.rows[0], rcData); console.log('Discrepancy:', discrepancy); if (discrepancy) { await syncDatabaseWithRevenueCat(appUserId, rcData); console.log('Synced!'); } } testSync('user_abc123'); ``` ### Integration Test ```javascript theme={null} // Test full sync job with limited users async function testSyncJob() { // Override limit for testing const originalLimit = RATE_LIMIT.MAX_PER_5MIN_RUN; RATE_LIMIT.MAX_PER_5MIN_RUN = 10; // Test with 10 users const results = await syncSubscriptionsWithRevenueCat(); RATE_LIMIT.MAX_PER_5MIN_RUN = originalLimit; console.log('Test results:', results); } ``` *** ## Troubleshooting ### High Discrepancy Rate **Symptom:** > 5% of syncs show discrepancies **Possible Causes:** 1. Webhooks not being processed 2. Database write failures 3. Race conditions in webhook handler **Solution:** ```javascript theme={null} // Check webhook processing rate const webhookStats = await db.query(` SELECT COUNT(*) as total, COUNT(CASE WHEN processed_at IS NOT NULL THEN 1 END) as processed FROM processed_webhook_events WHERE created_at > NOW() - INTERVAL '24 hours' `); const processingRate = webhookStats.rows[0].processed / webhookStats.rows[0].total; console.log('Webhook processing rate:', `${(processingRate * 100).toFixed(2)}%`); ``` ### Job Taking Too Long **Symptom:** Sync job runs longer than 5 minutes **Solution:** Reduce batch size or increase frequency ```javascript theme={null} // Reduce to 70% capacity const limit = Math.floor(RATE_LIMIT.MAX_PER_5MIN_RUN * 0.7); ``` ### API Rate Limit Errors **Symptom:** Getting 429 errors from RevenueCat **Solution:** Increase sleep time between requests ```dotenv theme={null} RATE_LIMIT.MS_BETWEEN_REQUESTS = 250; // Slower (240 req/min) ``` *** ## Quick Reference ### Sync Job Configuration ```javascript theme={null} const CONFIG = { CRON_SCHEDULE: '*/5 * * * *', // Every 5 minutes BATCH_SIZE: 1680, // Users per run RATE_LIMIT: 336, // Requests per minute (70% of 480) MS_BETWEEN_REQUESTS: 179, // Milliseconds PRIORITY_WEIGHTS: { EXPIRING_SOON: 0.3, // 30% BILLING_ISSUES: 0.2, // 20% RECENTLY_CANCELLED: 0.2, // 20% STALE_CACHE: 0.2, // 20% RANDOM_SAMPLE: 0.1 // 10% } }; ``` ### Alert Thresholds ```javascript theme={null} const ALERTS = { DISCREPANCY_RATE: 0.05, // > 5% ERROR_RATE: 0.02, // > 2% MAX_DURATION: 240, // > 4 minutes STALE_JOB: 10 // No run in 10 minutes }; ``` ### Priority Queue Logic 1. **Expires within 7 days** (30%) - Catch expiring subscriptions 2. **Billing issues** (20%) - Resolve payment problems 3. **Recently cancelled** (20%) - Detect un-cancellations 4. **Stale cache 24h+** (20%) - Refresh old data 5. **Random sample** (10%) - General health check *** ## Summary **Cron job runs every 5 minutes**\ **Processes 1,680 users per run** (respects 70% rate limit buffer)\ **Prioritizes critical users** (expiring, billing issues, etc.)\ **Self-healing** - catches webhook failures automatically\ **Rate-limited** - 179ms between requests\ **Monitored** - tracks discrepancy rates and errors\ **Alerting** - notifies on high discrepancy/error rates **Combined with webhooks: 99.9%+ sync reliability** # User Session Source: https://setup.despia.com/best-practices/backend/revenuecat/user-session This guide covers user identity management for in-app purchases and subscriptions using RevenueCat in Despia apps. ## Overview RevenueCat requires linking each user to a unique identifier (`app_user_id`) that persists across sessions and devices. This identifier connects RevenueCat, OneSignal, and your backend database. ```mermaid theme={null} flowchart LR ID[app_user_id] --> RC[RevenueCat] ID --> OS[OneSignal] ID --> DB[(Your Database)] ``` RevenueCat receives the user identity only when launching a paywall via the `external_id` parameter: ```javascript theme={null} despia(`revenuecat://launchPaywall?external_id=${appUserId}&offering=default`); ``` *** ## Database Synchronization Requirement The user must exist in your database before they can make a purchase. When RevenueCat sends a webhook after a purchase, your backend must be able to locate the user to send push notifications. ### Successful Flow ```mermaid theme={null} sequenceDiagram participant App participant DB as Database participant RC as RevenueCat participant OS as OneSignal App->>DB: POST /api/user/register DB-->>App: User created Note over App: Paywall can now open safely App->>RC: Launch paywall with external_id Note over RC: User completes purchase RC->>DB: Webhook: INITIAL_PURCHASE DB->>DB: Find user by app_user_id DB->>OS: Send push notification OS->>App: Notification delivered ``` ### Failed Flow (Database Sync Missing) ```mermaid theme={null} sequenceDiagram participant App participant DB as Database participant RC as RevenueCat App->>DB: POST /api/user/register DB-->>App: Error (network failure) Note over App: Paywall opens without sync App->>RC: Launch paywall with external_id Note over RC: User completes purchase RC->>DB: Webhook: INITIAL_PURCHASE DB->>DB: User not found Note over DB: Cannot send notification ``` *** ## Identity Resolution On every app launch, resolve the user's identity using the following priority: | Priority | Source | Description | | :------- | :---------------- | :----------------------------------------- | | 1 | Storage Vault | Synced via iCloud/Google backup | | 2 | Restore Purchases | Recovers paying users via `externalUserId` | | 3 | Install ID | Fallback for new users (`despia.uuid`) | ```mermaid theme={null} flowchart TD Start([App Launch]) --> GetUUID[Get install_id from despia.uuid] GetUUID --> Vault[Read from Storage Vault] Vault --> VaultCheck{Found?} VaultCheck -->|Yes| UseVault[Use vault ID] VaultCheck -->|No| Restore[Query purchase history] Restore --> RestoreCheck{Found externalUserId?} RestoreCheck -->|Yes| UseRestore[Use restored ID] RestoreCheck -->|No| UseInstall[Use install_id] UseVault --> Persist[Persist to vault] UseRestore --> Lock[Lock identity] Lock --> Persist UseInstall --> Persist Persist --> SyncOS[Sync to OneSignal] SyncOS --> SyncDB[Sync to database] SyncDB --> Ready([Paywall can open]) ``` *** ## Implementation ### App Startup Execute this logic on every app launch. Track both identity resolution and database synchronization status before allowing paywall access. ```javascript theme={null} import despia from 'despia-native'; // State tracking let identityReady = false; let databaseSynced = false; let appUserId = null; let installId = null; async function initializeIdentity() { const ua = navigator.userAgent.toLowerCase(); if (!ua.includes('despia')) { identityReady = true; databaseSynced = true; return null; } installId = despia.uuid; let source = 'new'; // Step 1: Attempt to read from Storage Vault try { const vaultData = await despia('readvault://?key=app_user_id', ['app_user_id']); if (vaultData?.app_user_id) { appUserId = vaultData.app_user_id; source = 'vault'; } } catch (error) { // Vault read failed, continue to next source } // Step 2: Attempt to recover from purchase history if (!appUserId) { try { const data = await despia('getpurchasehistory://', ['restoredData']); const purchases = data.restoredData || []; // Prioritize active subscriptions, then most recent purchase const activePurchase = purchases.find(p => p.isActive && p.externalUserId); const recentPurchase = purchases .filter(p => p.externalUserId) .sort((a, b) => new Date(b.purchaseDate) - new Date(a.purchaseDate))[0]; const recoveredId = activePurchase?.externalUserId || recentPurchase?.externalUserId; if (recoveredId) { appUserId = recoveredId; source = 'restore'; // Lock identity to prevent accidental changes await despia('setvault://?key=identity_locked&value=true&locked=false'); } } catch (error) { // Purchase history unavailable, continue to fallback } } // Step 3: Fall back to install ID for new users if (!appUserId) { appUserId = installId; source = 'new'; } // Step 4: Persist to Storage Vault try { await despia(`setvault://?key=app_user_id&value=${appUserId}&locked=false`); } catch (error) { // Vault write failed, continue with sync } identityReady = true; // Step 5: Sync to OneSignal despia(`setonesignalplayerid://?user_id=${appUserId}`); // Step 6: Sync to backend database (required for webhooks) try { await fetch('/api/user/register', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ appUserId, deviceId: installId, source, platform: ua.includes('android') ? 'android' : 'ios', timestamp: new Date().toISOString() }) }); databaseSynced = true; } catch (error) { // Queue for retry on next launch const queue = JSON.parse(localStorage.getItem('identity_sync_queue') || '[]'); queue.push({ appUserId, installId, source, queuedAt: Date.now() }); localStorage.setItem('identity_sync_queue', JSON.stringify(queue)); // Allow app to continue; webhook safety net will handle missing users databaseSynced = true; } return { appUserId, installId, source }; } ``` *** ### Launch Paywall Always verify that identity resolution and database synchronization are complete before opening the paywall. ```javascript theme={null} async function launchPaywall(offering = 'default') { // Wait for identity resolution while (!identityReady) { await new Promise(resolve => setTimeout(resolve, 50)); } // Wait for database synchronization while (!databaseSynced) { await new Promise(resolve => setTimeout(resolve, 50)); } // Safe to open paywall despia(`revenuecat://launchPaywall?external_id=${appUserId}&offering=${offering}`); } ``` Example usage in a UI component: ```javascript theme={null} function UpgradeButton({ offering = 'premium' }) { const [loading, setLoading] = useState(false); const handlePress = async () => { setLoading(true); // Wait for identity and sync while (!identityReady || !databaseSynced) { await new Promise(resolve => setTimeout(resolve, 50)); } despia(`revenuecat://launchPaywall?external_id=${appUserId}&offering=${offering}`); setLoading(false); }; return ( ); } ``` *** ### Identity Locking When a user has made purchases, lock their identity to prevent accidental changes that could orphan their purchase history. ```javascript theme={null} // Check if identity is locked on app startup async function checkIdentityLock() { try { const lockData = await despia('readvault://?key=identity_locked', ['identity_locked']); return lockData?.identity_locked === 'true'; } catch (error) { return false; } } // Lock identity after recovering purchases async function lockIdentity() { await despia('setvault://?key=identity_locked&value=true&locked=false'); } // Clear lock on logout async function clearIdentityLock() { await despia('setvault://?key=identity_locked&value=false&locked=false'); } ``` *** ### Check Subscription Status ```javascript theme={null} async function checkSubscriptionStatus() { try { const data = await despia('getpurchasehistory://', ['restoredData']); const purchases = data.restoredData || []; const activeSubscription = purchases.find(p => p.isActive); if (activeSubscription) { return { isSubscribed: true, productId: activeSubscription.productIdentifier, expiresAt: activeSubscription.expirationDate, externalUserId: activeSubscription.externalUserId }; } return { isSubscribed: false }; } catch (error) { console.error('Failed to check subscription status:', error); return { isSubscribed: false, error: error.message }; } } ``` *** ### Restore Purchases Provide a restore purchases button for users who need to recover their subscriptions on a new device. ```javascript theme={null} async function restorePurchases() { try { const data = await despia('getpurchasehistory://', ['restoredData']); const purchases = data.restoredData || []; // Find any purchase with an externalUserId const purchaseWithId = purchases.find(p => p.externalUserId); if (purchaseWithId) { const recoveredId = purchaseWithId.externalUserId; // Update Storage Vault await despia(`setvault://?key=app_user_id&value=${recoveredId}&locked=false`); await despia('setvault://?key=identity_locked&value=true&locked=false'); // Sync to OneSignal despia(`setonesignalplayerid://?user_id=${recoveredId}`); // Update local state appUserId = recoveredId; // Sync to backend await fetch('/api/user/register', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ appUserId: recoveredId, deviceId: installId, source: 'restore_button', timestamp: new Date().toISOString() }) }); return { success: true, appUserId: recoveredId }; } return { success: false, message: 'No purchases found' }; } catch (error) { return { success: false, error: error.message }; } } ``` *** ### User Login ```javascript theme={null} async function handleUserLogin(accountId, credentials) { const response = await fetch('/api/user/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ accountId, currentAppUserId: appUserId, credentials }) }); if (!response.ok) { throw new Error('Login failed'); } const { appUserId: returnedId, action } = await response.json(); // Update Storage Vault await despia(`setvault://?key=app_user_id&value=${returnedId}&locked=false`); // Sync to OneSignal despia(`setonesignalplayerid://?user_id=${returnedId}`); // Update local state appUserId = returnedId; return { appUserId: returnedId, action }; } ``` *** ### User Logout ```javascript theme={null} async function handleUserLogout() { // Generate a unique anonymous identifier const newAnonymousId = `${despia.uuid}-${Date.now()}`; // Clear identity lock await despia('setvault://?key=identity_locked&value=false&locked=false'); // Write new identity to vault await despia(`setvault://?key=app_user_id&value=${newAnonymousId}&locked=false`); // Sync to OneSignal despia(`setonesignalplayerid://?user_id=${newAnonymousId}`); // Register new anonymous user with backend await fetch('/api/user/register', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ appUserId: newAnonymousId, deviceId: installId, source: 'logout', timestamp: new Date().toISOString() }) }); // Update local state appUserId = newAnonymousId; return newAnonymousId; } ``` *** ## Backend Implementation ### Webhook Handler RevenueCat sends webhooks for subscription events. Your handler must be idempotent and include a safety net for missing users. ```javascript theme={null} const ONESIGNAL_APP_ID = process.env.ONESIGNAL_APP_ID; const ONESIGNAL_REST_API_KEY = process.env.ONESIGNAL_REST_API_KEY; // POST /api/webhooks/revenuecat async function handleRevenueCatWebhook(req, res) { const { event } = req.body; const eventId = event.id; const eventType = event.type; const appUserId = event.app_user_id; // Idempotency check: skip if already processed const existingEvent = await db.query( 'SELECT 1 FROM processed_webhook_events WHERE event_id = $1', [eventId] ); if (existingEvent.rows.length > 0) { return res.json({ success: true, message: 'Event already processed' }); } // Safety net: create user if missing await db.query(` INSERT INTO app_users (app_user_id, source, created_at, last_seen) VALUES ($1, 'webhook_safety_net', NOW(), NOW()) ON CONFLICT (app_user_id) DO NOTHING `, [appUserId]); // Update subscription status const isActive = ['INITIAL_PURCHASE', 'RENEWAL', 'PRODUCT_CHANGE', 'UNCANCELLATION'] .includes(eventType); await db.query(` INSERT INTO subscriptions ( app_user_id, status, product_id, expires_at, billing_issue, updated_at ) VALUES ($1, $2, $3, $4, $5, NOW()) ON CONFLICT (app_user_id) DO UPDATE SET status = EXCLUDED.status, product_id = EXCLUDED.product_id, expires_at = EXCLUDED.expires_at, billing_issue = EXCLUDED.billing_issue, updated_at = NOW() `, [ appUserId, eventType.toLowerCase(), event.product_id, event.expiration_at_ms ? new Date(event.expiration_at_ms) : null, eventType === 'BILLING_ISSUE' ]); // Send push notification await sendSubscriptionNotification(appUserId, eventType); // Mark event as processed await db.query(` INSERT INTO processed_webhook_events (event_id, event_type, app_user_id, processed_at) VALUES ($1, $2, $3, NOW()) `, [eventId, eventType, appUserId]); return res.json({ success: true }); } async function sendSubscriptionNotification(appUserId, eventType) { const notifications = { 'INITIAL_PURCHASE': { title: 'Welcome to Premium', message: 'Thank you for subscribing. Enjoy all premium features.' }, 'RENEWAL': { title: 'Subscription Renewed', message: 'Your subscription has been renewed successfully.' }, 'CANCELLATION': { title: 'Subscription Cancelled', message: 'Your subscription will remain active until the end of the billing period.' }, 'UNCANCELLATION': { title: 'Subscription Reactivated', message: 'Your subscription has been reactivated.' }, 'BILLING_ISSUE': { title: 'Payment Issue', message: 'There was a problem processing your payment. Please update your payment method.' }, 'EXPIRATION': { title: 'Subscription Expired', message: 'Your premium access has ended. Resubscribe to continue enjoying all features.' } }; const notification = notifications[eventType]; if (!notification) return; await fetch('https://onesignal.com/api/v1/notifications', { method: 'POST', headers: { 'Authorization': `Basic ${ONESIGNAL_REST_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ app_id: ONESIGNAL_APP_ID, include_aliases: { external_id: [appUserId] }, target_channel: 'push', headings: { en: notification.title }, contents: { en: notification.message }, data: { type: eventType, screen: 'subscription' } }) }); } ``` *** ### Webhook Event Types | Event Type | Description | Subscription Active | | :----------------- | :--------------------------------------- | :------------------ | | `INITIAL_PURCHASE` | First subscription purchase | Yes | | `RENEWAL` | Subscription renewed | Yes | | `PRODUCT_CHANGE` | Upgraded or downgraded | Yes | | `CANCELLATION` | User cancelled (active until period end) | Yes | | `UNCANCELLATION` | User re-enabled auto-renew | Yes | | `BILLING_ISSUE` | Payment failed | Yes (grace period) | | `EXPIRATION` | Subscription ended | No | | `TRANSFER` | Transferred to different user | Varies | *** ### User Registration Endpoint ```javascript theme={null} // POST /api/user/register async function handleUserRegistration(req, res) { const { appUserId, deviceId, source, platform, timestamp } = req.body; if (!appUserId || !deviceId) { return res.status(400).json({ error: 'appUserId and deviceId are required' }); } try { await db.query(` INSERT INTO app_users ( app_user_id, device_id, platform, source, created_at, last_seen ) VALUES ($1, $2, $3, $4, $5, $5) ON CONFLICT (app_user_id) DO UPDATE SET device_id = EXCLUDED.device_id, platform = EXCLUDED.platform, last_seen = EXCLUDED.last_seen `, [appUserId, deviceId, platform, source, timestamp || new Date()]); return res.json({ success: true, appUserId }); } catch (error) { console.error('User registration error:', error); return res.status(500).json({ error: 'Registration failed' }); } } ``` *** ### User Login Endpoint Use row-level locking to prevent race conditions when multiple devices authenticate simultaneously. ```javascript theme={null} // POST /api/user/login async function handleUserLogin(req, res) { const client = await db.connect(); try { const { accountId, currentAppUserId, credentials } = req.body; // Validate credentials here // ... await client.query('BEGIN'); // Lock the account row to prevent concurrent modifications const accountResult = await client.query( 'SELECT app_user_id FROM accounts WHERE id = $1 FOR UPDATE', [accountId] ); if (accountResult.rows.length === 0) { await client.query('ROLLBACK'); return res.status(404).json({ error: 'Account not found' }); } const existingAppUserId = accountResult.rows[0].app_user_id; if (existingAppUserId) { // RECOVER: Account already has an app_user_id await client.query('COMMIT'); return res.json({ success: true, action: 'recovered', appUserId: existingAppUserId }); } else { // CLAIM: Assign current app_user_id to account await client.query( 'UPDATE accounts SET app_user_id = $1 WHERE id = $2', [currentAppUserId, accountId] ); await client.query(` UPDATE app_users SET account_id = $1, is_anonymous = false WHERE app_user_id = $2 `, [accountId, currentAppUserId]); await client.query('COMMIT'); return res.json({ success: true, action: 'claimed', appUserId: currentAppUserId }); } } catch (error) { await client.query('ROLLBACK'); console.error('Login error:', error); return res.status(500).json({ error: 'Login failed' }); } finally { client.release(); } } ``` *** ## Database Schema ```sql theme={null} CREATE TABLE app_users ( id SERIAL PRIMARY KEY, app_user_id VARCHAR(255) NOT NULL UNIQUE, device_id VARCHAR(255), platform VARCHAR(20), source VARCHAR(50), is_anonymous BOOLEAN DEFAULT true, account_id VARCHAR(255), created_at TIMESTAMP DEFAULT NOW(), last_seen TIMESTAMP NOT NULL ); CREATE INDEX idx_app_users_app_user_id ON app_users(app_user_id); CREATE INDEX idx_app_users_account_id ON app_users(account_id); CREATE TABLE subscriptions ( id SERIAL PRIMARY KEY, app_user_id VARCHAR(255) NOT NULL UNIQUE, status VARCHAR(50), product_id VARCHAR(255), expires_at TIMESTAMP, billing_issue BOOLEAN DEFAULT false, updated_at TIMESTAMP DEFAULT NOW(), created_at TIMESTAMP DEFAULT NOW() ); CREATE INDEX idx_subscriptions_app_user_id ON subscriptions(app_user_id); CREATE INDEX idx_subscriptions_status ON subscriptions(status); CREATE INDEX idx_subscriptions_expires_at ON subscriptions(expires_at); CREATE TABLE processed_webhook_events ( event_id VARCHAR(255) PRIMARY KEY, event_type VARCHAR(100) NOT NULL, app_user_id VARCHAR(255) NOT NULL, processed_at TIMESTAMP DEFAULT NOW() ); CREATE INDEX idx_processed_events_app_user_id ON processed_webhook_events(app_user_id); -- Add app_user_id column to existing accounts table ALTER TABLE accounts ADD COLUMN app_user_id VARCHAR(255) UNIQUE; CREATE INDEX idx_accounts_app_user_id ON accounts(app_user_id); ``` *** ## Debugging Use this function to inspect the current identity state: ```javascript theme={null} async function debugIdentityState() { console.log('Identity State:'); console.log(' appUserId:', appUserId); console.log(' installId:', installId); console.log(' identityReady:', identityReady); console.log(' databaseSynced:', databaseSynced); // Check vault try { const vaultId = await despia('readvault://?key=app_user_id', ['app_user_id']); const locked = await despia('readvault://?key=identity_locked', ['identity_locked']); console.log('Vault:'); console.log(' app_user_id:', vaultId?.app_user_id); console.log(' identity_locked:', locked?.identity_locked); } catch (error) { console.log('Vault read error:', error); } // Check purchases try { const data = await despia('getpurchasehistory://', ['restoredData']); console.log('Purchases:', data.restoredData); } catch (error) { console.log('Purchase history error:', error); } } ``` *** ## Common Issues | Issue | Cause | Solution | | :------------------------------- | :----------------------------------------- | :-------------------------------- | | Webhook cannot find user | Database sync failed before purchase | Implement webhook safety net | | Wrong user receives notification | Identity changed between sync and purchase | Gate paywall on database sync | | Lost purchases on reinstall | Vault not synced, restore not attempted | Always attempt restore on startup | | Duplicate notifications | Webhook processed multiple times | Use idempotency table | *** ## Protocol Reference | Protocol | Purpose | When to Call | | :---------------------------------------------------- | :---------------------- | :-------------------------------- | | `revenuecat://launchPaywall?external_id=X&offering=Y` | Open paywall | After identity and sync complete | | `getpurchasehistory://` | Get purchase history | Identity recovery, restore button | | `readvault://?key=app_user_id` | Read from Storage Vault | App startup | | `setvault://?key=X&value=Y&locked=Z` | Write to Storage Vault | After identity resolution | | `setonesignalplayerid://?user_id=X` | Set OneSignal ID | Every app launch, login, logout | *** ## Related Documentation * [RevenueCat Webhook Template](https://setup.despia.com/best-practices/backend/revenuecat/webhooks) * [Storage Vault](https://setup.despia.com/native-features/storage-vault) # Webhooks Source: https://setup.despia.com/best-practices/backend/revenuecat/webhooks Complete implementation guide for processing RevenueCat webhooks with authorization validation, event type handling, and entitlement management. ## Webhook Flow Diagram ```mermaid theme={null} flowchart TD Start([Webhook Received]) --> ValidateAuth{Validate
Authorization
Header?} ValidateAuth -->|Invalid| Return401[Return 401
Unauthorized] ValidateAuth -->|Valid| ParseBody[Parse JSON Body] ParseBody --> GetUserID[Extract app_user_id
from event] GetUserID --> GetEntitlements[Extract Active
Entitlements] GetEntitlements --> CheckEventType{Check
Event Type} CheckEventType -->|INITIAL_PURCHASE| InitialPurchase[Process Initial Purchase
- Grant access
- Update user status
- Send welcome email] CheckEventType -->|RENEWAL| Renewal[Process Renewal
- Extend access
- Update billing date
- Log transaction] CheckEventType -->|CANCELLATION| Cancellation[Process Cancellation
- Schedule access removal
- Send survey email
- Update churn metrics] CheckEventType -->|UNCANCELLATION| Uncancellation[Process Uncancellation
- Restore full access
- Update status
- Send confirmation] CheckEventType -->|BILLING_ISSUE| BillingIssue[Process Billing Issue
- Flag account
- Send payment reminder
- Set grace period] CheckEventType -->|EXPIRATION| Expiration[Process Expiration
- Remove access
- Archive user data
- Send win-back email] CheckEventType -->|REFUND| Refund[Process Refund
- Revoke access immediately
- Log refund
- Update analytics] CheckEventType -->|REFUND_REVERSED| RefundReversed[Process Refund Reversal
- Restore access
- Update records
- Notify user] CheckEventType -->|PRODUCT_CHANGE| ProductChange[Process Product Change
- Update tier/features
- Adjust limits
- Log upgrade/downgrade] CheckEventType -->|SUBSCRIPTION_PAUSED| Paused[Process Pause
- Temporarily suspend
- Set resume date
- Update UI access] CheckEventType -->|SUBSCRIPTION_EXTENDED| Extended[Process Extension
- Update expiry date
- Log extension
- Send confirmation] CheckEventType -->|TRIAL_STARTED| TrialStart[Process Trial Start
- Grant trial access
- Set trial end date
- Send onboarding] CheckEventType -->|TRIAL_CANCELLED| TrialCancel[Process Trial Cancel
- Remove trial access
- Send feedback survey
- Update metrics] CheckEventType -->|TRANSFER| Transfer[Process Transfer
- Move subscription
- Update ownership
- Sync across accounts] CheckEventType -->|NON_RENEWING_PURCHASE| NonRenewing[Process Non-Renewing
- Grant time-limited access
- Set expiration
- No auto-renewal] CheckEventType -->|INVOICE_ISSUANCE| Invoice[Process Invoice
- Store invoice data
- Send to accounting
- Update billing] CheckEventType -->|TEMPORARY_ENTITLEMENT| TempEntitlement[Process Temp Entitlement
- Grant temporary access
- Set auto-expiry
- Log store issue] CheckEventType -->|VIRTUAL_CURRENCY| VirtualCurrency[Process Virtual Currency
- Update balance
- Log transaction
- Sync wallet] CheckEventType -->|EXPERIMENT_ENROLLMENT| Experiment[Process Experiment
- Assign variant
- Track enrollment
- Update analytics] CheckEventType -->|Unknown Event| UnknownEvent[Log Unknown Event
- Store for review
- Alert team
- Continue gracefully] InitialPurchase --> SyncDatabase[Sync to Database] Renewal --> SyncDatabase Cancellation --> SyncDatabase Uncancellation --> SyncDatabase BillingIssue --> SyncDatabase Expiration --> SyncDatabase Refund --> SyncDatabase RefundReversed --> SyncDatabase ProductChange --> SyncDatabase Paused --> SyncDatabase Extended --> SyncDatabase TrialStart --> SyncDatabase TrialCancel --> SyncDatabase Transfer --> SyncDatabase NonRenewing --> SyncDatabase Invoice --> SyncDatabase TempEntitlement --> SyncDatabase VirtualCurrency --> SyncDatabase Experiment --> SyncDatabase UnknownEvent --> SyncDatabase SyncDatabase --> OptionalFetch{Need Full
Customer Data?} OptionalFetch -->|Yes| FetchAPI[Call GET /subscribers
API for complete data] OptionalFetch -->|No| Return200 FetchAPI --> Return200[Return 200 OK] Return401 --> End([End]) Return200 --> End style Start fill:#e1f5e1 style Return200 fill:#e1f5e1 style Return401 fill:#ffe1e1 style End fill:#e1e1e1 style ValidateAuth fill:#fff4e1 style CheckEventType fill:#e1f0ff ``` *** ## JavaScript Implementation ### Complete Webhook Handler ```javascript theme={null} // Environment configuration const WEBHOOK_SECRET = process.env.REVENUECAT_WEBHOOK_SECRET || 'MYSECRET'; const REVENUECAT_API_KEY = process.env.REVENUECAT_API_KEY; /** * Main webhook handler * POST /webhooks/revenuecat */ async function handleRevenueCatWebhook(req, res) { try { // Step 1: Validate Authorization Header if (!validateAuthorization(req)) { console.warn('Unauthorized webhook attempt'); return res.status(401).json({ error: 'Unauthorized' }); } // Step 2: Parse webhook body const event = req.body?.event; if (!event) { console.error('Invalid webhook body - missing event'); return res.status(400).json({ error: 'Invalid webhook body' }); } // Step 3: Extract key information const eventType = event.type; const appUserId = event.app_user_id; const environment = event.environment; // PRODUCTION or SANDBOX const eventId = event.id; console.log(`Processing webhook: ${eventType} for user ${appUserId} (${environment})`); // Step 4: Check for duplicate event (idempotency) const isDuplicate = await checkDuplicateEvent(eventId); if (isDuplicate) { console.log(`Duplicate event ${eventId} - already processed`); return res.status(200).json({ message: 'Event already processed' }); } // Step 5: Extract entitlements and subscriber info const activeEntitlements = extractEntitlementsFromEvent(event); const subscriberAttributes = event.subscriber_attributes || {}; const externalUserId = subscriberAttributes.$email?.value || subscriberAttributes.$displayName?.value || appUserId; // Step 6: Process event based on type await processWebhookEvent({ eventType, appUserId, externalUserId, environment, activeEntitlements, subscriberAttributes, event }); // Step 7: Sync entitlements to database await syncEntitlementsToDatabase(appUserId, activeEntitlements, event); // Step 8: Mark event as processed await markEventAsProcessed(eventId); // Step 9: Return success return res.status(200).json({ message: 'Webhook processed successfully' }); } catch (error) { console.error('Webhook processing error:', error); // Return 200 to prevent retries for our internal errors // Return 500 only if we want RevenueCat to retry return res.status(200).json({ message: 'Webhook received but processing failed', error: error.message }); } } /** * Validate Authorization Header * RevenueCat sends: Authorization: Bearer MYSECRET * We validate against configured secret */ function validateAuthorization(req) { const authHeader = req.headers.authorization; if (!authHeader) { return false; } // Strip "Bearer " prefix if present const token = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : authHeader; return token === WEBHOOK_SECRET; } /** * Process webhook event based on type */ async function processWebhookEvent({ eventType, appUserId, externalUserId, environment, activeEntitlements, event }) { // Extract critical entitlement data from webhook const entitlementData = extractEntitlementData(event); // Always sync entitlements to database for ALL events // This ensures database stays in sync with RevenueCat await syncEntitlementsToDatabase(appUserId, entitlementData, event); // Get detailed subscriber data if needed for complex processing // const subscriberData = await fetchSubscriberData(appUserId); switch (eventType) { // ========================================== // PURCHASE EVENTS // ========================================== case 'INITIAL_PURCHASE': console.log(`Initial purchase for ${appUserId}`); // TODO: Implement your logic // - Grant access to premium features // - Update user status in database // - Send welcome email // - Track conversion in analytics // - Update subscription tier await handleInitialPurchase({ appUserId, externalUserId, activeEntitlements, productId: event.product_id, price: event.price, currency: event.currency, purchaseDate: event.purchased_at_ms, expirationDate: event.expiration_at_ms, store: event.store, isTrialConversion: event.is_trial_conversion }); break; case 'RENEWAL': console.log(`Renewal for ${appUserId}`); // TODO: Implement your logic // - Extend subscription access // - Update next billing date // - Log successful payment // - Update LTV metrics await handleRenewal({ appUserId, externalUserId, activeEntitlements, expirationDate: event.expiration_at_ms, price: event.price, currency: event.currency }); break; case 'NON_RENEWING_PURCHASE': console.log(`Non-renewing purchase for ${appUserId}`); // TODO: Implement your logic // - Grant time-limited access // - Set expiration date // - No auto-renewal expected await handleNonRenewingPurchase({ appUserId, externalUserId, activeEntitlements, productId: event.product_id, expirationDate: event.expiration_at_ms }); break; // ========================================== // CANCELLATION EVENTS // ========================================== case 'CANCELLATION': console.log(`Cancellation for ${appUserId}`); // TODO: Implement your logic // - Schedule access removal at period end // - Send feedback survey // - Offer win-back discount // - Update churn analytics // - Flag account as "cancelled" await handleCancellation({ appUserId, externalUserId, activeEntitlements, expirationDate: event.expiration_at_ms, cancellationReason: event.cancellation_reason, autoResumeDate: event.auto_resume_at_ms }); break; case 'UNCANCELLATION': console.log(`Uncancellation for ${appUserId}`); // TODO: Implement your logic // - Restore subscription to active state // - Remove cancellation flag // - Send confirmation email await handleUncancellation({ appUserId, externalUserId, activeEntitlements, expirationDate: event.expiration_at_ms }); break; // ========================================== // TRIAL EVENTS // ========================================== case 'TRIAL_STARTED': console.log(`Trial started for ${appUserId}`); // TODO: Implement your logic // - Grant trial access to features // - Set trial end date // - Send onboarding emails // - Track trial starts await handleTrialStarted({ appUserId, externalUserId, activeEntitlements, expirationDate: event.expiration_at_ms, productId: event.product_id }); break; case 'TRIAL_CANCELLED': console.log(`Trial cancelled for ${appUserId}`); // TODO: Implement your logic // - Remove trial access // - Send feedback survey // - Update trial conversion metrics await handleTrialCancelled({ appUserId, externalUserId, cancellationReason: event.cancellation_reason }); break; // ========================================== // BILLING EVENTS // ========================================== case 'BILLING_ISSUE': console.log(`Billing issue for ${appUserId}`); // TODO: Implement your logic // - Flag account with payment problem // - Send payment update reminder // - Start grace period // - Alert user via email/push await handleBillingIssue({ appUserId, externalUserId, activeEntitlements, gracePeriodExpiresAt: event.grace_period_expires_at_ms }); break; case 'EXPIRATION': console.log(`Subscription expired for ${appUserId}`); // TODO: Implement your logic // - Remove premium access // - Archive user data // - Send win-back campaign // - Update user to free tier await handleExpiration({ appUserId, externalUserId, expirationReason: event.expiration_reason, expirationDate: event.expiration_at_ms }); break; // ========================================== // REFUND EVENTS // ========================================== case 'REFUND': console.log(`Refund issued for ${appUserId}`); // TODO: Implement your logic // - Revoke access immediately // - Log refund for accounting // - Update analytics // - Flag potential abuse await handleRefund({ appUserId, externalUserId, productId: event.product_id, price: event.price, currency: event.currency }); break; case 'REFUND_REVERSED': console.log(`Refund reversed for ${appUserId}`); // TODO: Implement your logic // - Restore access // - Update accounting records // - Notify user await handleRefundReversed({ appUserId, externalUserId, activeEntitlements }); break; // ========================================== // SUBSCRIPTION CHANGES // ========================================== case 'PRODUCT_CHANGE': console.log(`Product changed for ${appUserId}`); // TODO: Implement your logic // - Update tier/plan // - Adjust feature access // - Update usage limits // - Log upgrade or downgrade await handleProductChange({ appUserId, externalUserId, activeEntitlements, newProductId: event.new_product_id, oldProductId: event.product_id, expirationDate: event.expiration_at_ms }); break; case 'SUBSCRIPTION_PAUSED': console.log(`Subscription paused for ${appUserId}`); // TODO: Implement your logic // - Temporarily suspend access // - Set auto-resume date // - Update UI to show paused state await handleSubscriptionPaused({ appUserId, externalUserId, autoResumeDate: event.auto_resume_at_ms }); break; case 'SUBSCRIPTION_EXTENDED': console.log(`Subscription extended for ${appUserId}`); // TODO: Implement your logic // - Update expiration date // - Log extension reason // - Send confirmation await handleSubscriptionExtended({ appUserId, externalUserId, newExpirationDate: event.expiration_at_ms, extensionReason: 'promotional' // or from event data }); break; // ========================================== // TRANSFER EVENTS // ========================================== case 'TRANSFER': console.log(`Subscription transferred for ${appUserId}`); // TODO: Implement your logic // - Move subscription to new user // - Update ownership records // - Sync across accounts await handleTransfer({ fromUserId: event.transferred_from?.[0], toUserId: appUserId, activeEntitlements }); break; // ========================================== // SPECIAL EVENTS // ========================================== case 'INVOICE_ISSUANCE': console.log(`Invoice issued for ${appUserId}`); // TODO: Implement your logic // - Store invoice data // - Send to accounting system // - Update billing records await handleInvoiceIssuance({ appUserId, externalUserId, invoiceData: event }); break; case 'TEMPORARY_ENTITLEMENT_GRANT': console.log(`Temporary entitlement granted for ${appUserId}`); // TODO: Implement your logic // - Grant temporary access (store issue) // - Set auto-expiry // - Log for monitoring await handleTemporaryEntitlement({ appUserId, externalUserId, activeEntitlements, expirationDate: event.expiration_at_ms }); break; case 'VIRTUAL_CURRENCY_TRANSACTION': console.log(`Virtual currency transaction for ${appUserId}`); // TODO: Implement your logic // - Update virtual currency balance // - Log transaction // - Sync wallet state await handleVirtualCurrency({ appUserId, externalUserId, amount: event.amount, currency: event.currency, transactionType: event.transaction_type }); break; case 'EXPERIMENT_ENROLLMENT': console.log(`Experiment enrollment for ${appUserId}`); // TODO: Implement your logic // - Assign user to variant // - Track enrollment // - Update analytics await handleExperimentEnrollment({ appUserId, externalUserId, experimentId: event.experiment_id, variantId: event.variant_id }); break; // ========================================== // UNKNOWN EVENTS (Future-proofing) // ========================================== default: console.warn(`Unknown event type: ${eventType}`); // TODO: Implement your logic // - Log for review // - Alert team // - Store for manual processing await handleUnknownEvent({ eventType, appUserId, externalUserId, event }); break; } } /** * Fetch complete subscriber data from RevenueCat API * Recommended after processing webhook for consistent data format */ async function fetchSubscriberData(appUserId) { try { const response = await fetch( `https://api.revenuecat.com/v1/subscribers/${appUserId}`, { headers: { 'Authorization': `Bearer ${REVENUECAT_API_KEY}`, 'Content-Type': 'application/json', 'X-Platform': 'stripe' // Optional: helps with analytics } } ); if (!response.ok) { throw new Error(`RevenueCat API error: ${response.status}`); } const data = await response.json(); return data.subscriber; } catch (error) { console.error('Error fetching subscriber data:', error); return null; } } /** * Fetch customer data from RevenueCat API V2 (recommended for real-time checks) * Use this as authoritative source of truth when validating subscription status */ async function fetchCustomerDataV2(customerId, projectId) { try { const response = await fetch( `https://api.revenuecat.com/v2/projects/${projectId}/customers/${customerId}`, { headers: { 'Authorization': `Bearer ${REVENUECAT_API_KEY}`, 'Content-Type': 'application/json' } } ); if (!response.ok) { if (response.status === 404) { console.warn(`Customer ${customerId} not found in RevenueCat`); return null; } throw new Error(`RevenueCat V2 API error: ${response.status}`); } const data = await response.json(); return data; } catch (error) { console.error('Error fetching customer data from V2 API:', error); return null; } } /** * Self-healing subscription status check * 1. Check database first (fast) * 2. If discrepancy detected, verify with RevenueCat V2 API * 3. Sync database if mismatch found */ async function verifyAndSyncSubscriptionStatus(appUserId, projectId) { try { // Step 1: Get current database status const dbStatus = await getSubscriptionStatusFromDB(appUserId); // Step 2: Get authoritative status from RevenueCat V2 const rcData = await fetchCustomerDataV2(appUserId, projectId); if (!rcData) { console.warn(`Customer ${appUserId} not found in RevenueCat`); return dbStatus; // Trust database if customer doesn't exist } // Step 3: Check for active entitlements // V2 API returns expires_at as milliseconds timestamp const hasActiveEntitlements = rcData.active_entitlements?.items?.length > 0; const rcIsActive = hasActiveEntitlements && rcData.active_entitlements.items.some(ent => { return ent.expires_at > Date.now(); }); // Step 4: Detect discrepancy if (dbStatus?.is_active !== rcIsActive) { console.warn(`Subscription status mismatch for ${appUserId}:`, { database: dbStatus?.is_active ? 'active' : 'inactive', revenuecat: rcIsActive ? 'active' : 'inactive' }); // Step 5: Sync database with RevenueCat (source of truth) await syncDatabaseWithRevenueCat(appUserId, rcData); console.log(`Synced ${appUserId} subscription status from RevenueCat`); } // Extract customer email and display name from attributes const email = rcData.attributes?.items?.find(attr => attr.name === '$email')?.value || null; const displayName = rcData.attributes?.items?.find(attr => attr.name === '$displayName')?.value || null; return { appUserId, isActive: rcIsActive, entitlements: rcData.active_entitlements?.items || [], email, displayName, lastSeen: rcData.last_seen_at, experiment: rcData.experiment, syncedAt: new Date() }; } catch (error) { console.error('Error in verifyAndSyncSubscriptionStatus:', error); // Fallback to database status on error const dbStatus = await getSubscriptionStatusFromDB(appUserId); return dbStatus; } } /** * Get subscription status from database */ async function getSubscriptionStatusFromDB(appUserId) { // TODO: Implement with your database // Example: // const result = await db.query( // 'SELECT * FROM user_subscriptions WHERE app_user_id = $1', // [appUserId] // ); // return result.rows[0]; return null; } /** * Sync database with RevenueCat data */ async function syncDatabaseWithRevenueCat(appUserId, rcData) { // TODO: Implement with your database // Update user_subscriptions table with V2 API data const hasActiveEntitlements = rcData.active_entitlements?.items?.length > 0; // Extract email and display name from attributes const email = rcData.attributes?.items?.find(attr => attr.name === '$email')?.value || null; const displayName = rcData.attributes?.items?.find(attr => attr.name === '$displayName')?.value || null; // Get latest expiration from active entitlements const latestExpiration = hasActiveEntitlements ? Math.max(...rcData.active_entitlements.items.map(ent => ent.expires_at)) : null; // Convert entitlements to database format const entitlementsForDB = {}; if (hasActiveEntitlements) { rcData.active_entitlements.items.forEach(ent => { entitlementsForDB[ent.entitlement_id] = { entitlement_id: ent.entitlement_id, expires_at: ent.expires_at }; }); } // Example database sync: // await db.query(` // UPDATE user_subscriptions // SET // is_active = $1, // entitlements = $2, // expires_at = $3, // email = $4, // external_user_id = $5, // last_seen_at = $6, // last_revenuecat_sync_at = NOW() // WHERE app_user_id = $7 // `, [ // hasActiveEntitlements, // JSON.stringify(entitlementsForDB), // latestExpiration ? new Date(latestExpiration) : null, // email, // displayName || email, // rcData.last_seen_at ? new Date(rcData.last_seen_at) : null, // appUserId // ]); console.log(`Database synced for ${appUserId}`, { hasActive: hasActiveEntitlements, entitlementCount: Object.keys(entitlementsForDB).length, email, latestExpiration: latestExpiration ? new Date(latestExpiration).toISOString() : null }); } /** * Extract complete entitlement data from webhook event * Based on actual RevenueCat webhook structure */ function extractEntitlementData(event) { return { // Entitlements (the key field!) entitlements: event.entitlements || {}, // User identification appUserId: event.app_user_id, originalAppUserId: event.original_app_user_id, aliases: event.aliases || [], // Subscriber attributes (email, displayName, custom attributes) subscriberAttributes: event.subscriber_attributes || {}, // Product information productId: event.product_id || event.new_product_id, oldProductId: event.product_id, // For product changes newProductId: event.new_product_id, // For product changes // Subscription dates purchasedAtMs: event.purchased_at_ms, expirationAtMs: event.expiration_at_ms, originalPurchaseDateMs: event.original_purchase_date_ms, // Grace period (billing issues) gracePeriodExpiresAtMs: event.grace_period_expires_at_ms, // Trial information isTrialConversion: event.is_trial_conversion, // Cancellation cancellationReason: event.cancellation_reason, autoResumeAtMs: event.auto_resume_at_ms, // Expiration reason expirationReason: event.expiration_reason, // Transfer information transferredFrom: event.transferred_from, transferredTo: event.transferred_to, // Metadata store: event.store, environment: event.environment, periodType: event.period_type, // Pricing price: event.price, priceInPurchasedCurrency: event.price_in_purchased_currency, currency: event.currency, // Event tracking eventId: event.id, eventType: event.type, eventTimestampMs: event.event_timestamp_ms }; } /** * Extract entitlements from webhook event * Handles the nested structure from RevenueCat webhooks * * IMPORTANT: Entitlements structure from RevenueCat: * { * "entitlement_id": { * "expires_date": "2026-01-17T12:00:00Z", * "grace_period_expires_date": null, * "product_identifier": "yearly_pro", * "purchase_date": "2025-01-17T12:00:00Z" * } * } */ function extractEntitlementsFromEvent(event) { // Entitlements are nested under event.entitlements // Structure: { entitlement_id: { expires_date, product_identifier, ... } } const entitlements = event.entitlements || {}; // Convert to array format with expiration checking const activeEntitlements = {}; Object.keys(entitlements).forEach(entitlementId => { const entitlement = entitlements[entitlementId]; // Check if entitlement is active const expiresDate = entitlement.expires_date; const isActive = !expiresDate || new Date(expiresDate) > new Date(); if (isActive) { activeEntitlements[entitlementId] = { entitlement_id: entitlementId, product_id: entitlement.product_identifier, expires_at: expiresDate, purchase_date: entitlement.purchase_date, grace_period_expires_at: entitlement.grace_period_expires_date }; } }); return activeEntitlements; } /** * Sync entitlements to database * Updates user_subscriptions table with current entitlements from webhook * * CRITICAL: This function MUST be called for EVERY webhook event to keep * the database in sync with RevenueCat's source of truth */ async function syncEntitlementsToDatabase(appUserId, entitlementData, event) { try { // Extract entitlements const entitlements = entitlementData.entitlements || event.entitlements || {}; const activeEntitlements = extractEntitlementsFromEvent({ entitlements }); const hasActiveEntitlements = Object.keys(activeEntitlements).length > 0; // Get subscriber attributes const subscriberAttributes = entitlementData.subscriberAttributes || event.subscriber_attributes || {}; const email = subscriberAttributes.$email?.value || null; const displayName = subscriberAttributes.$displayName?.value || null; // Product information const productId = entitlementData.productId || event.product_id || event.new_product_id; // Dates const expiresAt = entitlementData.expirationAtMs ? new Date(entitlementData.expirationAtMs) : (event.expiration_at_ms ? new Date(event.expiration_at_ms) : null); const purchasedAt = entitlementData.purchasedAtMs ? new Date(entitlementData.purchasedAtMs) : (event.purchased_at_ms ? new Date(event.purchased_at_ms) : null); const gracePeriodExpiresAt = entitlementData.gracePeriodExpiresAtMs ? new Date(entitlementData.gracePeriodExpiresAtMs) : (event.grace_period_expires_at_ms ? new Date(event.grace_period_expires_at_ms) : null); // Determine subscription status based on event type let subscriptionStatus = 'expired'; let autoRenew = true; let billingIssue = false; let cancelledAt = null; if (hasActiveEntitlements) { if (event.type === 'TRIAL_STARTED') { subscriptionStatus = 'trial'; } else if (event.type === 'SUBSCRIPTION_PAUSED') { subscriptionStatus = 'paused'; autoRenew = false; } else if (event.type === 'CANCELLATION') { subscriptionStatus = 'cancelled'; autoRenew = false; cancelledAt = new Date(event.event_timestamp_ms || Date.now()); } else if (event.type === 'BILLING_ISSUE') { subscriptionStatus = 'billing_issue'; billingIssue = true; } else { subscriptionStatus = 'active'; } } else { // No active entitlements subscriptionStatus = 'expired'; autoRenew = false; } // Store information const store = entitlementData.store || event.store; const environment = entitlementData.environment || event.environment; console.log(`Syncing entitlements for ${appUserId}:`, { hasActive: hasActiveEntitlements, status: subscriptionStatus, entitlementCount: Object.keys(activeEntitlements).length, entitlements: Object.keys(activeEntitlements), productId, expiresAt, email }); // TODO: Implement database update // This is the CRITICAL sync point - update your database here /* await db.query(` INSERT INTO user_subscriptions ( app_user_id, external_user_id, email, is_active, subscription_status, product_id, entitlements, expires_at, purchased_at, cancelled_at, grace_period_expires_at, auto_renew, billing_issue, store, environment, last_webhook_event_id, last_webhook_event_type, last_updated ) VALUES ( $1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, NOW() ) ON CONFLICT (app_user_id) DO UPDATE SET external_user_id = COALESCE(EXCLUDED.external_user_id, user_subscriptions.external_user_id), email = COALESCE(EXCLUDED.email, user_subscriptions.email), is_active = EXCLUDED.is_active, subscription_status = EXCLUDED.subscription_status, product_id = EXCLUDED.product_id, entitlements = EXCLUDED.entitlements, expires_at = EXCLUDED.expires_at, purchased_at = COALESCE(EXCLUDED.purchased_at, user_subscriptions.purchased_at), cancelled_at = EXCLUDED.cancelled_at, grace_period_expires_at = EXCLUDED.grace_period_expires_at, auto_renew = EXCLUDED.auto_renew, billing_issue = EXCLUDED.billing_issue, store = EXCLUDED.store, environment = EXCLUDED.environment, last_webhook_event_id = EXCLUDED.last_webhook_event_id, last_webhook_event_type = EXCLUDED.last_webhook_event_type, last_updated = NOW() `, [ appUserId, displayName || email, email, hasActiveEntitlements, subscriptionStatus, productId, JSON.stringify(activeEntitlements), expiresAt, purchasedAt, cancelledAt, gracePeriodExpiresAt, autoRenew, billingIssue, store, environment, event.id, event.type ]); */ // Also sync to normalized entitlements table await syncEntitlementsToNormalizedTable(appUserId, activeEntitlements, event); } catch (error) { console.error('Error syncing entitlements to database:', error); throw error; } } /** * Check for duplicate event (idempotency) */ async function checkDuplicateEvent(eventId) { // TODO: Implement with your database // Check if eventId exists in processed_events table // Return true if exists, false otherwise // Example: // const exists = await db.query( // 'SELECT 1 FROM processed_webhook_events WHERE event_id = $1', // [eventId] // ); // return exists.rows.length > 0; return false; } /** * Mark event as processed */ async function markEventAsProcessed(eventId) { // TODO: Implement with your database // Insert eventId into processed_events table // Example: // await db.query( // 'INSERT INTO processed_webhook_events (event_id, processed_at) VALUES ($1, NOW())', // [eventId] // ); } // ========================================== // EVENT HANDLER TEMPLATES // Implement these functions with your business logic // ========================================== async function handleInitialPurchase(data) { // TODO: Implement // - Update user subscription status in database // - Grant access to premium features // - Send welcome email // - Track conversion event in analytics console.log('Initial purchase handler - implement your logic here', data); } async function handleRenewal(data) { // TODO: Implement // - Update subscription end date // - Log successful payment // - Update customer LTV console.log('Renewal handler - implement your logic here', data); } async function handleNonRenewingPurchase(data) { // TODO: Implement console.log('Non-renewing purchase handler - implement your logic here', data); } async function handleCancellation(data) { // TODO: Implement // - Update subscription status to "cancelled" // - Schedule access removal for expiration date // - Send feedback survey // - Track churn reason console.log('Cancellation handler - implement your logic here', data); } async function handleUncancellation(data) { // TODO: Implement console.log('Uncancellation handler - implement your logic here', data); } async function handleTrialStarted(data) { // TODO: Implement console.log('Trial started handler - implement your logic here', data); } async function handleTrialCancelled(data) { // TODO: Implement console.log('Trial cancelled handler - implement your logic here', data); } async function handleBillingIssue(data) { // TODO: Implement // - Flag account // - Send payment reminder email // - Start grace period console.log('Billing issue handler - implement your logic here', data); } async function handleExpiration(data) { // TODO: Implement // - Remove premium access // - Downgrade to free tier // - Send win-back email console.log('Expiration handler - implement your logic here', data); } async function handleRefund(data) { // TODO: Implement // - Immediately revoke access // - Log refund // - Update accounting console.log('Refund handler - implement your logic here', data); } async function handleRefundReversed(data) { // TODO: Implement console.log('Refund reversed handler - implement your logic here', data); } async function handleProductChange(data) { // TODO: Implement // - Update subscription tier // - Adjust feature access // - Log upgrade/downgrade console.log('Product change handler - implement your logic here', data); } async function handleSubscriptionPaused(data) { // TODO: Implement console.log('Subscription paused handler - implement your logic here', data); } async function handleSubscriptionExtended(data) { // TODO: Implement console.log('Subscription extended handler - implement your logic here', data); } async function handleTransfer(data) { // TODO: Implement console.log('Transfer handler - implement your logic here', data); } async function handleInvoiceIssuance(data) { // TODO: Implement console.log('Invoice issuance handler - implement your logic here', data); } async function handleTemporaryEntitlement(data) { // TODO: Implement console.log('Temporary entitlement handler - implement your logic here', data); } async function handleVirtualCurrency(data) { // TODO: Implement console.log('Virtual currency handler - implement your logic here', data); } async function handleExperimentEnrollment(data) { // TODO: Implement console.log('Experiment enrollment handler - implement your logic here', data); } async function handleUnknownEvent(data) { // TODO: Implement // - Log event for manual review // - Alert development team // - Store in database for later processing console.log('Unknown event handler - implement your logic here', data); } // ========================================== // HELPER FUNCTIONS // ========================================== /** * Check if user has active entitlement (V2 API format) * V2 API returns expires_at as milliseconds timestamp */ function hasActiveEntitlementV2(customerData, entitlementId = null) { if (!customerData?.active_entitlements?.items) { return false; } return customerData.active_entitlements.items.some(ent => { // If entitlementId specified, check for specific entitlement if (entitlementId && ent.entitlement_id !== entitlementId) { return false; } // Check if entitlement is still valid // expires_at is in milliseconds timestamp return ent.expires_at > Date.now(); }); } /** * Determine if we should verify status with RevenueCat */ function shouldVerifyWithRevenueCat(cachedStatus) { if (!cachedStatus) { return true; // No cached data, must check } // Always verify if subscription expires soon (within 24 hours) if (cachedStatus.expires_at) { const expiresAt = new Date(cachedStatus.expires_at); const hoursUntilExpiry = (expiresAt - new Date()) / (1000 * 60 * 60); if (hoursUntilExpiry < 24) { return true; // Verify near expiration } } // Verify if billing issue detected if (cachedStatus.billing_issue) { return true; } // Verify if recently cancelled (within 48 hours) if (cachedStatus.cancelled_at) { const cancelledAt = new Date(cachedStatus.cancelled_at); const hoursSinceCancellation = (new Date() - cancelledAt) / (1000 * 60 * 60); if (hoursSinceCancellation < 48) { return true; // Verify recent cancellations } } // Verify if cache is stale (older than 1 hour) if (cachedStatus.last_updated) { const lastUpdated = new Date(cachedStatus.last_updated); const hoursSinceUpdate = (new Date() - lastUpdated) / (1000 * 60 * 60); if (hoursSinceUpdate > 1) { return true; // Cache is stale } } return false; // Use cached data } /** * Check if user has active entitlement */ function hasActiveEntitlement(activeEntitlements, entitlementId) { return activeEntitlements[entitlementId]?.expires_date_ms ? activeEntitlements[entitlementId].expires_date_ms > Date.now() : false; } /** * Get all active entitlement IDs */ function getActiveEntitlementIds(activeEntitlements) { return Object.keys(activeEntitlements).filter(entitlementId => hasActiveEntitlement(activeEntitlements, entitlementId) ); } /** * Get all active entitlement IDs from V2 API customer data */ function getActiveEntitlementIdsV2(customerData) { if (!customerData?.active_entitlements?.items) { return []; } return customerData.active_entitlements.items .filter(ent => ent.expires_at > Date.now()) .map(ent => ent.entitlement_id); } /** * Get customer email from V2 API attributes */ function getCustomerEmailV2(customerData) { if (!customerData?.attributes?.items) { return null; } const emailAttr = customerData.attributes.items.find( attr => attr.name === '$email' ); return emailAttr?.value || null; } /** * Get customer display name from V2 API attributes */ function getCustomerDisplayNameV2(customerData) { if (!customerData?.attributes?.items) { return null; } const nameAttr = customerData.attributes.items.find( attr => attr.name === '$displayName' ); return nameAttr?.value || null; } /** * Get custom attribute from V2 API customer data */ function getCustomerAttributeV2(customerData, attributeName) { if (!customerData?.attributes?.items) { return null; } const attr = customerData.attributes.items.find( a => a.name === attributeName ); return attr?.value || null; } /** * Extract user email from subscriber attributes */ function getUserEmail(subscriberAttributes) { return subscriberAttributes.$email?.value || null; } /** * Extract custom attributes */ function getCustomAttribute(subscriberAttributes, key) { return subscriberAttributes[key]?.value || null; } // ========================================== // EXPRESS.JS EXAMPLE // ========================================== // const express = require('express'); // const app = express(); // // app.use(express.json()); // // app.post('/webhooks/revenuecat', handleRevenueCatWebhook); // // app.listen(3000, () => { // console.log('Webhook server running on port 3000'); // }); // ========================================== // NEXT.JS API ROUTE EXAMPLE // ========================================== // // pages/api/webhooks/revenuecat.js // export default async function handler(req, res) { // if (req.method !== 'POST') { // return res.status(405).json({ error: 'Method not allowed' }); // } // // return handleRevenueCatWebhook(req, res); // } module.exports = { handleRevenueCatWebhook, validateAuthorization, // V1 API fetchSubscriberData, // V2 API fetchCustomerDataV2, verifyAndSyncSubscriptionStatus, getSubscriptionStatusFromDB, syncDatabaseWithRevenueCat, hasActiveEntitlementV2, getActiveEntitlementIdsV2, getCustomerEmailV2, getCustomerDisplayNameV2, getCustomerAttributeV2, shouldVerifyWithRevenueCat, // Entitlement Management extractEntitlementData, extractEntitlementsFromEvent, syncEntitlementsToDatabase, syncEntitlementsToNormalizedTable, getUserEntitlements, userHasEntitlement, // Helper functions (V1/Webhook format) hasActiveEntitlement, getActiveEntitlementIds, getUserEmail, getCustomAttribute }; ``` *** ## Quick Start ### 1. Set Up Webhook in RevenueCat Dashboard 1. Navigate to **Integrations** → **Webhooks** 2. Click **Add new configuration** 3. Set Authorization Header: `Bearer MYSECRET` 4. Enter your webhook URL: `https://yourdomain.com/webhooks/revenuecat` 5. Select environment (Production, Sandbox, or Both) ### 2. Configure Your Server ```dotenv theme={null} // .env file REVENUECAT_WEBHOOK_SECRET=MYSECRET REVENUECAT_API_KEY=your_api_key_here ``` ### 3. Deploy Webhook Endpoint Deploy the handler to your server and ensure it responds within 60 seconds. ### 4. Test with RevenueCat Dashboard Use the "Send Test Event" button in RevenueCat dashboard to verify your implementation. *** ## Database Schema Example ```sql theme={null} -- Track processed events (idempotency) CREATE TABLE processed_webhook_events ( event_id VARCHAR(255) PRIMARY KEY, event_type VARCHAR(100) NOT NULL, app_user_id VARCHAR(255) NOT NULL, environment VARCHAR(20), -- PRODUCTION or SANDBOX processed_at TIMESTAMP DEFAULT NOW(), created_at TIMESTAMP DEFAULT NOW() ); CREATE INDEX idx_app_user_id ON processed_webhook_events(app_user_id); CREATE INDEX idx_processed_at ON processed_webhook_events(processed_at); CREATE INDEX idx_event_type ON processed_webhook_events(event_type); -- User subscriptions table CREATE TABLE user_subscriptions ( id SERIAL PRIMARY KEY, app_user_id VARCHAR(255) UNIQUE NOT NULL, external_user_id VARCHAR(255), email VARCHAR(255), -- Subscription status is_active BOOLEAN DEFAULT false, subscription_status VARCHAR(50), -- active, cancelled, expired, trial, paused product_id VARCHAR(255), entitlements JSONB, -- Store active entitlements as JSON -- Dates expires_at TIMESTAMP, purchased_at TIMESTAMP, cancelled_at TIMESTAMP, trial_end_at TIMESTAMP, -- Flags auto_renew BOOLEAN DEFAULT true, billing_issue BOOLEAN DEFAULT false, -- Metadata store VARCHAR(50), -- app_store, play_store, stripe, etc environment VARCHAR(20), -- PRODUCTION or SANDBOX -- Tracking last_webhook_event_id VARCHAR(255), last_webhook_event_type VARCHAR(100), last_revenuecat_sync_at TIMESTAMP, last_updated TIMESTAMP DEFAULT NOW(), created_at TIMESTAMP DEFAULT NOW() ); CREATE INDEX idx_external_user_id ON user_subscriptions(external_user_id); CREATE INDEX idx_email ON user_subscriptions(email); CREATE INDEX idx_subscription_status ON user_subscriptions(subscription_status); CREATE INDEX idx_is_active ON user_subscriptions(is_active); CREATE INDEX idx_expires_at ON user_subscriptions(expires_at); -- Dedicated entitlements table (normalized approach) CREATE TABLE user_entitlements ( id SERIAL PRIMARY KEY, app_user_id VARCHAR(255) NOT NULL, entitlement_id VARCHAR(255) NOT NULL, product_id VARCHAR(255) NOT NULL, -- Status is_active BOOLEAN DEFAULT true, -- Dates granted_at TIMESTAMP DEFAULT NOW(), expires_at TIMESTAMP, grace_period_expires_at TIMESTAMP, purchase_date TIMESTAMP, -- Metadata store VARCHAR(50), environment VARCHAR(20), -- Tracking created_at TIMESTAMP DEFAULT NOW(), updated_at TIMESTAMP DEFAULT NOW(), UNIQUE(app_user_id, entitlement_id) ); CREATE INDEX idx_entitlement_user ON user_entitlements(app_user_id); CREATE INDEX idx_entitlement_id ON user_entitlements(entitlement_id); CREATE INDEX idx_entitlement_active ON user_entitlements(is_active); CREATE INDEX idx_entitlement_expires ON user_entitlements(expires_at); -- Track RevenueCat API calls for monitoring CREATE TABLE revenuecat_api_calls ( id SERIAL PRIMARY KEY, endpoint VARCHAR(255) NOT NULL, -- v1/subscribers or v2/customers app_user_id VARCHAR(255), status_code INTEGER, response_time_ms INTEGER, error_message TEXT, called_at TIMESTAMP DEFAULT NOW() ); CREATE INDEX idx_api_endpoint ON revenuecat_api_calls(endpoint); CREATE INDEX idx_api_user ON revenuecat_api_calls(app_user_id); CREATE INDEX idx_api_called_at ON revenuecat_api_calls(called_at); -- Webhook delivery failures (for retry logic) CREATE TABLE webhook_failures ( id SERIAL PRIMARY KEY, event_id VARCHAR(255) NOT NULL, event_type VARCHAR(100) NOT NULL, app_user_id VARCHAR(255) NOT NULL, error_message TEXT, retry_count INTEGER DEFAULT 0, next_retry_at TIMESTAMP, created_at TIMESTAMP DEFAULT NOW(), resolved_at TIMESTAMP ); CREATE INDEX idx_webhook_failures_user ON webhook_failures(app_user_id); CREATE INDEX idx_webhook_failures_retry ON webhook_failures(next_retry_at); ``` ### Database Sync Functions ```javascript theme={null} /** * Sync entitlements to normalized table * Recommended for complex entitlement logic */ async function syncEntitlementsToNormalizedTable(appUserId, activeEntitlements, event) { // Get all entitlement IDs from event const entitlementIds = Object.keys(activeEntitlements); // Mark all existing entitlements as inactive first await db.query(` UPDATE user_entitlements SET is_active = false, updated_at = NOW() WHERE app_user_id = $1 `, [appUserId]); // Insert or update each active entitlement for (const entitlementId of entitlementIds) { const ent = activeEntitlements[entitlementId]; await db.query(` INSERT INTO user_entitlements ( app_user_id, entitlement_id, product_id, is_active, expires_at, grace_period_expires_at, purchase_date, store, environment, updated_at ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, NOW()) ON CONFLICT (app_user_id, entitlement_id) DO UPDATE SET product_id = EXCLUDED.product_id, is_active = EXCLUDED.is_active, expires_at = EXCLUDED.expires_at, grace_period_expires_at = EXCLUDED.grace_period_expires_at, purchase_date = EXCLUDED.purchase_date, store = EXCLUDED.store, environment = EXCLUDED.environment, updated_at = NOW() `, [ appUserId, entitlementId, ent.product_id, true, ent.expires_at ? new Date(ent.expires_at) : null, ent.grace_period_expires_at ? new Date(ent.grace_period_expires_at) : null, ent.purchase_date ? new Date(ent.purchase_date) : null, event.store, event.environment ]); } } /** * Get user's active entitlements from database */ async function getUserEntitlements(appUserId) { const result = await db.query(` SELECT entitlement_id, product_id, expires_at, grace_period_expires_at, purchase_date, is_active FROM user_entitlements WHERE app_user_id = $1 AND is_active = true AND (expires_at IS NULL OR expires_at > NOW()) ORDER BY purchase_date DESC `, [appUserId]); // Convert to object format const entitlements = {}; result.rows.forEach(row => { entitlements[row.entitlement_id] = { product_id: row.product_id, expires_at: row.expires_at, grace_period_expires_at: row.grace_period_expires_at, purchase_date: row.purchase_date }; }); return entitlements; } /** * Check if user has specific entitlement */ async function userHasEntitlement(appUserId, entitlementId) { const result = await db.query(` SELECT 1 FROM user_entitlements WHERE app_user_id = $1 AND entitlement_id = $2 AND is_active = true AND (expires_at IS NULL OR expires_at > NOW()) LIMIT 1 `, [appUserId, entitlementId]); return result.rows.length > 0; } ``` *** ## Database Schema Example *** ## Environment Variables Create a `.env` file with the following configuration: ``` # RevenueCat Configuration REVENUECAT_API_KEY=your_secret_api_key_here REVENUECAT_PROJECT_ID=your_project_id_here REVENUECAT_WEBHOOK_SECRET=MYSECRET # Database Configuration DATABASE_URL=postgresql://user:password@localhost:5432/dbname # Application Configuration NODE_ENV=production PORT=3000 # Optional: Rate Limiting REVENUECAT_API_RATE_LIMIT=480 REVENUECAT_API_RATE_WINDOW=60000 # Optional: Caching CACHE_TTL_SECONDS=3600 ENABLE_REVENUECAT_CACHE=true # Optional: Monitoring ENABLE_API_CALL_TRACKING=true ENABLE_WEBHOOK_FAILURE_TRACKING=true ``` ### Security Notes **Never commit these values to version control:** ``` # .gitignore .env .env.local .env.*.local ``` **Use environment-specific files:** ``` .env.development .env.staging .env.production ``` **Validate environment variables on startup:** ```javascript theme={null} // config/env.js const requiredEnvVars = [ 'REVENUECAT_API_KEY', 'REVENUECAT_PROJECT_ID', 'REVENUECAT_WEBHOOK_SECRET', 'DATABASE_URL' ]; function validateEnvironment() { const missing = requiredEnvVars.filter(key => !process.env[key]); if (missing.length > 0) { throw new Error( `Missing required environment variables: ${missing.join(', ')}` ); } console.log('Environment variables validated'); } validateEnvironment(); ``` *** ## Database Schema Example *** ## Security Best Practices ### 1. Always Validate Authorization ```javascript theme={null} // Never skip authorization validation if (!validateAuthorization(req)) { return res.status(401).json({ error: 'Unauthorized' }); } ``` ### 2. Respond Quickly ```javascript theme={null} // Respond within 60 seconds // Defer heavy processing to background jobs await queueBackgroundJob('process-webhook', event); return res.status(200).json({ message: 'Accepted' }); ``` ### 3. Handle Duplicates ```javascript theme={null} // Implement idempotency using event.id const isDuplicate = await checkDuplicateEvent(event.id); if (isDuplicate) { return res.status(200).json({ message: 'Already processed' }); } ``` ### 4. Use HTTPS Only Configure your webhook URL with HTTPS. HTTP is not supported. ### 5. Verify Event Structure ```javascript theme={null} // Validate required fields if (!event || !event.type || !event.app_user_id) { return res.status(400).json({ error: 'Invalid event structure' }); } ``` *** ## Testing Guide ### Test with RevenueCat Dashboard 1. Go to **Integrations** → **Webhooks** 2. Click on your webhook configuration 3. Click **Send Test Event** 4. Select event type 5. Verify your endpoint receives and processes the event ### Test with Sandbox Purchases Make test purchases in sandbox environment: ```javascript theme={null} // The environment field will be "SANDBOX" if (event.environment === 'SANDBOX') { console.log('Test purchase - skip production workflows'); } ``` *** ## Common Patterns ### Sync Subscription Status ```javascript theme={null} async function syncSubscriptionStatus(appUserId, event) { const activeEntitlements = event.entitlements || {}; const hasActiveSubscription = Object.keys(activeEntitlements).length > 0; await db.query(` UPDATE user_subscriptions SET subscription_status = $1, entitlements = $2, expires_at = $3, last_updated = NOW() WHERE app_user_id = $4 `, [ hasActiveSubscription ? 'active' : 'expired', JSON.stringify(activeEntitlements), event.expiration_at_ms ? new Date(event.expiration_at_ms) : null, appUserId ]); } ``` ### Send Email Notification ```javascript theme={null} async function sendCancellationEmail(email, data) { // Use your email service await emailService.send({ to: email, template: 'subscription-cancelled', data: { userName: data.externalUserId, expirationDate: new Date(data.expirationDate).toLocaleDateString(), feedbackUrl: 'https://yourapp.com/feedback' } }); } ``` ### Update Analytics ```javascript theme={null} async function trackWebhookEvent(eventType, userId, data) { await analytics.track({ userId, event: `Subscription ${eventType}`, properties: { productId: data.productId, price: data.price, currency: data.currency, environment: data.environment } }); } ``` *** ## Troubleshooting ### Webhooks Not Received * Verify HTTPS endpoint is accessible * Check authorization header matches exactly * Ensure server responds within 60 seconds * Check RevenueCat dashboard for delivery errors ### Duplicate Events * Implement idempotency using `event.id` * Check database for already-processed events * Return 200 OK even for duplicates ### Missing Data * Use `GET /subscribers` API for complete data * Check `event.entitlements` for active subscriptions * Verify `event.subscriber_attributes` for custom data *** ## RevenueCat API: V1 vs V2 RevenueCat provides two API versions for fetching customer data. Understanding when to use each is critical for building a robust subscription system. ### API V1 - Subscribers Endpoint **Endpoint:** ```shellscript theme={null} GET https://api.revenuecat.com/v1/subscribers/{app_user_id} ``` **Use Cases:** * Fetching complete subscriber information after webhook * Getting subscriber attributes and custom metadata * Historical purchase data * Integration aliases (multiple IDs for same customer) **Example Request:** ```shellscript theme={null} curl -X GET "https://api.revenuecat.com/v1/subscribers/user_abc123" \ -H "Authorization: Bearer YOUR_REVENUECAT_API_KEY" \ -H "Content-Type: application/json" ``` **Example Response:** ```json theme={null} { "request_date": "2025-01-17T12:00:00Z", "request_date_ms": 1737115200000, "subscriber": { "original_app_user_id": "user_abc123", "original_application_version": "1.0", "first_seen": "2024-01-01T00:00:00Z", "last_seen": "2025-01-17T10:00:00Z", "management_url": "https://apps.apple.com/account/subscriptions", "original_purchase_date": "2024-01-15T12:00:00Z", "non_subscriptions": {}, "subscriptions": { "yearly_pro": { "auto_resume_date": null, "billing_issues_detected_at": null, "expires_date": "2025-02-15T12:00:00Z", "grace_period_expires_date": null, "is_sandbox": false, "original_purchase_date": "2024-02-15T12:00:00Z", "ownership_type": "PURCHASED", "period_type": "normal", "purchase_date": "2025-01-15T12:00:00Z", "refunded_at": null, "store": "app_store", "unsubscribe_detected_at": null } }, "entitlements": { "pro": { "expires_date": "2025-02-15T12:00:00Z", "grace_period_expires_date": null, "product_identifier": "yearly_pro", "purchase_date": "2025-01-15T12:00:00Z" } }, "subscriber_attributes": { "$email": { "value": "user@example.com", "updated_at_ms": 1737115200000 }, "$displayName": { "value": "John Doe", "updated_at_ms": 1737115200000 } } } } ``` **JavaScript Implementation:** ```javascript theme={null} async function getSubscriberV1(appUserId) { const response = await fetch( `https://api.revenuecat.com/v1/subscribers/${appUserId}`, { headers: { 'Authorization': `Bearer ${REVENUECAT_API_KEY}`, 'Content-Type': 'application/json' } } ); if (!response.ok) { throw new Error(`RevenueCat V1 API error: ${response.status}`); } const data = await response.json(); return data.subscriber; } ``` *** ### API V2 - Customers Endpoint (Recommended for Real-Time Checks) **Endpoint:** ```shellscript theme={null} GET https://api.revenuecat.com/v2/projects/{project_id}/customers/{customer_id} ``` **Use Cases:** * Real-time subscription status verification * Source of truth for active entitlements * Self-healing when webhooks fail or are delayed * Backup validation before granting access **Why V2 is Better for Status Checks:** * Returns active entitlements directly * Cleaner, more focused response structure * Explicitly shows what's currently active * Better for programmatic status checks * Includes customer attributes in paginated format * Provides experiment enrollment data * Tracks customer metadata (last\_seen, platform, country, etc.) **Important V2 API Differences:** * `expires_at` is returned as **milliseconds timestamp** (not ISO date string) * `active_entitlements.items` contains only `entitlement_id` and `expires_at` (no product\_id) * Customer attributes (email, displayName) are in separate `attributes.items` array * No `subscriptions` object - only active entitlements are returned * Responses are paginated (though most apps fit in single page) **Example Request:** ```shellscript theme={null} curl -X GET "https://api.revenuecat.com/v2/projects/abc123/customers/user_abc123" \ -H "Authorization: Bearer YOUR_REVENUECAT_API_KEY" \ -H "Content-Type: application/json" ``` **Example Response:** ```json theme={null} { "object": "customer", "id": "19b8de26-77c1-49f1-aa18-019a391603e2", "project_id": "proj1ab2c3d4", "first_seen_at": 1658399423658, "last_seen_at": 1658399423658, "last_seen_app_version": "1.0.0", "last_seen_country": "US", "last_seen_platform": "android", "last_seen_platform_version": "35", "active_entitlements": { "object": "list", "items": [ { "object": "customer.active_entitlement", "entitlement_id": "pro", "expires_at": 1768651200000 }, { "object": "customer.active_entitlement", "entitlement_id": "premium_features", "expires_at": 1768651200000 } ], "next_page": null, "url": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/active_entitlements" }, "experiment": { "object": "experiment_enrollment", "id": "exp_123", "name": "pricing_test_v2", "variant": "a" }, "attributes": { "object": "list", "items": [ { "object": "customer.attribute", "name": "$email", "value": "user@example.com", "updated_at": 1658399423658 }, { "object": "customer.attribute", "name": "$displayName", "value": "John Doe", "updated_at": 1658399423658 } ], "next_page": null, "url": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/attributes" } } ``` **JavaScript Implementation:** ```javascript theme={null} async function getCustomerV2(customerId, projectId) { const response = await fetch( `https://api.revenuecat.com/v2/projects/${projectId}/customers/${customerId}`, { headers: { 'Authorization': `Bearer ${REVENUECAT_API_KEY}`, 'Content-Type': 'application/json' } } ); if (!response.ok) { if (response.status === 404) { return null; // Customer not found } throw new Error(`RevenueCat V2 API error: ${response.status}`); } return await response.json(); } // Check if customer has active entitlement function hasActiveEntitlementV2(customerData, entitlementId) { if (!customerData?.active_entitlements?.items) { return false; } return customerData.active_entitlements.items.some(ent => { if (entitlementId && ent.entitlement_id !== entitlementId) { return false; } const expiresAt = new Date(ent.expires_at); return expiresAt > new Date(); }); } ``` *** ### Comparison: V1 vs V2 | Feature | V1 (/subscribers) | V2 (/customers) | | :----------------------- | :----------------------------------- | :----------------------------------------- | | **Response Structure** | Detailed, nested | Clean, paginated | | **Active Entitlements** | In `entitlements` object | Explicit `active_entitlements.items` array | | **Timestamp Format** | ISO date strings | Milliseconds (numbers) | | **Customer Attributes** | `subscriber_attributes` object | `attributes.items` array (paginated) | | **Product Information** | Includes product\_id in entitlements | Only entitlement\_id + expires\_at | | **Subscription Details** | Full subscription history | Not included | | **Experiment Data** | Not included | Included in `experiment` object | | **Customer Metadata** | Limited | Rich (last\_seen, platform, country, etc.) | | **Primary Use Case** | Full customer history | Real-time status checks | | **Best For** | After webhook processing | Self-healing validation | | **Rate Limit** | 480 requests/minute | 480 requests/minute | | **Project ID Required** | No | Yes | | **Response Size** | Larger (more metadata) | Smaller (focused data) | *** ### Working with V2 API Responses **Extract active entitlements:** ```javascript theme={null} const rcData = await fetchCustomerDataV2(userId, projectId); // Check if user has any active access const hasAccess = rcData?.active_entitlements?.items?.length > 0 && rcData.active_entitlements.items.some(ent => ent.expires_at > Date.now()); // Get all active entitlement IDs const entitlementIds = rcData?.active_entitlements?.items ?.filter(ent => ent.expires_at > Date.now()) .map(ent => ent.entitlement_id) || []; // Result: ["pro", "premium_features"] // Check specific entitlement const hasPro = rcData?.active_entitlements?.items?.some(ent => ent.entitlement_id === 'pro' && ent.expires_at > Date.now() ); ``` **Extract customer attributes:** ```javascript theme={null} const rcData = await fetchCustomerDataV2(userId, projectId); // Get email const email = rcData?.attributes?.items ?.find(attr => attr.name === '$email') ?.value; // Get display name const displayName = rcData?.attributes?.items ?.find(attr => attr.name === '$displayName') ?.value; // Get custom attribute const customValue = rcData?.attributes?.items ?.find(attr => attr.name === 'my_custom_attribute') ?.value; ``` **Get customer metadata:** ```javascript theme={null} const rcData = await fetchCustomerDataV2(userId, projectId); const metadata = { firstSeen: new Date(rcData.first_seen_at), lastSeen: new Date(rcData.last_seen_at), appVersion: rcData.last_seen_app_version, country: rcData.last_seen_country, platform: rcData.last_seen_platform, // "ios", "android", etc. platformVersion: rcData.last_seen_platform_version }; ``` **Get experiment enrollment:** ```javascript theme={null} const rcData = await fetchCustomerDataV2(userId, projectId); if (rcData.experiment) { console.log('User in experiment:', rcData.experiment.name); console.log('Variant:', rcData.experiment.variant); // "a", "b", "control", etc. } ``` **Complete example:** ```javascript theme={null} async function checkUserAccess(userId, projectId) { const rcData = await fetchCustomerDataV2(userId, projectId); if (!rcData) { return { hasAccess: false, error: 'Customer not found' }; } // Get active entitlements const activeEntitlements = rcData.active_entitlements?.items ?.filter(ent => ent.expires_at > Date.now()) || []; // Get customer info const email = rcData.attributes?.items ?.find(attr => attr.name === '$email')?.value; return { hasAccess: activeEntitlements.length > 0, entitlements: activeEntitlements.map(ent => ent.entitlement_id), email, lastSeen: new Date(rcData.last_seen_at), experiment: rcData.experiment }; } ``` *** ### Self-Healing Pattern Use this pattern to ensure your database stays synchronized with RevenueCat, even if webhooks are missed or delayed. #### The Problem Webhooks can fail due to: * Network issues during delivery * Server downtime when webhook arrives * Processing errors in your handler * Race conditions with concurrent events * Webhook delivery delays (2+ hours for cancellations) #### The Solution: Database + API V2 Backup ```mermaid theme={null} flowchart TD Start([User Request:
Check Subscription Status]) Start --> CheckDB[1. Check Database
subscription_status table
Fast - local query] CheckDB --> IsDefinitive{Is status
definitive?} IsDefinitive -->|YES| ReturnCached[Return cached
status] IsDefinitive -->|NO
expired soon,
billing issue, etc| CallAPI[2. Call RevenueCat V2
GET /v2/customers/id
Authoritative] CallAPI --> Compare[3. Compare results] Compare --> HasDiscrepancy{Discrepancy
detected?} HasDiscrepancy -->|NO| ReturnRC[Return RC
status] HasDiscrepancy -->|YES| SyncDB[4. Sync Database
with RevenueCat
source of truth] SyncDB --> ReturnSynced[5. Return synced
status to user] ReturnCached --> End([End]) ReturnRC --> End ReturnSynced --> End style Start fill:#e1f5e1 style End fill:#e1e1e1 style CheckDB fill:#e1f0ff style CallAPI fill:#fff4e1 style IsDefinitive fill:#ffe1e1 style HasDiscrepancy fill:#ffe1e1 style ReturnCached fill:#e1f5e1 style ReturnRC fill:#e1f5e1 style ReturnSynced fill:#e1f5e1 style Compare fill:#f0f0f0 style SyncDB fill:#fff4e1 ``` #### Implementation ```javascript theme={null} /** * Get subscription status with self-healing * Uses database for speed, RevenueCat V2 API for accuracy */ async function getSubscriptionStatus(userId, projectId) { // Step 1: Check database first (fast) const dbStatus = await db.query( 'SELECT * FROM user_subscriptions WHERE app_user_id = $1', [userId] ); const cachedStatus = dbStatus.rows[0]; // Step 2: Determine if we need to verify with RevenueCat const needsVerification = shouldVerifyWithRevenueCat(cachedStatus); if (!needsVerification) { return { isActive: cachedStatus?.is_active || false, entitlements: cachedStatus?.entitlements || {}, source: 'database' }; } // Step 3: Fetch from RevenueCat V2 (authoritative) const rcData = await getCustomerV2(userId, projectId); if (!rcData) { // Customer doesn't exist in RevenueCat return { isActive: false, entitlements: {}, source: 'revenuecat', error: 'Customer not found' }; } // Step 4: Check for active entitlements const hasActive = hasActiveEntitlementV2(rcData); // Step 5: Detect discrepancy and sync if needed if (cachedStatus && cachedStatus.is_active !== hasActive) { console.warn('Subscription status mismatch detected', { userId, database: cachedStatus.is_active, revenuecat: hasActive }); // Sync database with RevenueCat (source of truth) await syncSubscriptionStatus(userId, rcData); } return { isActive: hasActive, entitlements: rcData.active_entitlements?.items || [], subscriptions: rcData.subscriptions?.items || [], source: 'revenuecat', synced: true }; } /** * Determine if we should verify status with RevenueCat */ function shouldVerifyWithRevenueCat(cachedStatus) { if (!cachedStatus) { return true; // No cached data, must check } // Always verify if subscription expires soon (within 24 hours) if (cachedStatus.expires_at) { const expiresAt = new Date(cachedStatus.expires_at); const hoursUntilExpiry = (expiresAt - new Date()) / (1000 * 60 * 60); if (hoursUntilExpiry < 24) { return true; // Verify near expiration } } // Verify if billing issue detected if (cachedStatus.billing_issue) { return true; } // Verify if recently cancelled (within 48 hours) if (cachedStatus.cancelled_at) { const cancelledAt = new Date(cachedStatus.cancelled_at); const hoursSinceCancellation = (new Date() - cancelledAt) / (1000 * 60 * 60); if (hoursSinceCancellation < 48) { return true; // Verify recent cancellations } } // Verify if cache is stale (older than 1 hour) if (cachedStatus.last_updated) { const lastUpdated = new Date(cachedStatus.last_updated); const hoursSinceUpdate = (new Date() - lastUpdated) / (1000 * 60 * 60); if (hoursSinceUpdate > 1) { return true; // Cache is stale } } return false; // Use cached data } /** * Sync database with RevenueCat data */ async function syncSubscriptionStatus(userId, rcData) { const hasActive = hasActiveEntitlementV2(rcData); const latestSubscription = rcData.subscriptions?.items?.[0]; await db.query(` INSERT INTO user_subscriptions ( app_user_id, is_active, entitlements, expires_at, product_id, store, last_updated ) VALUES ($1, $2, $3, $4, $5, $6, NOW()) ON CONFLICT (app_user_id) DO UPDATE SET is_active = $2, entitlements = $3, expires_at = $4, product_id = $5, store = $6, last_updated = NOW() `, [ userId, hasActive, JSON.stringify(rcData.active_entitlements?.items || []), latestSubscription?.expires_at, latestSubscription?.product_id, latestSubscription?.store ]); console.log(`Synced subscription status for ${userId} from RevenueCat`); } ``` *** ### Rate Limiting Both V1 and V2 APIs share the same rate limit: **Limit:** 480 requests per minute per API key **Best Practices:** 1. **Cache aggressively** - Store results in database 2. **Use webhooks as primary** - API calls as backup only 3. **Implement exponential backoff** on rate limit errors 4. **Monitor API usage** - Set up alerts at 80% capacity ```javascript theme={null} // Rate limit error handling async function callRevenueCatAPI(url, options) { try { const response = await fetch(url, options); if (response.status === 429) { // Rate limited const retryAfter = response.headers.get('Retry-After') || 60; console.warn(`Rate limited. Retry after ${retryAfter}s`); // Wait and retry await new Promise(resolve => setTimeout(resolve, retryAfter * 1000)); return callRevenueCatAPI(url, options); } return response; } catch (error) { console.error('RevenueCat API error:', error); throw error; } } ``` *** ### When to Use Which API | Scenario | Use API V1 | Use API V2 | | :---------------------------- | :---------- | :---------- | | After processing webhook | ✅ Yes | ⚠️ Optional | | Real-time status check | ❌ No | ✅ Yes | | Self-healing validation | ❌ No | ✅ Yes | | Getting subscriber attributes | ✅ Yes | ❌ No | | Checking active entitlements | ⚠️ Possible | ✅ Better | | Historical purchase data | ✅ Yes | ⚠️ Limited | | Building customer profile | ✅ Yes | ❌ No | **General Rule:** Use V2 for status checks, V1 for detailed customer information. *** ## API Endpoint Examples ### Subscription Status Endpoint Create an endpoint that clients can call to check subscription status: ```javascript theme={null} // GET /api/subscription-status async function handleSubscriptionStatus(req, res) { try { const userId = req.user.id; // From authentication middleware const projectId = process.env.REVENUECAT_PROJECT_ID; // Use self-healing pattern const status = await verifyAndSyncSubscriptionStatus(userId, projectId); return res.json({ isActive: status.isActive, entitlements: status.entitlements, subscriptions: status.subscriptions, syncedAt: status.syncedAt }); } catch (error) { console.error('Error checking subscription status:', error); return res.status(500).json({ error: 'Failed to check subscription status' }); } } ``` ### Force Sync Endpoint Create an endpoint to manually trigger sync with RevenueCat: ```javascript theme={null} // POST /api/sync-revenuecat async function handleForceSync(req, res) { try { const userId = req.user.id; const projectId = process.env.REVENUECAT_PROJECT_ID; // Fetch fresh data from RevenueCat V2 const rcData = await fetchCustomerDataV2(userId, projectId); if (!rcData) { return res.status(404).json({ error: 'Customer not found in RevenueCat' }); } // Sync to database await syncDatabaseWithRevenueCat(userId, rcData); return res.json({ message: 'Subscription synced successfully', isActive: hasActiveEntitlementV2(rcData), entitlements: rcData.active_entitlements?.items || [], syncedAt: new Date() }); } catch (error) { console.error('Error syncing with RevenueCat:', error); return res.status(500).json({ error: 'Failed to sync subscription' }); } } ``` ### Check Specific Entitlement ```javascript theme={null} // GET /api/entitlement/:entitlementId async function handleCheckEntitlement(req, res) { try { const userId = req.user.id; const entitlementId = req.params.entitlementId; const projectId = process.env.REVENUECAT_PROJECT_ID; // Check database first const dbStatus = await getSubscriptionStatusFromDB(userId); // If uncertain, verify with RevenueCat if (!dbStatus || shouldVerifyWithRevenueCat(dbStatus)) { const rcData = await fetchCustomerDataV2(userId, projectId); if (rcData) { await syncDatabaseWithRevenueCat(userId, rcData); const hasEntitlement = rcData.active_entitlements?.items?.some(ent => ent.entitlement_id === entitlementId && new Date(ent.expires_at) > new Date() ); return res.json({ hasAccess: hasEntitlement, entitlementId, source: 'revenuecat' }); } } // Use database status const entitlements = dbStatus?.entitlements || {}; const hasAccess = hasActiveEntitlement(entitlements, entitlementId); return res.json({ hasAccess, entitlementId, source: 'database' }); } catch (error) { console.error('Error checking entitlement:', error); return res.status(500).json({ error: 'Failed to check entitlement' }); } } ``` ### Debug Endpoint (Development Only) ```javascript theme={null} // GET /api/debug/subscription/:userId // WARNING: Only enable in development/staging async function handleDebugSubscription(req, res) { if (process.env.NODE_ENV === 'production') { return res.status(403).json({ error: 'Not available in production' }); } try { const userId = req.params.userId; const projectId = process.env.REVENUECAT_PROJECT_ID; // Get data from all sources const [dbStatus, rcV1Data, rcV2Data] = await Promise.all([ getSubscriptionStatusFromDB(userId), fetchSubscriberData(userId), fetchCustomerDataV2(userId, projectId) ]); return res.json({ database: dbStatus, revenueCatV1: rcV1Data, revenueCatV2: rcV2Data, comparison: { dbActive: dbStatus?.is_active, v1Active: rcV1Data?.entitlements ? Object.keys(rcV1Data.entitlements).length > 0 : false, v2Active: rcV2Data?.active_entitlements?.items?.length > 0, match: dbStatus?.is_active === (rcV2Data?.active_entitlements?.items?.length > 0) } }); } catch (error) { console.error('Error in debug endpoint:', error); return res.status(500).json({ error: error.message }); } } ``` ### Express.js Router Example ```javascript theme={null} const express = require('express'); const router = express.Router(); const { authenticate } = require('../middleware/auth'); // Webhook endpoint (no auth required) router.post('/webhooks/revenuecat', handleRevenueCatWebhook); // Protected endpoints (require authentication) router.get('/subscription-status', authenticate, handleSubscriptionStatus); router.post('/sync-revenuecat', authenticate, handleForceSync); router.get('/entitlement/:entitlementId', authenticate, handleCheckEntitlement); // Debug endpoint (development only) if (process.env.NODE_ENV !== 'production') { router.get('/debug/subscription/:userId', handleDebugSubscription); } module.exports = router; ``` ### Next.js API Routes Example ```javascript theme={null} // pages/api/subscription-status.js import { verifyAndSyncSubscriptionStatus } from '@/lib/revenuecat'; import { getServerSession } from 'next-auth'; export default async function handler(req, res) { if (req.method !== 'GET') { return res.status(405).json({ error: 'Method not allowed' }); } const session = await getServerSession(req, res); if (!session) { return res.status(401).json({ error: 'Unauthorized' }); } const status = await verifyAndSyncSubscriptionStatus( session.user.id, process.env.REVENUECAT_PROJECT_ID ); return res.json(status); } ``` ```javascript theme={null} // pages/api/sync-revenuecat.js import { fetchCustomerDataV2, syncDatabaseWithRevenueCat } from '@/lib/revenuecat'; import { getServerSession } from 'next-auth'; export default async function handler(req, res) { if (req.method !== 'POST') { return res.status(405).json({ error: 'Method not allowed' }); } const session = await getServerSession(req, res); if (!session) { return res.status(401).json({ error: 'Unauthorized' }); } const rcData = await fetchCustomerDataV2( session.user.id, process.env.REVENUECAT_PROJECT_ID ); if (!rcData) { return res.status(404).json({ error: 'Customer not found' }); } await syncDatabaseWithRevenueCat(session.user.id, rcData); return res.json({ message: 'Synced successfully', syncedAt: new Date() }); } ``` *** ## Sample Webhook Events ### Understanding Event Structure All RevenueCat webhooks follow this structure: ```json theme={null} { "api_version": "1.0", "event": { "id": "unique_event_id", "type": "INITIAL_PURCHASE", "app_user_id": "user_abc123", "aliases": ["$RCAnonymousID:abc123"], "original_app_user_id": "user_abc123", "product_id": "yearly_pro", "period_type": "normal", "purchased_at_ms": 1737115200000, "expiration_at_ms": 1768651200000, "environment": "PRODUCTION", "store": "app_store", "entitlements": { "pro": { "expires_date": "2026-01-17T12:00:00Z", "product_identifier": "yearly_pro", "purchase_date": "2025-01-17T12:00:00Z" } }, "subscriber_attributes": { "$email": { "value": "user@example.com", "updated_at_ms": 1737115200000 }, "$displayName": { "value": "John Doe", "updated_at_ms": 1737115200000 } }, "event_timestamp_ms": 1737115200000 } } ``` ### Key Fields to Extract | Field | Location | Purpose | Example | | :--------------- | :----------------------------------------- | :----------------- | :------------------- | | **Event ID** | `event.id` | Idempotency | `"unique_event_id"` | | **Event Type** | `event.type` | Determine action | `"INITIAL_PURCHASE"` | | **User ID** | `event.app_user_id` | Identify user | `"user_abc123"` | | **Product ID** | `event.product_id` | What was purchased | `"yearly_pro"` | | **Entitlements** | `event.entitlements` | Active access | `{ "pro": {...} }` | | **Email** | `event.subscriber_attributes.$email.value` | Contact user | `"user@example.com"` | | **Expires At** | `event.expiration_at_ms` | When access ends | `1768651200000` | | **Environment** | `event.environment` | Production/Sandbox | `"PRODUCTION"` | | **Store** | `event.store` | Purchase platform | `"app_store"` | ### Sample: Initial Purchase ```json theme={null} { "api_version": "1.0", "event": { "id": "abc123-def456-ghi789", "type": "INITIAL_PURCHASE", "app_user_id": "user_123", "original_app_user_id": "user_123", "product_id": "yearly_pro", "period_type": "normal", "purchased_at_ms": 1737115200000, "expiration_at_ms": 1768651200000, "environment": "PRODUCTION", "store": "app_store", "entitlements": { "pro": { "expires_date": "2026-01-17T12:00:00Z", "grace_period_expires_date": null, "product_identifier": "yearly_pro", "purchase_date": "2025-01-17T12:00:00Z" } }, "subscriber_attributes": { "$email": { "value": "user@example.com", "updated_at_ms": 1737115200000 } }, "event_timestamp_ms": 1737115200000, "price": 99.99, "currency": "USD", "is_trial_conversion": false, "takehome_percentage": 0.85 } } ``` **Extract:** * User: `event.app_user_id` → `"user_123"` * Email: `event.subscriber_attributes.$email.value` → `"user@example.com"` * Entitlements: `event.entitlements` → `{ "pro": {...} }` * Active: Check if `entitlements.pro.expires_date` > now * Product: `event.product_id` → `"yearly_pro"` ### Sample: Renewal ```json theme={null} { "api_version": "1.0", "event": { "id": "renewal-event-123", "type": "RENEWAL", "app_user_id": "user_123", "product_id": "yearly_pro", "period_type": "normal", "purchased_at_ms": 1768651200000, "expiration_at_ms": 1800187200000, "environment": "PRODUCTION", "store": "app_store", "entitlements": { "pro": { "expires_date": "2027-01-17T12:00:00Z", "product_identifier": "yearly_pro", "purchase_date": "2026-01-17T12:00:00Z" } }, "event_timestamp_ms": 1768651200000, "price": 99.99, "currency": "USD" } } ``` **Action:** Update `expires_at` to new date, keep entitlements active. ### Sample: Cancellation ```json theme={null} { "api_version": "1.0", "event": { "id": "cancel-event-123", "type": "CANCELLATION", "app_user_id": "user_123", "product_id": "yearly_pro", "expiration_at_ms": 1768651200000, "environment": "PRODUCTION", "store": "app_store", "entitlements": { "pro": { "expires_date": "2026-01-17T12:00:00Z", "product_identifier": "yearly_pro", "purchase_date": "2025-01-17T12:00:00Z" } }, "cancellation_reason": "UNSUBSCRIBE", "event_timestamp_ms": 1737202800000 } } ``` **Important:** * Entitlements STILL ACTIVE until `expires_date` * Update status to "cancelled" * Schedule access removal at `expiration_at_ms` ### Sample: Expiration ```json theme={null} { "api_version": "1.0", "event": { "id": "expire-event-123", "type": "EXPIRATION", "app_user_id": "user_123", "product_id": "yearly_pro", "expiration_at_ms": 1768651200000, "environment": "PRODUCTION", "store": "app_store", "entitlements": {}, "expiration_reason": "UNSUBSCRIBE", "event_timestamp_ms": 1768651200000 } } ``` **Action:** Remove all access - `entitlements` is now empty `{}` ### Sample: Billing Issue ```json theme={null} { "api_version": "1.0", "event": { "id": "billing-event-123", "type": "BILLING_ISSUE", "app_user_id": "user_123", "product_id": "yearly_pro", "expiration_at_ms": 1768651200000, "environment": "PRODUCTION", "store": "app_store", "entitlements": { "pro": { "expires_date": "2026-01-17T12:00:00Z", "grace_period_expires_date": "2026-01-24T12:00:00Z", "product_identifier": "yearly_pro", "purchase_date": "2025-01-17T12:00:00Z" } }, "grace_period_expires_at_ms": 1769256000000, "event_timestamp_ms": 1768651200000 } } ``` **Action:** * Entitlements STILL ACTIVE during grace period * Flag account with billing issue * Access expires at `grace_period_expires_date` if not resolved ### Sample: Product Change ```json theme={null} { "api_version": "1.0", "event": { "id": "product-change-123", "type": "PRODUCT_CHANGE", "app_user_id": "user_123", "product_id": "monthly_pro", "new_product_id": "yearly_pro", "expiration_at_ms": 1800187200000, "environment": "PRODUCTION", "store": "app_store", "entitlements": { "pro": { "expires_date": "2027-01-17T12:00:00Z", "product_identifier": "yearly_pro", "purchase_date": "2026-01-17T12:00:00Z" } }, "event_timestamp_ms": 1768651200000 } } ``` **Action:** * Update `product_id` to `new_product_id` * Entitlements remain active * Update expiration date ### Entitlement Extraction Code ```json theme={null} // Extract entitlements from any webhook event function extractEntitlementsFromEvent(event) { const entitlements = event.entitlements || {}; const activeEntitlements = {}; Object.keys(entitlements).forEach(entitlementId => { const ent = entitlements[entitlementId]; // Check if still active const expiresDate = ent.expires_date; const isActive = !expiresDate || new Date(expiresDate) > new Date(); if (isActive) { activeEntitlements[entitlementId] = { entitlement_id: entitlementId, product_id: ent.product_identifier, expires_at: expiresDate, purchase_date: ent.purchase_date, grace_period_expires_at: ent.grace_period_expires_date }; } }); return activeEntitlements; } // Usage in webhook handler const activeEntitlements = extractEntitlementsFromEvent(event.event); const hasAccess = Object.keys(activeEntitlements).length > 0; // Store in database await db.query(` UPDATE user_subscriptions SET entitlements = $1, is_active = $2, last_updated = NOW() WHERE app_user_id = $3 `, [ JSON.stringify(activeEntitlements), hasAccess, event.event.app_user_id ]); ``` ### Common Patterns **Check if user has specific entitlement:** ```javascript theme={null} function hasEntitlement(activeEntitlements, entitlementId) { return activeEntitlements[entitlementId] !== undefined; } const hasPro = hasEntitlement(activeEntitlements, 'pro'); ``` **Check if ANY entitlement is active:** ```javascript theme={null} const hasAnyAccess = Object.keys(activeEntitlements).length > 0; ``` **Get all active entitlement IDs:** ```javascript theme={null} const activeIds = Object.keys(activeEntitlements); // ["pro", "premium_features"] ``` **Get expiration dates:** ```javascript theme={null} const expirationDates = Object.values(activeEntitlements).map(ent => ({ id: ent.entitlement_id, expires: ent.expires_at })); ``` *** ## Entitlement Sync Strategy ### Why Sync is Critical Your database must stay synchronized with RevenueCat to provide accurate access control. Out-of-sync entitlements cause: * Users losing access they paid for (churn) * Users gaining unauthorized access (revenue loss) * Poor user experience * Support tickets ### Three-Layer Sync Architecture ```mermaid theme={null} flowchart TD RC[RevenueCat - Source of Truth
• App Store / Play Store / Stripe
• Handles refunds, renewals, cancellations] RC -->|Webhooks - Primary Sync
INITIAL_PURCHASE
RENEWAL
CANCELLATION
EXPIRATION
etc.| DB DB[Your Database - Cached State] subgraph DB_Tables [" "] T1[user_subscriptions
• is_active
• entitlements JSON
• expires_at
• product_id] T2[user_entitlements
• entitlement_id
• expires_at
• is_active
• product_id] end DB -.-> DB_Tables DB -->|API V2 - Backup Verification
When:
• Webhook missed
• Near expiration
• Billing issues
• User-triggered check| APP APP[Your Application
• Feature gates
• Access control
• UI rendering] style RC fill:#e1f5e1 style DB fill:#fff4e1 style APP fill:#e1f0ff style T1 fill:#f0f0f0 style T2 fill:#f0f0f0 style DB_Tables fill:none,stroke:none ``` ### Sync Flow Per Webhook **Every webhook event follows this flow:** ```javascript theme={null} // 1. Webhook arrives POST /webhooks/revenuecat { "event": { "type": "RENEWAL", "app_user_id": "user_123", "entitlements": { "pro": { "expires_date": "2026-01-17T12:00:00Z", "product_identifier": "yearly_pro", "purchase_date": "2025-01-17T12:00:00Z" } }, ... } } // 2. Extract entitlements const entitlementData = extractEntitlementData(event); // Returns: { // entitlements: { "pro": {...} }, // productId: "yearly_pro", // expirationAtMs: 1768651200000, // ... // } // 3. Sync to database (CRITICAL - happens for EVERY event) await syncEntitlementsToDatabase(appUserId, entitlementData, event); // Updates: // - user_subscriptions.entitlements = { "pro": {...} } // - user_subscriptions.is_active = true // - user_subscriptions.expires_at = "2026-01-17" // - user_entitlements rows // 4. Process event-specific logic switch(event.type) { case 'RENEWAL': // Send thank you email // Update analytics break; ... } // 5. Return 200 OK to RevenueCat ``` ### Handling Missed Webhooks Even with webhooks, you need backup verification: ```javascript theme={null} async function getUserAccess(userId) { // 1. Check database (fast) const dbStatus = await getUserEntitlements(userId); // 2. Determine if verification needed const needsVerification = shouldVerifyWithRevenueCat({ expires_at: dbStatus.expires_at, billing_issue: dbStatus.billing_issue, last_updated: dbStatus.last_updated }); if (!needsVerification) { return dbStatus; // Trust database } // 3. Verify with RevenueCat V2 API const rcData = await fetchCustomerDataV2(userId, projectId); // 4. Detect mismatch const dbHasAccess = Object.keys(dbStatus.entitlements).length > 0; const rcHasAccess = rcData?.active_entitlements?.items?.length > 0; if (dbHasAccess !== rcHasAccess) { console.warn('Entitlement mismatch - syncing from RevenueCat'); // 5. Sync database with source of truth await syncDatabaseWithRevenueCat(userId, rcData); } return { entitlements: rcData.active_entitlements?.items || [], source: 'revenuecat', synced: true }; } ``` ### Critical Sync Points **ALWAYS sync entitlements on these events:** | Event | Database Update | Notes | | :---------------- | :----------------------------------- | :------------------------ | | INITIAL\_PURCHASE | Add entitlements | Grant access immediately | | RENEWAL | Update expires\_at | Extend access | | CANCELLATION | Keep entitlements, set cancelled\_at | Access until expiration | | EXPIRATION | Clear entitlements | Remove access | | BILLING\_ISSUE | Keep entitlements, set grace period | Access during grace | | PRODUCT\_CHANGE | Update entitlements & product\_id | May change access level | | REFUND | Clear entitlements | Revoke access immediately | | REFUND\_REVERSED | Restore entitlements | Re-grant access | ### Example: Cancellation Sync ```javascript theme={null} // Webhook: CANCELLATION { "type": "CANCELLATION", "app_user_id": "user_123", "entitlements": { "pro": { "expires_date": "2026-01-17T12:00:00Z", // STILL ACTIVE "product_identifier": "yearly_pro" } }, "expiration_at_ms": 1768651200000 } // Database update await db.query(` UPDATE user_subscriptions SET subscription_status = 'cancelled', cancelled_at = NOW(), auto_renew = false, entitlements = $1, -- KEEP entitlements (still has access) expires_at = $2, -- Access until this date last_updated = NOW() WHERE app_user_id = $3 `, [ JSON.stringify({ "pro": {...} }), // Entitlements still active new Date(1768651200000), // Expiration date "user_123" ]); // User still has access until expiration_at // On expiration date, EXPIRATION webhook will: // - Clear entitlements: {} // - Set is_active = false ``` ### Example: Expiration Sync ```javascript theme={null} // Webhook: EXPIRATION { "type": "EXPIRATION", "app_user_id": "user_123", "entitlements": {}, // EMPTY - no more access "expiration_reason": "UNSUBSCRIBE" } // Database update await db.query(` UPDATE user_subscriptions SET subscription_status = 'expired', is_active = false, entitlements = '{}', -- Clear entitlements auto_renew = false, last_updated = NOW() WHERE app_user_id = $1 `, ["user_123"]); // Also deactivate in normalized table await db.query(` UPDATE user_entitlements SET is_active = false, updated_at = NOW() WHERE app_user_id = $1 `, ["user_123"]); // User loses access immediately ``` ### Sync Verification Schedule **When to verify with RevenueCat API:** ```javascript theme={null} function shouldVerifyWithRevenueCat(dbStatus) { if (!dbStatus) return true; // No data // 1. Expires within 24 hours if (dbStatus.expires_at) { const hoursUntilExpiry = (new Date(dbStatus.expires_at) - new Date()) / (1000 * 60 * 60); if (hoursUntilExpiry < 24 && hoursUntilExpiry > 0) { return true; // Verify near expiration } } // 2. Billing issue active if (dbStatus.billing_issue) { return true; // May have been resolved } // 3. Recently cancelled (within 48 hours) if (dbStatus.cancelled_at) { const hoursSinceCancel = (new Date() - new Date(dbStatus.cancelled_at)) / (1000 * 60 * 60); if (hoursSinceCancel < 48) { return true; // User might uncancelled } } // 4. Cache stale (> 1 hour old) if (dbStatus.last_updated) { const hoursSinceUpdate = (new Date() - new Date(dbStatus.last_updated)) / (1000 * 60 * 60); if (hoursSinceUpdate > 1) { return true; // Refresh stale cache } } return false; // Trust database } ``` ### Monitoring Sync Health Track sync issues in your application: ```javascript theme={null} // Track when database and RevenueCat disagree async function logSyncDiscrepancy(userId, dbStatus, rcStatus) { await db.query(` INSERT INTO sync_discrepancies ( app_user_id, db_is_active, rc_is_active, db_entitlements, rc_entitlements, detected_at ) VALUES ($1, $2, $3, $4, $5, NOW()) `, [ userId, dbStatus.is_active, rcStatus.active_entitlements?.items?.length > 0, JSON.stringify(dbStatus.entitlements), JSON.stringify(rcStatus.active_entitlements?.items) ]); } // Alert on frequent discrepancies const discrepancyRate = await db.query(` SELECT COUNT(*) as count FROM sync_discrepancies WHERE detected_at > NOW() - INTERVAL '1 hour' `); if (discrepancyRate.rows[0].count > 10) { // Send alert - webhooks may be failing await sendAlert('High entitlement sync discrepancy rate'); } ``` *** ## Working with Entitlements ### Understanding Entitlements vs Products **Product ID** = What the user purchased (e.g., "monthly\_pro", "yearly\_premium")\ **Entitlement ID** = What access they have (e.g., "pro", "premium\_features") One product can grant multiple entitlements. Multiple products can grant the same entitlement. ```javascript theme={null} // Example: Both products grant the same "pro" entitlement { "monthly_pro": { entitlements: ["pro"] }, "yearly_pro": { entitlements: ["pro"] } } ``` ### Check User Access ```javascript theme={null} // Method 1: Check database (fast) async function checkUserAccess(userId, requiredEntitlement) { const result = await db.query(` SELECT 1 FROM user_entitlements WHERE app_user_id = $1 AND entitlement_id = $2 AND is_active = true AND (expires_at IS NULL OR expires_at > NOW()) `, [userId, requiredEntitlement]); return result.rows.length > 0; } // Method 2: Check RevenueCat API (authoritative) async function checkUserAccessFromRC(userId, projectId, requiredEntitlement) { const rcData = await fetchCustomerDataV2(userId, projectId); if (!rcData?.active_entitlements?.items) { return false; } return rcData.active_entitlements.items.some(ent => ent.entitlement_id === requiredEntitlement && new Date(ent.expires_at) > new Date() ); } // Method 3: Combined (self-healing) async function checkUserAccessSafe(userId, projectId, requiredEntitlement) { // Check database first const hasAccessDB = await checkUserAccess(userId, requiredEntitlement); // If database says no access, verify with RevenueCat if (!hasAccessDB) { return await checkUserAccessFromRC(userId, projectId, requiredEntitlement); } return true; } ``` ### Middleware for Route Protection ```javascript theme={null} // Express middleware function requireEntitlement(entitlementId) { return async (req, res, next) => { const userId = req.user?.id; if (!userId) { return res.status(401).json({ error: 'Not authenticated' }); } const hasAccess = await userHasEntitlement(userId, entitlementId); if (!hasAccess) { return res.status(403).json({ error: 'Access denied', required_entitlement: entitlementId }); } next(); }; } // Usage app.get('/api/premium-feature', requireEntitlement('pro'), handlePremiumFeature ); ``` ### Frontend Entitlement Check ```javascript theme={null} // API endpoint for frontend app.get('/api/my-entitlements', async (req, res) => { const userId = req.user.id; // Get from database const entitlements = await getUserEntitlements(userId); // Return entitlement list return res.json({ entitlements: Object.keys(entitlements), details: entitlements }); }); // Frontend usage (React example) function useEntitlements() { const [entitlements, setEntitlements] = useState([]); useEffect(() => { fetch('/api/my-entitlements') .then(res => res.json()) .then(data => setEntitlements(data.entitlements)); }, []); const hasAccess = (entitlementId) => { return entitlements.includes(entitlementId); }; return { entitlements, hasAccess }; } // Component function PremiumFeature() { const { hasAccess } = useEntitlements(); if (!hasAccess('pro')) { return
getpurchasehistory://] Restore --> RestoreCheck{Found externalUserId?} RestoreCheck -->|Yes| UseRestore[Use restored ID] RestoreCheck -->|No| UseInstall[Use install_id] UseRestore --> Lock[Lock identity
identity_locked=true] Lock --> Persist UseVault --> Persist[Persist to vault] UseInstall --> Persist Persist --> SyncOS[Sync to OneSignal
setonesignalplayerid://] SyncOS --> SyncDB[Sync to database
POST /api/user/register] SyncDB --> Ready([Paywall can open]) ``` > **Note:** The `getpurchasehistory://` step is RevenueCat-specific. If not using RevenueCat, the flow goes directly from "Vault not found" to "Use install\_id". ## Paywall Readiness Before launching a paywall, ensure both identity resolution and database sync are complete: ```javascript theme={null} // Check readiness before opening paywall function canOpenPaywall() { return identityReady && databaseSynced && appUserId; } // Launch paywall with identity function launchPaywall(offering = 'default') { if (!canOpenPaywall()) { console.warn('Identity not ready, cannot open paywall'); return; } despia(`revenuecat://launchPaywall?external_id=${appUserId}&offering=${offering}`); } // Handle purchase callback (set globally) window.onRevenueCatPurchase = async (purchaseData) => { // Don't grant access immediately - wait for webhook confirmation // Start polling backend for status update pollForSubscriptionStatus(appUserId); }; ``` ## User Login (Claim vs Recover) When a user authenticates, the backend determines whether to **claim** the current identity or **recover** an existing one. ### Login Actions | Action | Condition | Result | | :---------- | :-------------------------------- | :------------------------------------ | | **CLAIM** | Account has no `app_user_id` | Link current `app_user_id` to account | | **RECOVER** | Account already has `app_user_id` | Return existing `app_user_id` | ### Client-Side Implementation ```javascript theme={null} async function handleUserLogin(accountId, credentials) { const response = await fetch('/api/user/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ accountId, currentAppUserId: appUserId, credentials }) }); if (!response.ok) { throw new Error('Login failed'); } const { appUserId: returnedId, action } = await response.json(); // Update Storage Vault await despia(`setvault://?key=app_user_id&value=${returnedId}&locked=false`); // Sync to all services await syncToServices(returnedId); // Update local state appUserId = returnedId; return { appUserId: returnedId, action }; } ``` ## Backend API Endpoints ### User Registration Endpoint This endpoint receives identity syncs from the app on every launch: ```javascript theme={null} // POST /api/user/register async function registerHandler(req, res) { const { appUserId, deviceId, source, platform, timestamp } = req.body; try { // Upsert user record await db.query(` INSERT INTO users (app_user_id, created_at, last_seen) VALUES ($1, $2, $2) ON CONFLICT (app_user_id) DO UPDATE SET last_seen = $2 `, [appUserId, timestamp]); // Track device await db.query(` INSERT INTO user_devices (device_id, app_user_id, platform, last_seen, created_at) VALUES ($1, $2, $3, $4, $4) ON CONFLICT (device_id) DO UPDATE SET app_user_id = $2, last_seen = $4 `, [deviceId, appUserId, platform, timestamp]); // Log identity source for analytics if (source === 'restore') { console.log(`User ${appUserId} recovered via purchase history`); } res.json({ success: true }); } catch (error) { console.error('Registration failed:', error); res.status(500).json({ error: 'Registration failed' }); } } ``` ### User Login Endpoint ```javascript theme={null} // POST /api/user/login async function loginHandler(req, res) { const { accountId, currentAppUserId, credentials } = req.body; // Authenticate user const account = await authenticateUser(accountId, credentials); if (!account) { return res.status(401).json({ error: 'Invalid credentials' }); } // Identity resolution if (!account.app_user_id) { // CLAIM: Link current identity to account await db.accounts.update(accountId, { app_user_id: currentAppUserId }); return res.json({ appUserId: currentAppUserId, action: 'claimed' }); } else { // RECOVER: Return existing identity return res.json({ appUserId: account.app_user_id, action: 'recovered' }); } } ``` ### Login Flow Diagram ```mermaid theme={null} sequenceDiagram autonumber participant App participant API participant Vault participant Services Note over App,Services: Authentication App->>API: POST /login Note over App,API: + currentAppUserId API->>API: Query account Note over App,Services: Identity Resolution alt No app_user_id Note over API: CLAIM API->>API: Save app_user_id API-->>App: action: claimed else Has app_user_id Note over API: RECOVER API-->>App: action: recovered end Note over App,Services: State Sync App->>Vault: Write app_user_id Vault-->>App: OK App->>Services: Sync to all services Services-->>App: OK Note over App,Services: Done ``` ## Syncing to Services After identity resolution, sync the `app_user_id` to all integrated services. ### Generic Sync Pattern ```javascript theme={null} async function syncToServices(appUserId) { // OneSignal (push notifications) despia(`setonesignalplayerid://?user_id=${appUserId}`); // Your backend database await fetch('/api/user/sync', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ appUserId, deviceId: despia.uuid, timestamp: new Date().toISOString() }) }); // RevenueCat: passed via external_id when launching paywall // Stripe: sync via backend webhook } ``` ## Restore Purchases (Required for App Store) Provide a restore purchases button for users who need to recover their subscriptions on a new device. This is **required** by both Apple and Google. ```javascript theme={null} async function restorePurchases() { try { const data = await despia('getpurchasehistory://', ['restoredData']); const purchases = data.restoredData || []; // Find any purchase with an externalUserId const purchaseWithId = purchases.find(p => p.externalUserId); if (purchaseWithId) { const recoveredId = purchaseWithId.externalUserId; // Update Storage Vault await despia(`setvault://?key=app_user_id&value=${recoveredId}&locked=false`); await despia('setvault://?key=identity_locked&value=true&locked=false'); // Sync to OneSignal despia(`setonesignalplayerid://?user_id=${recoveredId}`); // Update local state appUserId = recoveredId; // Sync to backend await fetch('/api/user/register', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ appUserId: recoveredId, deviceId: installId, source: 'restore_button', timestamp: new Date().toISOString() }) }); return { success: true, appUserId: recoveredId }; } return { success: false, message: 'No purchases found' }; } catch (error) { return { success: false, error: error.message }; } } ``` ### Where to Place the Restore Button * Settings screen (most common) * Paywall screen * Account or profile screen * Onboarding flow for returning users ## Integration Examples ### RevenueCat (In-App Purchases) — Deep Integration RevenueCat is deeply integrated into Despia. The `app_user_id` is passed as `external_id` when launching paywalls. ```javascript theme={null} // Launch native paywall despia(`revenuecat://launchPaywall?external_id=${appUserId}&offering=default`); // Purchase a specific product despia(`revenuecat://purchase?external_id=${appUserId}&product=monthly_premium`); // Check entitlement status async function checkPremiumAccess() { const history = await despia('getpurchasehistory://', ['restoredData']); const activeSubs = history.restoredData.filter(p => p.isActive && p.entitlementId === 'premium' ); return activeSubs.length > 0; } ``` #### Purchase Response Fields The `getpurchasehistory://` response includes: | Field | Description | | :---------------------- | :----------------------------------------------- | | `transactionId` | Unique identifier for this transaction | | `originalTransactionId` | Links to original purchase (for renewals) | | `productId` | Product ID from App Store Connect / Play Console | | `type` | `"subscription"` or `"product"` | | `entitlementId` | The entitlement this purchase grants | | `isActive` | Whether purchase currently grants access | | `willRenew` | Whether subscription will auto-renew | | `purchaseDate` | ISO timestamp of transaction | | `expirationDate` | When access expires (null for lifetime) | | `externalUserId` | The `app_user_id` linked to this purchase | | `store` | `"app_store"` or `"play_store"` | #### Hybrid Payment Example (Native + Web) ```javascript theme={null} const handleUpgrade = () => { if (navigator.userAgent.includes('despia')) { // Native: Use RevenueCat despia(`revenuecat://launchPaywall?external_id=${appUserId}&offering=default`); } else { // Web fallback: Redirect to Stripe window.location.href = `/pricing?user=${appUserId}`; } }; ``` ### OneSignal (Push Notifications) ```javascript theme={null} // Set external user ID on every app load despia(`setonesignalplayerid://?user_id=${appUserId}`); ``` ### Stripe (Web-Based Payments) For web-based services like Stripe, sync via your backend: ```javascript theme={null} // Client: Pass app_user_id to your backend async function createCheckoutSession(priceId) { const response = await fetch('/api/stripe/checkout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ appUserId, priceId, deviceId: despia.uuid }) }); const { sessionUrl } = await response.json(); window.location.href = sessionUrl; } ``` ```javascript theme={null} // Backend: Create Stripe customer with app_user_id as metadata async function createCheckoutHandler(req, res) { const { appUserId, priceId, deviceId } = req.body; // Find or create Stripe customer let customer = await findStripeCustomerByAppUserId(appUserId); if (!customer) { customer = await stripe.customers.create({ metadata: { app_user_id: appUserId, device_id: deviceId } }); await saveStripeCustomerMapping(appUserId, customer.id); } // Create checkout session const session = await stripe.checkout.sessions.create({ customer: customer.id, line_items: [{ price: priceId, quantity: 1 }], mode: 'subscription', success_url: 'myapp://payment/success', cancel_url: 'myapp://payment/cancel', metadata: { app_user_id: appUserId } }); res.json({ sessionUrl: session.url }); } ``` ```javascript theme={null} // Backend: Handle Stripe webhook async function stripeWebhookHandler(req, res) { const event = stripe.webhooks.constructEvent( req.body, req.headers['stripe-signature'], webhookSecret ); switch (event.type) { case 'checkout.session.completed': const session = event.data.object; const appUserId = session.metadata.app_user_id; // Update user subscription status await updateUserSubscription(appUserId, { stripeCustomerId: session.customer, subscriptionId: session.subscription, status: 'active' }); break; } res.json({ received: true }); } ``` ### Generic Web SDK Pattern For any web-based SDK, follow this pattern: ```javascript theme={null} // 1. Client passes app_user_id to backend await fetch('/api/service/action', { method: 'POST', body: JSON.stringify({ appUserId, deviceId: despia.uuid, // ... service-specific params }) }); // 2. Backend links service's user ID to app_user_id async function serviceHandler(req, res) { const { appUserId } = req.body; // Create or find service user const serviceUser = await service.createUser({ externalId: appUserId, // or metadata: { app_user_id: appUserId } }); // Store mapping await saveServiceMapping(appUserId, serviceUser.id); } // 3. Backend handles webhooks using app_user_id async function serviceWebhook(req, res) { const event = req.body; const appUserId = event.metadata.app_user_id || await getAppUserIdFromServiceId(event.user_id); // Update your database await updateUser(appUserId, { /* ... */ }); } ``` ## Database Schema Store the `app_user_id` as the primary link across all tables: ```javascript theme={null} -- Users table CREATE TABLE users ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), app_user_id TEXT UNIQUE NOT NULL, email TEXT, created_at TIMESTAMP DEFAULT NOW() ); -- Service mappings CREATE TABLE service_mappings ( app_user_id TEXT REFERENCES users(app_user_id), service_name TEXT NOT NULL, service_user_id TEXT NOT NULL, created_at TIMESTAMP DEFAULT NOW(), PRIMARY KEY (app_user_id, service_name) ); -- Example: devices CREATE TABLE user_devices ( device_id TEXT PRIMARY KEY, app_user_id TEXT REFERENCES users(app_user_id), last_seen TIMESTAMP, created_at TIMESTAMP DEFAULT NOW() ); ``` ## Summary | Component | Key | Purpose | | :------------ | :--------------------- | :--------------------------------------------- | | Storage Vault | `app_user_id` | Persistent identity across sessions/reinstalls | | Backend DB | `app_user_id` | Central user record | | RevenueCat | `external_id` | Links purchases to user | | OneSignal | `external_user_id` | Links push notifications to user | | Stripe | `metadata.app_user_id` | Links payments to user | | Any SDK | varies | Always map back to `app_user_id` | The `app_user_id` is the single source of truth. Every service integration should either accept it directly or map their internal IDs back to it via your backend. # Animations Source: https://setup.despia.com/best-practices/frontend/animations CSS animation first. Scroll-driven CSS for drawers, sheets, parallax, and page transitions. JS fallback only where CSS is not supported. ## Philosophy CSS animations run on the compositor thread. They stay smooth under Low Power Mode, thermal throttling, and every other constraint a mobile device can throw at them. JavaScript animations run on the main thread and compete with everything else the app is doing. The hierarchy is: 1. **CSS scroll-driven** (`animation-timeline`) for anything swipe-driven - drawers, sheets, parallax, page stacks, carousels. Zero JS per frame. Compositor-only. 2. **CSS transitions and keyframes** for everything else - tap feedback, modals, toasts, loaders. Still compositor-safe on `transform` and `opacity`. 3. **JS `requestAnimationFrame`** only when CSS cannot express the result, and only as a fallback when scroll-driven is not supported. Only animate `transform` and `opacity`. Everything else triggers layout or paint on the main thread. *** ## Touch Interaction Feedback The input is always touch. Use `:active`, never `:hover`. `:active` fires on press and clears on release. `:hover` fires on tap and sticks with nothing to clear it. ```css theme={null} .button { transition: transform 0.1s ease, opacity 0.1s ease; } .button:active { transform: scale(0.95); opacity: 0.8; } .card { transition: transform 0.1s ease, opacity 0.1s ease; } .card:active { transform: scale(0.98); opacity: 0.85; } ``` If a component also renders in a browser, guard `:hover` with an input capability query. Screen width tells you nothing about input type. ```css theme={null} @media (hover: hover) and (pointer: fine) { .card:hover { transform: translateY(-0.25rem); } } ``` *** ## CSS Transitions ```css theme={null} /* Tap feedback */ .button { transition: transform 0.1s ease; } /* State changes */ .card { transition: transform 0.3s ease; } /* Large entrances */ .modal { transition: opacity 0.4s ease, transform 0.4s ease; } ``` | Use case | Duration | | :-------------------- | :------------ | | Tap feedback | 0.1s to 0.15s | | Standard state change | 0.2s to 0.3s | | Large movements | 0.3s to 0.5s | | Maximum | 0.6s | ```css theme={null} .enter { transition-timing-function: cubic-bezier(0.0, 0.0, 0.2, 1); } .exit { transition-timing-function: cubic-bezier(0.4, 0.0, 1, 1); } .bounce { transition-timing-function: cubic-bezier(0.68, -0.55, 0.265, 1.55); } ``` *** ## CSS Keyframe Animations ```css theme={null} @keyframes fadeIn { from { opacity: 0; transform: translateY(1rem); } to { opacity: 1; transform: translateY(0); } } .element { animation: fadeIn 0.4s ease forwards; will-change: transform, opacity; } ``` ```css theme={null} animation-fill-mode: forwards; /* hold end state */ animation-fill-mode: both; /* hold start before delay, end after */ ``` *** ## Will-Change Add `will-change: transform` to `position: fixed` or `position: sticky` elements before they animate. Remove it after. ```css theme={null} .drawer { will-change: transform; } ``` ```js theme={null} element.addEventListener('animationend', () => { element.style.willChange = 'auto'; }, { once: true }); ``` Never apply `will-change` globally. Each declaration allocates a compositor layer. *** ## Scroll-Driven Animations For any swipe-driven UI, scroll-driven CSS is the preferred approach. The scroll position drives the animation directly on the compositor. No JS per frame, no touch event listeners, smooth under every power state. ### WebView Compatibility | API | Available | | :--------------------------------- | :------------------------- | | CSS `animation-timeline: scroll()` | Yes | | CSS `animation-timeline: view()` | Yes | | `new ScrollTimeline()` in JS | No - throws ReferenceError | | `new ViewTimeline()` in JS | No - throws ReferenceError | ### Browser Support and Fallbacks `animation-timeline` requires Chromium 115+ / Safari 18+. Use `@supports` to layer it on top of a working CSS fallback. **Write the fallback first, enhance inside `@supports`:** ```css theme={null} /* Fallback - works everywhere */ .drawer { transform: translateX(-100%); transition: transform 0.3s cubic-bezier(0.0, 0.0, 0.2, 1); } .drawer.is-open { transform: translateX(0); } /* Enhancement - scroll-driven where supported */ @supports (animation-timeline: scroll()) { .drawer { transition: none; animation: drawer-in linear both; animation-timeline: scroll(nearest inline); animation-range: 0% 50%; } } ``` **Always start items visible for scroll-reveal.** If `animation-timeline: view()` is unsupported, items stay at `opacity: 0` forever. ```css theme={null} /* Baseline - visible */ .list-item { opacity: 1; transform: translateY(0); } /* Enhancement - animate in */ @supports (animation-timeline: scroll()) { .list-item { opacity: 0; transform: translateY(1rem); animation: fadeInUp 0.4s ease forwards; animation-timeline: view(); animation-range: entry 0% entry 35%; } } @keyframes fadeInUp { to { opacity: 1; transform: translateY(0); } } ``` **Branch in JS with `CSS.supports()`:** ```js theme={null} const supportsScrollTimeline = CSS.supports('animation-timeline: scroll()'); function initDrawer(sceneEl, drawerEl) { if (supportsScrollTimeline) { initScrollDriver(sceneEl, drawerEl); } else { initClassToggle(drawerEl); } } function initScrollDriver(sceneEl, drawerEl) { const driver = sceneEl.querySelector('.scroll-driver'); const openPos = driver.scrollWidth / 2; sceneEl.querySelector('#menuBtn').addEventListener('click', () => driver.scrollTo({ left: openPos, behavior: 'smooth' })); sceneEl.querySelector('#scrim').addEventListener('click', () => driver.scrollTo({ left: 0, behavior: 'smooth' })); onScrollSettled(driver, () => { const open = driver.scrollLeft >= openPos * 0.9; drawerEl.classList.toggle('is-open', open); }); } function initClassToggle(drawerEl) { document.getElementById('menuBtn').addEventListener('click', () => drawerEl.classList.add('is-open')); document.getElementById('scrim').addEventListener('click', () => drawerEl.classList.remove('is-open')); } ``` **Support matrix:** | Environment | `animation-timeline` support | | :---------------------------- | :---------------------------- | | WKWebView - iOS 18+ | Yes | | WKWebView - iOS 17 and below | No - use `@supports` fallback | | Android WebView - Chrome 115+ | Yes | | Android WebView - older | No - use `@supports` fallback | ### The Hidden Scroller Pattern The base technique for all swipe-driven UI. An invisible scroll container captures gestures. Its scroll position becomes the CSS timeline for the content below. ``` User swipes > invisible scroller moves > CSS timeline drives your UI ``` No `touchstart`. No `touchmove`. No `requestAnimationFrame`. Native scroll engine handles physics, momentum, and snap. ```html theme={null}
...
```
```javascript theme={null}
// Intersection Observer for custom lazy loading
const imageObserver = new IntersectionObserver((entries) => {
entries.forEach(entry => {
if (entry.isIntersecting) {
const img = entry.target;
img.src = img.dataset.src;
imageObserver.unobserve(img);
}
});
});
document.querySelectorAll('img[data-src]').forEach(img => {
imageObserver.observe(img);
});
```
### Optimize Image Dimensions
Serve images at display size, not larger:
```html theme={null}
```
### Use Responsive Images
Serve different sizes based on viewport:
```html theme={null}
```
***
## DOM Manipulation
### Minimize DOM Access
Cache DOM queries:
```javascript theme={null}
// Incorrect: repeated queries
function updateList() {
document.querySelector('.list').innerHTML = '';
for (let i = 0; i < items.length; i++) {
document.querySelector('.list').appendChild(createItem(items[i]));
}
}
// Correct: cache reference
function updateList() {
const list = document.querySelector('.list');
list.innerHTML = '';
items.forEach(item => list.appendChild(createItem(item)));
}
```
### Use Document Fragments
Batch DOM insertions:
```javascript theme={null}
// Incorrect: multiple reflows
items.forEach(item => {
container.appendChild(createItem(item));
});
// Correct: single reflow
const fragment = document.createDocumentFragment();
items.forEach(item => {
fragment.appendChild(createItem(item));
});
container.appendChild(fragment);
```
### Virtual Scrolling for Long Lists
For long lists (100+ items), use virtual scrolling to render only visible items. **TanStack Virtual** is proven to work exceptionally well with Despia.
**Installation:**
```
npm install @tanstack/react-virtual
```
**Basic Implementation:**
```tsx theme={null}
import { useVirtualizer } from '@tanstack/react-virtual';
import { useRef } from 'react';
function VirtualList({ items }) {
const parentRef = useRef(null);
const virtualizer = useVirtualizer({
count: items.length,
getScrollElement: () => parentRef.current,
estimateSize: () => 50, // Estimated item height
overscan: 5 // Render 5 extra items above/below viewport
});
return (
{virtualizer.getVirtualItems().map((virtualItem) => (
{items[virtualItem.index].content}
))}
{items.map(item =>
);
}
// Correct: use TanStack Virtual
import { useVirtualizer } from '@tanstack/react-virtual';
function ItemList({ items }) {
const parentRef = useRef(null);
const virtualizer = useVirtualizer({
count: items.length,
getScrollElement: () => parentRef.current,
estimateSize: () => 50
});
return (
{/* Virtual items only */}
);
}
```
**Impact:** Large lists without virtualization cause significant frame drops and poor scroll performance. TanStack Virtual maintains smooth scrolling by rendering only visible items.
### Excessive Re-renders
```javascript theme={null}
// Incorrect: creates new object every render
function Component() {
return items.map(item => (
```
***
## Performance Budget
### Define Targets
Set measurable performance goals:
| Metric | Target | Maximum |
| :----------------------- | :------- | :------ |
| First Contentful Paint | \< 1.5s | 2.0s |
| Time to Interactive | \< 3.0s | 4.0s |
| Total Bundle Size | \< 200kb | 300kb |
| JavaScript Execution | \< 500ms | 1000ms |
| Frame Rate (Normal) | 60fps | 55fps |
| Frame Rate (Constrained) | 30fps | 25fps |
This text can be selected by users.
Article Title
Users can select and copy this content.
const example = "selectable code";
```
### Touch Feedback Implementation
Provide visual feedback for touch interactions:
```css theme={null}
.button {
transition: opacity 0.1s ease;
}
.button:active {
opacity: 0.7;
}
/* Alternative: transform-based feedback (improved performance) */
.button:active {
transform: scale(0.95);
}
```
***
## Complete Implementation Example
```html theme={null}
My App
This content can be selected and copied by users.
Users can select and copy this text.