AeThex-Corporation/aethex-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
aethex-forge/DISCORD_SETUP.md
Builder.io 2cd425a344 Discord Activity Setup Guide 
cgen-e4c4f15ce727456ca666db380bbcdff9
2025-11-05 07:34:02 +00:00

5.5 KiB
Raw Blame History

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

VITE_DISCORD_CLIENT_ID=578971245454950421
DISCORD_CLIENT_SECRET=your-client-secret-here
DISCORD_REDIRECT_URI=https://your-domain.com/discord/callback

For Local Development:

# .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:

import { useDiscord } from '@/contexts/DiscordContext';

export function MyComponent() {
  const { isDiscordActivity, discordUser, initiateDiscordOAuth } = useDiscord();

  return (
    <div>
      {isDiscordActivity ? (
        <p>Running as Discord Activity for {discordUser?.username}</p>
      ) : (
        <button onClick={initiateDiscordOAuth}>
          Connect with Discord
        </button>
      )}
    </div>
  );
}

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:

{
  "code": "authorization_code",
  "state": "optional_state_value"
}

Response:

{
  "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: