Discord Activity SPA Compliance Verification Checklist

cgen-30d39ac7b3b845e6b94390fae539b5b4
2025-11-10 00:58:16 +00:00 · 2025-11-10 00:58:16 +00:00 · 5f0654e531
commit 5f0654e531
parent 95dd420e4a
1 changed files with 230 additions and 0 deletions
--- a/docs/ACTIVITY-COMPLIANCE-CHECKLIST.md
+++ b/docs/ACTIVITY-COMPLIANCE-CHECKLIST.md
@ -0,0 +1,230 @@
+# Discord Activity SPA Compliance Checklist
+
+This checklist ensures your Discord Activity meets Discord's Single-Page Application (SPA) requirements.
+
+## ✅ Code Compliance
+
+### Activity Component (code/client/pages/Activity.tsx)
+
+- [ ] **No React Router Navigation**
+  - [ ] No `useNavigate()` hook
+  - [ ] No `navigate()` calls
+  - [ ] No `<Link to="...">` components
+
+- [ ] **No Internal Page Navigation**
+  - [ ] All internal navigation removed
+  - [ ] Routes like `/creators`, `/opportunities`, `/settings` don't exist in Activity
+  - [ ] If accessing main app features, use `window.open(url, "_blank")`
+
+- [ ] **Proper Error Handling**
+  - [ ] Graceful error state display
+  - [ ] Loading state handled properly
+  - [ ] "Not in Discord" state shows helpful message instead of crashing
+
+- [ ] **PostMessage Communication**
+  - [ ] Activity uses Discord SDK (DiscordActivityContext)
+  - [ ] SDK handles all Discord communication
+  - [ ] No direct iframe communication attempted
+
+### Manifest Configuration (code/public/discord-manifest.json)
+
+- [ ] **Discord Proxy Domain Only**
+  - [ ] `rpc_origins` contains ONLY: `"https://578971245454950421.discordsays.com"`
+  - [ ] No external domains listed
+  - [ ] No `aethex.dev` in rpc_origins
+
+- [ ] **Valid JSON Structure**
+  - [ ] `id` matches Discord app ID: `"578971245454950421"`
+  - [ ] `version` is set: `"1"`
+  - [ ] `name` describes the Activity
+  - [ ] `description` explains Activity purpose
+
+- [ ] **No External Interactions Configured**
+  - [ ] If `interactions` present, URL points to Discord proxy domain
+  - [ ] No external API endpoints in manifest
+
+### Context/SDK Setup (code/client/contexts/DiscordActivityContext.tsx)
+
+- [ ] **Proper SDK Initialization**
+  - [ ] SDK imported: `@discord/embedded-app-sdk`
+  - [ ] `DiscordSDK` instantiated with client ID
+  - [ ] `sdk.ready()` awaited before using SDK
+  - [ ] `sdk.authenticate()` called after ready
+
+- [ ] **Correct OAuth Flow**
+  - [ ] Uses `sdk.commands.authorize()` for OAuth
+  - [ ] Exchanges code for token via `/api/discord/activity-auth`
+  - [ ] Token used to authenticate with SDK
+  - [ ] User data fetched after authentication
+
+- [ ] **Proper Error Handling**
+  - [ ] Errors logged with `[Discord Activity]` prefix
+  - [ ] User-friendly error messages displayed
+  - [ ] No silent failures
+  - [ ] Console logs helpful for debugging
+
+## ✅ Navigation Compliance
+
+### Link Handling
+
+- [ ] **All External Links Use window.open()**
+  ```typescript
+  // ✅ CORRECT
+  <button onClick={() => window.open(url, "_blank")}>
+  
+  // ❌ WRONG
+  <a href={url}>
+  <Link to={url}>
+  navigate(url)
+  ```
+
+- [ ] **All Buttons Have Clear Intent**
+  - [ ] "View Profile" → Opens profile in new window
+  - [ ] "Browse Creators" → Opens main app in new window
+  - [ ] "Settings" → Opens settings in new window
+
+- [ ] **No Hidden Navigation**
+  - [ ] No `useEffect` that navigates
+  - [ ] No programmatic routing
+  - [ ] No redirects outside Activity
+
+## ✅ Data Handling
+
+### User Data
+
+- [ ] **Data Fetched from Backend**
+  - [ ] Uses `/api/discord/activity-auth` endpoint
+  - [ ] Passes access token from SDK
+  - [ ] Displays cached/static data, not real-time
+  - [ ] Handles missing data gracefully
+
+- [ ] **No Data Mutations in Activity**
+  - [ ] Profile updates happen in main app
+  - [ ] Settings changes happen in main app
+  - [ ] Activity is read-only display layer
+
+## ✅ Deployment & Testing
+
+### Pre-Deployment
+
+- [ ] **Build Succeeds**
+  ```bash
+  npm run build
+  # Should produce no errors about Activity
+  ```
+
+- [ ] **Dev Server Works**
+  ```bash
+  npm run dev
+  # Activity loads without console errors
+  ```
+
+- [ ] **No External Resource Issues**
+  - [ ] All images load correctly
+  - [ ] No "blocked by CSP" errors
+  - [ ] No CORS errors in console
+
+### Post-Deployment
+
+- [ ] **Manifest Served Correctly**
+  - [ ] `https://aethex.dev/discord-manifest.json` returns valid JSON
+  - [ ] Content-Type is `application/json`
+  - [ ] No 404 errors
+
+- [ ] **Activity Loads in Discord**
+  - [ ] Can launch from Discord
+  - [ ] No loading stuck state
+  - [ ] User profile displays
+  - [ ] Buttons work correctly
+
+- [ ] **Console Logs Clear**
+  - [ ] No errors prefixed with `[Discord Activity]`
+  - [ ] Helpful debug logs present
+  - [ ] No React warnings about navigation
+
+## ✅ Advanced Compliance
+
+### URL Mappings (If Needed)
+
+- [ ] **External Resources Have Mappings**
+  - [ ] Add to manifest if using external APIs
+  - [ ] Format: `"/api/external": "https://api.example.com"`
+  - [ ] Test that requests go through Discord proxy
+
+### Cookie Handling (If Needed)
+
+- [ ] **Cookies Use Correct Domain**
+  - [ ] Domain: `578971245454950421.discordsays.com`
+  - [ ] `SameSite=None` flag set
+  - [ ] `Partitioned` flag set (if supporting third-party cookies)
+
+### Security
+
+- [ ] **No Sensitive Data in Activity**
+  - [ ] Don't store auth tokens in Activity
+  - [ ] Don't expose API keys
+  - [ ] Use backend proxy for secure operations
+
+## 🔍 Verification Steps
+
+### Step 1: Code Review
+```bash
+# Check Activity component
+grep -n "navigate\|useNavigate\|<Link\|href=" code/client/pages/Activity.tsx
+
+# Check for router imports
+grep -n "react-router" code/client/pages/Activity.tsx
+
+# Result: Should find NO matches (except in comments)
+```
+
+### Step 2: Manifest Validation
+```bash
+# Check manifest domains
+cat code/public/discord-manifest.json
+
+# Should only show Discord proxy domain in rpc_origins
+```
+
+### Step 3: Runtime Testing
+1. Launch Activity in Discord
+2. Open DevTools (F12)
+3. Check console for `[Discord Activity]` logs
+4. Verify no errors about navigation/routing
+5. Click buttons and verify they open in new windows
+6. Reload Activity - should re-initialize properly
+
+### Step 4: Cross-Origin Testing
+1. In Discord DevTools:
+   - Go to Console tab
+   - Look for CORS errors
+   - Should see ZERO CORS errors
+2. If errors found:
+   - Check manifest rpc_origins
+   - Verify API endpoints are accessed through Discord proxy
+
+## Common Issues & Fixes
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| Activity won't load | Missing frame_id in URL | Check you're in Discord iframe |
+| "Cannot find module 'react-router'" | Router still imported | Remove router imports |
+| Links navigate within Activity | Using `href` or `navigate()` | Change to `window.open(..., "_blank")` |
+| User data doesn't load | `/api/discord/activity-auth` failing | Check SDK authentication success |
+| CORS errors in console | External domains in rpc_origins | Remove from manifest, use Discord proxy |
+| Manifest 404 error | File not in public directory | Move to `code/public/discord-manifest.json` |
+
+## Certification Summary
+
+When all items are checked, your Activity is:
+
+✅ **Discord SPA Compliant** - Follows all official Discord Activity requirements
+✅ **Properly Isolated** - Runs in sandbox without breaking iframe
+✅ **Correctly Configured** - Manifest and SDK setup are proper
+✅ **Ready for Production** - Can be deployed safely
+
+## References
+
+- Discord Activities Overview: https://discord.com/developers/docs/activities/overview
+- SDK Reference: https://discord.com/developers/docs/activities/sdk-reference
+- Best Practices: https://discord.com/developers/docs/activities/security