From 2cd425a344baa6e242c2e691c9c5543f6ee1a3f0 Mon Sep 17 00:00:00 2001 From: "Builder.io" Date: Wed, 5 Nov 2025 07:34:02 +0000 Subject: [PATCH] Discord Activity Setup Guide cgen-e4c4f15ce727456ca666db380bbcdff9 --- DISCORD_SETUP.md | 195 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 DISCORD_SETUP.md diff --git a/DISCORD_SETUP.md b/DISCORD_SETUP.md new file mode 100644 index 00000000..ada9808a --- /dev/null +++ b/DISCORD_SETUP.md @@ -0,0 +1,195 @@ +# Discord Activity Setup Guide + +This guide explains how to set up and deploy the AeThex platform as a Discord Activity. + +## Overview + +AeThex can now be embedded as a Discord Activity, allowing users to access the full platform directly within Discord. The integration uses: + +- **Discord SDK** for Activity context detection and user authentication +- **Discord OAuth 2.0** for secure user verification +- **React Context** for managing Discord user state + +## Prerequisites + +- **Discord Application ID**: `578971245454950421` +- **Discord Client Secret** (from Discord Developer Portal) +- **Deployed Application URL** (for OAuth redirect URI) + +## Configuration Steps + +### 1. Discord Developer Portal Setup + +1. Go to [Discord Developer Portal](https://discord.com/developers/applications) +2. Open your application (ID: `578971245454950421`) +3. Navigate to **OAuth2 > General** +4. Copy your **Client Secret** and save it securely +5. Add Redirect URIs: + - `https://your-domain.com/discord/callback` (for standard OAuth) + - `https://your-domain.com` (for Activity context) + +### 2. Environment Variables + +Set these environment variables in your deployment: + +**For Netlify/Vercel:** +```bash +VITE_DISCORD_CLIENT_ID=578971245454950421 +DISCORD_CLIENT_SECRET=your-client-secret-here +DISCORD_REDIRECT_URI=https://your-domain.com/discord/callback +``` + +**For Local Development:** +```bash +# .env or via DevServerControl +VITE_DISCORD_CLIENT_ID=578971245454950421 +DISCORD_CLIENT_SECRET=your-client-secret-here +PUBLIC_BASE_URL=http://localhost:5173 +``` + +### 3. Activity Configuration in Discord + +In the Discord Developer Portal for your application: + +1. Go to **App Details** +2. Look for "Activities" or "Embedded App Sub-Command" +3. Set the **Activity URL** to your deployment URL: + - `https://your-domain.com/discord` +4. Enable "Requires OAuth2 Code Grant" + +### 4. Deploy the Application + +The application is now ready to be deployed. All changes include: + +- **Discord Context Provider** (`code/client/contexts/DiscordContext.tsx`) +- **Discord Activity Page** (`code/client/pages/DiscordActivity.tsx`) +- **OAuth Callback Handler** (`code/client/pages/DiscordOAuthCallback.tsx`) +- **API Endpoint** (`/api/discord/oauth/callback`) +- **Discord SDK Integration** (in `index.html`) + +## How It Works + +### Activity Flow + +1. **User launches Activity**: User opens the Discord Activity in a Discord server +2. **SDK Initialization**: `DiscordContext` attempts to load and initialize Discord SDK +3. **User Detection**: If in Discord Activity context, user info is retrieved from Discord +4. **Authentication**: + - If in Discord Activity: User is automatically identified via Discord + - If standard OAuth: User is redirected to Discord OAuth flow +5. **App Access**: User gains full access to AeThex platform with Discord credentials + +### Routes + +- **`/discord`** - Main Discord Activity page +- **`/discord/callback`** - OAuth callback handler (redirects to dashboard) +- **`/api/discord/oauth/callback`** - Backend OAuth token exchange + +## Usage + +### For Users + +Users can access AeThex as a Discord Activity by: + +1. Going to their Discord server +2. Clicking on "Activities" (rocket icon) +3. Searching for or selecting "AeThex" +4. Activity launches in the Discord client + +### For Developers + +To integrate Discord authentication in components: + +```typescript +import { useDiscord } from '@/contexts/DiscordContext'; + +export function MyComponent() { + const { isDiscordActivity, discordUser, initiateDiscordOAuth } = useDiscord(); + + return ( +
+ {isDiscordActivity ? ( +

Running as Discord Activity for {discordUser?.username}

+ ) : ( + + )} +
+ ); +} +``` + +## Troubleshooting + +### SDK Not Loading + +If Discord SDK doesn't load: +- Check that you're running the Activity in Discord (not a web browser) +- Verify the Activity URL is correctly configured in Discord Developer Portal +- Check browser console for SDK loading errors + +### OAuth Failures + +If OAuth fails: +- Verify `DISCORD_CLIENT_SECRET` is set correctly +- Confirm redirect URI matches Discord Developer Portal settings +- Check server logs for token exchange errors + +### User Not Detected + +If Discord user info isn't available: +- The Activity might not have proper permissions +- User might not be authenticated with Discord +- Check Discord SDK `ready()` promise resolved successfully + +## Security Considerations + +1. **Client Secret**: Keep `DISCORD_CLIENT_SECRET` secure (never expose in frontend) +2. **OAuth State**: Discord SDK handles state validation automatically +3. **Redirect URI**: Only whitelist your official domain +4. **Token Storage**: OAuth tokens are stored securely in `localStorage` +5. **CORS**: Discord Activities run in isolated context; standard CORS doesn't apply + +## API Documentation + +### `POST /api/discord/oauth/callback` + +Exchanges Discord authorization code for access token. + +**Request:** +```json +{ + "code": "authorization_code", + "state": "optional_state_value" +} +``` + +**Response:** +```json +{ + "ok": true, + "access_token": "token", + "discord_user": { + "id": "user_id", + "username": "username", + "avatar": "avatar_url", + "email": "user@example.com" + } +} +``` + +## Next Steps + +1. Obtain Discord Client Secret from Developer Portal +2. Set environment variables in your deployment platform +3. Deploy the application +4. Test the Activity in a Discord server +5. Monitor logs for any issues + +## Support + +For issues or questions: +- Check Discord Developer Portal documentation: https://discord.dev +- Review error logs in server console +- Contact support@aethex.tech