diff --git a/docs/discord-social-sdk/core-concepts.mdx b/docs/discord-social-sdk/core-concepts.mdx index 9554376a59..ad870e7d92 100644 --- a/docs/discord-social-sdk/core-concepts.mdx +++ b/docs/discord-social-sdk/core-concepts.mdx @@ -1,7 +1,12 @@ --- sidebar_label: Core Concepts +subpages: + - core-concepts/core-features.mdx + - core-concepts/communication-features.mdx + - core-concepts/integration-overview.mdx + - core-concepts/platform-compatibility.mdx + - core-concepts/oauth2-scopes.mdx --- -import ConsoleAccess from './partials/callouts/console-access.mdx'; [Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > {sidebar_label} @@ -9,303 +14,47 @@ import ConsoleAccess from './partials/callouts/console-access.mdx'; The Discord Social SDK allows you to build social features into your game, including friend lists, messaging, voice chat, and rich presence. Unlike a traditional SDK with built-in UI components, the Discord Social SDK provides access to raw data, allowing developers to create a fully customized experience that aligns with their game's aesthetic. ---- +## Core Concepts Overview -## How the Discord Social SDK Works +Select a topic below to learn more about the Discord Social SDK: -### Integration Overview - -To implement the Discord Social SDK, developers for all platforms will generally follow these steps: - -1. Import the SDK -2. Initialize the SDK: - - Create a [`Client`] instance. - - Set up event listeners to monitor SDK events and callbacks -3. Authenticate users with flexible account options - - Link an existing Discord account via OAuth ([`Client::Authorize`]). - - Create and manage provisional accounts for users who don't have or want a Discord account ([`Client::GetProvisionalToken`]). -4. Implement social features - - Implement [unified friends list](/docs/discord-social-sdk/development-guides/creating-a-unified-friends-list) and [relationships](/docs/discord-social-sdk/development-guides/managing-relationships). - - Use [rich presence](/docs/discord-social-sdk/development-guides/setting-rich-presence) for game activity updates. - - Set up [lobbies](/docs/discord-social-sdk/development-guides/managing-lobbies) for multiplayer interaction and [game invites](/docs/discord-social-sdk/development-guides/managing-game-invites). - - Manage [direct message](/docs/discord-social-sdk/development-guides/sending-direct-messages), [linked channels](/docs/discord-social-sdk/development-guides/creating-a-unified-friends-list), and [voice communication](/docs/discord-social-sdk/development-guides/managing-voice-chat). -5. Handle events & API calls: - - Listen for changes in friend lists, presence updates, and chat messages. - - Use Discord's APIs to update statuses, send messages, and manage connections. - -This guide is a conceptual overview. If you're ready to start building, [follow our step-by-step guide](/docs/discord-social-sdk/getting-started) to set up the SDK in your game engine. - ---- - -## Limited Access Features - -The following features are only fully unlocked when joining the closed beta: - -- **Cross-platform messaging** allows users to message each other in-game and on Discord. -- **Voice chat integration** delivers excellent audio quality and lets you create individual user voice streams. -- **Linked Channels** provide persistent group chats that allow conversations to flow seamlessly before, during, and after gameplay—both in-game and out. - -While these limited access features are available in the Discord Social SDK, their usage is capped with a rate limit. Please read our [documentation on rate limits](/docs/topics/rate-limits) to learn more. - -:::preview -To apply for full access to closed beta features or to reach out to Discord directly to discuss your game, please fill out [this form](https://discord.com/developers/social-sdk-closed-beta-access-request-form). -::: - ---- - -## SDK Platform Compatibility - -:::info -You can find instructions on how to download the SDK for each platform in the [Getting Started](/docs/discord-social-sdk/getting-started) guide. -::: - -The Discord Social SDK is available for the following platforms: - -### Desktop - -- Standalone C++ (Windows and macOS) -- Unreal Engine (Windows Only) -- Unity (Windows and macOS) - -### Android/iOS (full mobile support & guides coming soon) - -- Standalone C++ -- Unity - -### Console (full console support & guides coming soon) - - -- **Xbox Series X|S and Xbox One** - - Standalone C++ - - Unreal Engine - - Unity -- **PlayStation5 and PlayStation4** - - Standalone C++ - - Unreal Engine - - Unity - - - ---- - -## OAuth2 Scopes - -OAuth2 scopes define the level of access your app has to a user's Discord account - -What OAuth scopes are available to your integration are set via -[`AuthorizationArgs::SetScopes`] on [`AuthorizationArgs`] which is passed to [`Client::Authorize`] on Social SDK -authentication. - -### Default Presence Scopes - -At a minimum, the Social SDK uses the following scopes to use features like rich presence and friends list: - -- `openid` -- `sdk.social_layer_presence` - -The default presence features include: - -* [Account Linking](/docs/discord-social-sdk/core-concepts#account-linking) -* [Provisional Accounts](/docs/discord-social-sdk/core-concepts#provisional-accounts) -* [Friend System & Relationships](/docs/discord-social-sdk/core-concepts#friend-system-relationships) -* [Presence & Rich Presence](/docs/discord-social-sdk/core-concepts#presence-rich-presence) - -The Social SDK provides the helper method [`Client::GetDefaultPresenceScopes`], which returns `openid sdk.social_layer_presence`, -that you can use when setting up your OAuth2 flow, for integrations that only need the above functionality. - -:::warn -With only the default presence scopes, your game will not be able to use any of the limited access -communications features. -::: - -### Default Communication Scopes - -The communications features are currently available but have limited access. Those features **require** the scope -of `sdk.social_layer`, which includes the `sdk.social_layer_presence` scope but also allows your app to use those limited features on behalf of the user. - -- `openid` -- `sdk.social_layer` - -These communication features include: -* [Messaging & Communication](/docs/discord-social-sdk/core-concepts#messaging-communication) -* [Lobbies & In-Game Chat](/docs/discord-social-sdk/core-concepts#lobbies-ingame-chat) -* [Linked Channels](/docs/discord-social-sdk/core-concepts#linked-channels) - -The Social SDK provides the helper method [`Client::GetDefaultCommunicationScopes`], which returns `openid sdk.social_layer`, -that you can use when setting up your OAuth2 flow, for integrations that integrates both the default and limited communications features. - -:::preview -For more information about these features, please see [Core Concepts: Limited Access Features](/docs/discord-social-sdk/core-concepts#limited-access-features). -::: - -If your game requires additional scopes, you can add them to the default scopes to authorize additional access from your users. - -You should only add scopes that are necessary for your game to function. Requesting unnecessary scopes can lead to user distrust and may result in users not linking their Discord account. - -See [available OAuth2 scopes](/docs/topics/oauth2#shared-resources-oauth2-scopes) available with the Discord API. - -### OAuth2 Client Types - -OAuth2 has two client types: **Public** and **Confidential**. Most games will not want to ship with **Public Client** enabled. - -Some Social SDK methods require your Discord application to be a **Public Client**. These methods also have server-side alternatives that you can use with a **Confidential Client**. - -- Public clients cannot securely store client secrets. -- Using confidential clients with proper secret management for production applications is generally recommended. -- Your security team should review this setting and authentication flows before releasing your game. - -[Learn more about OAuth2 client types](https://oauth.net/2/client-types) - ---- - -## Core Features - -The Discord Social SDK offers a range of features to enhance social interactions within games. Developers can leverage these features to create a more engaging and connected experience for players in their game. - -### Account Linking - -Account linking allows a game to authenticate users with their Discord credentials, gaining access to social features like friends, chat, and presence. This process uses OAuth2 authentication. - -| Development Guides | -|----------------------------------------------------------------------------------------------------------| -| [Account Linking with Discord](/docs/discord-social-sdk/development-guides/account-linking-with-discord) | -| [Account Linking on Consoles](/docs/discord-social-sdk/development-guides/account-linking-on-consoles) | - -| Design Guidelines | -|----------------------------------------------------------------------------------| -| [Signing in with Discord](/docs/discord-social-sdk/design-guidelines/signing-in) | -| [Consoles](/docs/discord-social-sdk/design-guidelines/consoles) | - -### Provisional Accounts - -Provisional accounts let players use social features in your game without linking a Discord account so all players can have a consistent gameplay experience. - -| Development Guides | -|------------------------------------------------------------------------------------------------------| -| [Using Provisional Accounts](/docs/discord-social-sdk/development-guides/using-provisional-accounts) | - -| Design Guidelines | -|-----------------------------------------------------------------------------------------| -| [Provisional Accounts](/docs/discord-social-sdk/design-guidelines/provisional-accounts) | - -### Friend System & Relationships - -The SDK models friendships and relationships in two ways: - -- Discord Friends: Persistent across all games. -- Game-Specific Friends: Limited to the current game. - -| Development Guides | -|----------------------------------------------------------------------------------------------------------------| -| [Creating a Unified Friends List](/docs/discord-social-sdk/development-guides/creating-a-unified-friends-list) | - -| Design Guidelines | -|-----------------------------------------------------------------------------------------| -| [Unified Friends List](/docs/discord-social-sdk/design-guidelines/provisional-accounts) | -| [Game Friends](/docs/discord-social-sdk/design-guidelines/game-friends) | - -### Messaging & Communication - -Users can communicate via direct messages (DMs) and voice calls: - -- DMs: One-on-one private chat ([`MessageHandle`]). -- Calls: Real-time voice communication inside a game lobby ([`Call`]). - -| Development Guides | -|------------------------------------------------------------------------------------------------| -| [Sending Direct Messages](/docs/discord-social-sdk/development-guides/sending-direct-messages) | -| [Managing Voice Chat](/docs/discord-social-sdk/development-guides/managing-voice-chat) | - -| Design Guidelines | -|-------------------------------------------------------------------------------| -| [Direct Messages](/docs/discord-social-sdk/design-guidelines/direct-messages) | - -### Presence & Rich Presence - -Presence refers to a user's online status, while Rich Presence provides game-specific activity data: - -- Displays if a user is online, idle, or offline. -- Shows detailed game stats (e.g., what level they're playing and time played). -- Allows users to send game invites through Discord and in-game. - -| Development Guides | -|--------------------------------------------------------------------------------------------| -| [Setting Rich Presence](/docs/discord-social-sdk/development-guides/setting-rich-presence) | - -| Design Guidelines | -|-------------------------------------------------------------------------------------------| -| [Status & Rich Presence](/docs/discord-social-sdk/design-guidelines/status-rich-presence) | - -### Lobbies & In-Game Chat - -A lobby is a virtual space where players can interact through voice and text chat. - -- Your game controls lobbies, which can have different membership rules. -- Integrated voice chat allows real-time communication among players in a session. - -| Development Guides | -|---------------------------------------------------------------------------------| -| [Manging Lobbies](/docs/discord-social-sdk/development-guides/managing-lobbies) | - -### Linked Channels - -Games can link in-game chat with Discord's server-based text channels in their UI, allowing players to chat in a Discord server without leaving the game. - -| Development Guides | -|--------------------------------------------------------------------------------| -| [Linked channels](/docs/discord-social-sdk/development-guides/linked-channels) | - -| Design Guidelines | -|-------------------------------------------------------------------------------| -| [Linked channels](/docs/discord-social-sdk/design-guidelines/linked-channels) | + + + Explore social features like account linking, friends, and rich presence. + + + Learn about messaging, voice chat, and in-game lobbies. + + + Learn about the integration overview and implementation steps. + + + See supported platforms and download information. + + + Understand OAuth2 scopes and client types for authentication. + + --- -## SDK Best Practices & Design Guidelines +## Next Steps -### Best Practices +After exploring these core concepts, you can start implementing the Discord Social SDK in your game: -- Optimize your authentication flow: Minimize disruptions during sign-in. -- Use event-driven updates: Listen for SDK status changes to ensure a responsive UI. -- Respect user privacy: Never send friend requests or messages without user consent. -- Design intuitive UI/UX: Ensure social features blend seamlessly with the gameplay. - -### Design Guidelines - -Check out the [Discord Social SDK Design Guidelines](/docs/discord-social-sdk/design-guidelines) for more best practices and common integration scenarios. - ---- - -## SDK & API Reference - -### Discord Social SDK - -Check out the full [Discord Social SDK Reference](https://discord.com/developers/docs/social-sdk/index.html) for reference details. - -For development guides on implementing specific features, refer to the [Discord Social SDK Development Guides](/docs/discord-social-sdk/development-guides). - -### Discord HTTP API - -When working with the Discord HTTP API directly from your game backend, developers can use the [Discord API Reference](/docs/reference) to see available endpoints and methods. - -Learn more about [Using the Discord HTTP API](/docs/discord-social-sdk/development-guides/using-with-discord-apis) with the Discord Social SDK. +- **Ready to integrate?** Follow our [Getting Started](/docs/discord-social-sdk/getting-started) guide for step-by-step setup instructions. +- **Need implementation details?** Check out the [Development Guides](/docs/discord-social-sdk/development-guides) for specific feature implementations. +- **Looking for UI guidance?** Review the [Design Guidelines](/docs/discord-social-sdk/design-guidelines) for best practices. --- ## Change Log -| Date | Changes | -|----------------|--------------------------| -| June 30, 2025 | restructure oauth scopes | -| March 17, 2025 | initial release | - -{/* Autogenerated Reference Links */} -[`AuthorizationArgs`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1AuthorizationArgs.html#adb47ac55258db29d4cb8a2c506093eed -[`AuthorizationArgs::SetScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1AuthorizationArgs.html#aa3714d11a196e0d71c8c1cf38c506d92 -[`Call`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Call.html#a1cc8a7f73c15a960bc409d734b5edbd1 -[`Client`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a91716140c699d8ef0bdf6bfd7ee0ae13 -[`Client::Authorize`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#ace94a58e27545a933d79db32b387a468 -[`Client::GetDefaultCommunicationScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a71499da752fbdc2d4326ae0fd36c0dd1 -[`Client::GetDefaultPresenceScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a7648bd1d2f7d9a86ebd0edb8bef12b5c -[`Client::GetProvisionalToken`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a8003130b6c46e54ac68442483bf0480c -[`MessageHandle`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1MessageHandle.html#ae25595b43bc74b0c4c92c5165d16382f \ No newline at end of file +| Date | Changes | +|----------------|---------------------------| +| July 21, 2025 | restructure core concepts | +| June 30, 2025 | restructure oauth scopes | +| March 17, 2025 | initial release | \ No newline at end of file diff --git a/docs/discord-social-sdk/core-concepts/communication-features.mdx b/docs/discord-social-sdk/core-concepts/communication-features.mdx new file mode 100644 index 0000000000..8cccc74ca4 --- /dev/null +++ b/docs/discord-social-sdk/core-concepts/communication-features.mdx @@ -0,0 +1,94 @@ +--- +sidebar_label: Communication Features +--- + +[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > [Core Concepts](/docs/discord-social-sdk/core-concepts) > {sidebar_label} + +# Communication Features + +The Discord Social SDK provides powerful communication features to enhance player interaction in your game. +These features include messaging, voice chat, and in-game lobbies, allowing players to connect seamlessly. + +## Limited Access + +The following communication features are available to be used, but are only fully unlocked when joining the closed beta. + +:::preview +To apply for full access to closed beta features or to reach out to Discord directly to discuss your game, please fill out [this form](https://discord.com/developers/social-sdk-closed-beta-access-request-form). +::: + +Without full access, these features are available for development and testing, but they are not suitable for a +production environments as their usage is capped with a rate limit. Please read our +[documentation on rate limits](/docs/topics/rate-limits) to learn more. + +## Messaging & Communication + +Users can communicate via direct messages (DMs) and voice calls: + +- DMs: One-on-one private chat ([`MessageHandle`]). +- Calls: Real-time voice communication inside a game lobby ([`Call`]). + +| Development Guides | +|------------------------------------------------------------------------------------------------| +| [Sending Direct Messages](/docs/discord-social-sdk/development-guides/sending-direct-messages) | +| [Managing Voice Chat](/docs/discord-social-sdk/development-guides/managing-voice-chat) | + +| Design Guidelines | +|-------------------------------------------------------------------------------| +| [Direct Messages](/docs/discord-social-sdk/design-guidelines/direct-messages) | + +## Lobbies & In-Game Chat + +A lobby is a virtual space where players can interact through voice and text chat. + +- Your game controls lobbies, which can have different membership rules. +- Integrated voice chat allows real-time communication among players in a session. + +| Development Guides | +|---------------------------------------------------------------------------------| +| [Manging Lobbies](/docs/discord-social-sdk/development-guides/managing-lobbies) | + +## Linked Channels + +Games can link in-game chat with Discord's server-based text channels in their UI, allowing players to chat in a Discord server without leaving the game. + +| Development Guides | +|--------------------------------------------------------------------------------| +| [Linked channels](/docs/discord-social-sdk/development-guides/linked-channels) | + +| Design Guidelines | +|-------------------------------------------------------------------------------| +| [Linked channels](/docs/discord-social-sdk/design-guidelines/linked-channels) | + +--- + +## Next Steps + +Learn about integration steps, check platform support, and explore implementation guides: + + + + Learn about the integration overview and implementation steps. + + + See supported platforms and download information. + + + Learn how to implement messaging, voice chat, and linked channels. + + + +--- + +## Change Log + +| Date | Changes | +|---------------|-----------------| +| July 21, 2025 | initial release | + + +{/* Autogenerated Reference Links */} +[`Call`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Call.html#a1cc8a7f73c15a960bc409d734b5edbd1 +[`MessageHandle`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1MessageHandle.html#ae25595b43bc74b0c4c92c5165d16382f \ No newline at end of file diff --git a/docs/discord-social-sdk/core-concepts/core-features.mdx b/docs/discord-social-sdk/core-concepts/core-features.mdx new file mode 100644 index 0000000000..3f55af3497 --- /dev/null +++ b/docs/discord-social-sdk/core-concepts/core-features.mdx @@ -0,0 +1,96 @@ +--- +sidebar_label: Core Features +--- + +[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > [Core Concepts](/docs/discord-social-sdk/core-concepts) > {sidebar_label} + +# Core Features + +The Discord Social SDK offers a range of features to enhance social interactions within games. Developers can leverage these features to create a more engaging and connected experience for players in their game. + +## Account Linking + +Account linking allows a game to authenticate users with their Discord credentials, gaining access to social features like friends, chat, and presence. This process uses OAuth2 authentication. + +| Development Guides | +|----------------------------------------------------------------------------------------------------------| +| [Account Linking with Discord](/docs/discord-social-sdk/development-guides/account-linking-with-discord) | +| [Account Linking on Consoles](/docs/discord-social-sdk/development-guides/account-linking-on-consoles) | + +| Design Guidelines | +|----------------------------------------------------------------------------------| +| [Signing in with Discord](/docs/discord-social-sdk/design-guidelines/signing-in) | +| [Consoles](/docs/discord-social-sdk/design-guidelines/consoles) | + +## Provisional Accounts + +Provisional accounts let players use social features in your game without linking a Discord account so all players can have a consistent gameplay experience. + +| Development Guides | +|------------------------------------------------------------------------------------------------------| +| [Using Provisional Accounts](/docs/discord-social-sdk/development-guides/using-provisional-accounts) | + +| Design Guidelines | +|-----------------------------------------------------------------------------------------| +| [Provisional Accounts](/docs/discord-social-sdk/design-guidelines/provisional-accounts) | + +## Friend System & Relationships + +The SDK models friendships and relationships in two ways: + +- Discord Friends: Persistent across all games. +- Game-Specific Friends: Limited to the current game. + +| Development Guides | +|----------------------------------------------------------------------------------------------------------------| +| [Creating a Unified Friends List](/docs/discord-social-sdk/development-guides/creating-a-unified-friends-list) | + +| Design Guidelines | +|-----------------------------------------------------------------------------------------| +| [Unified Friends List](/docs/discord-social-sdk/design-guidelines/provisional-accounts) | +| [Game Friends](/docs/discord-social-sdk/design-guidelines/game-friends) | + +## Presence & Rich Presence + +Presence refers to a user's online status, while Rich Presence provides game-specific activity data: + +- Displays if a user is online, idle, or offline. +- Shows detailed game stats (e.g., what level they're playing and time played). +- Allows users to send game invites through Discord and in-game. + +| Development Guides | +|--------------------------------------------------------------------------------------------| +| [Setting Rich Presence](/docs/discord-social-sdk/development-guides/setting-rich-presence) | + +| Design Guidelines | +|-------------------------------------------------------------------------------------------| +| [Status & Rich Presence](/docs/discord-social-sdk/design-guidelines/status-rich-presence) | + + +--- + +## Next Steps + +Learn the implementation steps, configure authentication, and explore development guides: + + + + Learn about messaging, voice chat, and in-game lobbies. + + + Learn about the integration overview and implementation steps. + + + Step-by-step guides for implementing each social feature. + + + +--- + +## Change Log + +| Date | Changes | +|---------------|-----------------| +| July 21, 2025 | initial release | diff --git a/docs/discord-social-sdk/core-concepts/integration-overview.mdx b/docs/discord-social-sdk/core-concepts/integration-overview.mdx new file mode 100644 index 0000000000..5b1b25ba95 --- /dev/null +++ b/docs/discord-social-sdk/core-concepts/integration-overview.mdx @@ -0,0 +1,60 @@ +--- +sidebar_label: Integration Overview +--- + +[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > [Core Concepts](/docs/discord-social-sdk/core-concepts) > {sidebar_label} + +# Integration Overview + +To implement the Discord Social SDK, developers for all platforms will generally follow these steps: + +1. Import the SDK +2. Initialize the SDK: + - Create a [`Client`] instance. + - Set up event listeners to monitor SDK events and callbacks +3. Authenticate users with flexible account options + - Link an existing Discord account via OAuth ([`Client::Authorize`]). + - Create and manage provisional accounts for users who don't have or want a Discord account ([`Client::GetProvisionalToken`]). +4. Implement social features + - Implement [unified friends list](/docs/discord-social-sdk/development-guides/creating-a-unified-friends-list) and [relationships](/docs/discord-social-sdk/development-guides/managing-relationships). + - Use [rich presence](/docs/discord-social-sdk/development-guides/setting-rich-presence) for game activity updates. + - Set up [lobbies](/docs/discord-social-sdk/development-guides/managing-lobbies) for multiplayer interaction and [game invites](/docs/discord-social-sdk/development-guides/managing-game-invites). + - Manage [direct message](/docs/discord-social-sdk/development-guides/sending-direct-messages), [linked channels](/docs/discord-social-sdk/development-guides/creating-a-unified-friends-list), and [voice communication](/docs/discord-social-sdk/development-guides/managing-voice-chat). +5. Handle events & API calls: + - Listen for changes in friend lists, presence updates, and chat messages. + - Use Discord's APIs to update statuses, send messages, and manage connections. + +This guide is a conceptual overview. If you're ready to start building, [follow our step-by-step guide](/docs/discord-social-sdk/getting-started) to set up the SDK in your game engine. + +--- + +## Next Steps + +Check platform compatibility, explore communication features, and start your integration: + + + + See supported platforms and download information. + + + Learn about messaging, voice chat, and in-game lobbies. + + + Choose your platform and follow step-by-step setup instructions. + + + +--- + +## Change Log + +| Date | Changes | +|---------------|-----------------| +| July 21, 2025 | initial release | + +{/* Autogenerated Reference Links */} +[`Client`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a91716140c699d8ef0bdf6bfd7ee0ae13 +[`Client::Authorize`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#ace94a58e27545a933d79db32b387a468 +[`Client::GetProvisionalToken`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a8003130b6c46e54ac68442483bf0480c \ No newline at end of file diff --git a/docs/discord-social-sdk/core-concepts/oauth2-scopes.mdx b/docs/discord-social-sdk/core-concepts/oauth2-scopes.mdx new file mode 100644 index 0000000000..32a45f30c1 --- /dev/null +++ b/docs/discord-social-sdk/core-concepts/oauth2-scopes.mdx @@ -0,0 +1,107 @@ +--- +sidebar_label: OAuth2 Scopes +--- + +[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > [Core Concepts](/docs/discord-social-sdk/core-concepts) > {sidebar_label} + +# OAuth2 Scopes + +OAuth2 scopes define the level of access your app has to a user's Discord account + +What OAuth scopes are available to your integration are set via +[`AuthorizationArgs::SetScopes`] on [`AuthorizationArgs`] which is passed to [`Client::Authorize`] on Social SDK +authentication. + +## Default Presence Scopes + +At a minimum, the Social SDK uses the following scopes to use features like rich presence and friends list: + +- `openid` +- `sdk.social_layer_presence` + +The default presence features include: + +* [Account Linking](/docs/discord-social-sdk/core-concepts/core-features#account-linking) +* [Provisional Accounts](/docs/discord-social-sdk/core-concepts/core-features#provisional-accounts) +* [Friend System & Relationships](/docs/discord-social-sdk/core-concepts/core-features#friend-system-relationships) +* [Presence & Rich Presence](/docs/discord-social-sdk/core-concepts/core-features#presence-rich-presence) + +The Social SDK provides the helper method [`Client::GetDefaultPresenceScopes`], which returns `openid sdk.social_layer_presence`, +that you can use when setting up your OAuth2 flow, for integrations that only need the above functionality. + +:::warn +With only the default presence scopes, your game will not be able to use any of the limited access +communications features. +::: + +## Default Communication Scopes + +The communications features are currently available but have limited access. Those features **require** the scope +of `sdk.social_layer`, which includes the `sdk.social_layer_presence` scope but also allows your app to use those limited features on behalf of the user. + +- `openid` +- `sdk.social_layer` + +These communication features include: +* [Messaging & Communication](/docs/discord-social-sdk/core-concepts/communication-features#messaging-communication) +* [Lobbies & In-Game Chat](/docs/discord-social-sdk/core-concepts/communication-features#lobbies-ingame-chat) +* [Linked Channels](/docs/discord-social-sdk/core-concepts/communication-features#linked-channels) + +The Social SDK provides the helper method [`Client::GetDefaultCommunicationScopes`], which returns `openid sdk.social_layer`, +that you can use when setting up your OAuth2 flow, for integrations that integrates both the default and limited communications features. + +:::preview +For more information about these features, please see [Core Concepts: Communication Features](/docs/discord-social-sdk/core-concepts/communication-features). +::: + +If your game requires additional scopes, you can add them to the default scopes to authorize additional access from your users. + +You should only add scopes that are necessary for your game to function. Requesting unnecessary scopes can lead to user distrust and may result in users not linking their Discord account. + +See [available OAuth2 scopes](/docs/topics/oauth2#shared-resources-oauth2-scopes) available with the Discord API. + +## OAuth2 Client Types + +OAuth2 has two client types: **Public** and **Confidential**. Most games will not want to ship with **Public Client** enabled. + +Some Social SDK methods require your Discord application to be a **Public Client**. These methods also have server-side alternatives that you can use with a **Confidential Client**. + +- Public clients cannot securely store client secrets. +- Using confidential clients with proper secret management for production applications is generally recommended. +- Your security team should review this setting and authentication flows before releasing your game. + +[Learn more about OAuth2 client types](https://oauth.net/2/client-types) + +--- + +## Next Steps + +Start your integration, implement user authentication, and learn about UI design: + + + + Choose your platform and follow step-by-step setup instructions. + + + Implement user authentication with Discord OAuth2. + + + Learn how to design your game's UI to integrate social features. + + + +--- + +## Change Log + +| Date | Changes | +|---------------|-----------------| +| July 21, 2025 | initial release | + +{/* Autogenerated Reference Links */} +[`AuthorizationArgs`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1AuthorizationArgs.html#adb47ac55258db29d4cb8a2c506093eed +[`AuthorizationArgs::SetScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1AuthorizationArgs.html#aa3714d11a196e0d71c8c1cf38c506d92 +[`Client::Authorize`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#ace94a58e27545a933d79db32b387a468 +[`Client::GetDefaultCommunicationScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a71499da752fbdc2d4326ae0fd36c0dd1 +[`Client::GetDefaultPresenceScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a7648bd1d2f7d9a86ebd0edb8bef12b5c \ No newline at end of file diff --git a/docs/discord-social-sdk/core-concepts/platform-compatibility.mdx b/docs/discord-social-sdk/core-concepts/platform-compatibility.mdx new file mode 100644 index 0000000000..cd0006cc99 --- /dev/null +++ b/docs/discord-social-sdk/core-concepts/platform-compatibility.mdx @@ -0,0 +1,64 @@ +--- +sidebar_label: Platform Compatibility +--- +import ConsoleAccess from '../partials/callouts/console-access.mdx'; + +[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > [Core Concepts](/docs/discord-social-sdk/core-concepts) > {sidebar_label} + +# Platform Compatibility + +:::info +You can find instructions on how to download the SDK for each platform in the [Getting Started](/docs/discord-social-sdk/getting-started) guide. +::: + +The Discord Social SDK is available for the following platforms: + +## Desktop + +- Standalone C++ (Windows and macOS) +- Unreal Engine (Windows Only) +- Unity (Windows and macOS) + +## Android/iOS (full mobile support & guides coming soon) + +- Standalone C++ +- Unity + +## Console (full console support & guides coming soon) + +- **Xbox Series X|S and Xbox One** + - Standalone C++ + - Unreal Engine + - Unity +- **PlayStation5 and PlayStation4** + - Standalone C++ + - Unreal Engine + - Unity + + + +--- + +## Next Steps + +Configure authentication, explore features, and get started with setup: + + + + Understand OAuth2 scopes and client types for authentication. + + + Explore social features like account linking, friends, and rich presence. + + + Platform-specific setup instructions and download links. + + + +--- + +## Change Log + +| Date | Changes | +|---------------|-----------------| +| July 21, 2025 | initial release | diff --git a/docs/discord-social-sdk/getting-started.mdx b/docs/discord-social-sdk/getting-started.mdx index 386d808169..a07acc1858 100644 --- a/docs/discord-social-sdk/getting-started.mdx +++ b/docs/discord-social-sdk/getting-started.mdx @@ -33,7 +33,7 @@ If you are unsure which platform to choose, we recommend starting with the C++ g :::info -To see a complete list of currently compatible platforms, check out our [Platform Compatibility](/docs/discord-social-sdk/core-concepts#sdk-platform-compatibility) section. +To see a complete list of currently compatible platforms, check out our [Platform Compatibility](/docs/discord-social-sdk/core-concepts/platform-compatibility) section. ::: --- diff --git a/docs/discord-social-sdk/getting-started/partials/getting-started.mdx b/docs/discord-social-sdk/getting-started/partials/getting-started.mdx index 6f2dc6925a..07806bc4ab 100644 --- a/docs/discord-social-sdk/getting-started/partials/getting-started.mdx +++ b/docs/discord-social-sdk/getting-started/partials/getting-started.mdx @@ -19,7 +19,7 @@ Later, you can invite your team members to your new team to collaborate on your 4. Enable the `Public Client` toggle in the `OAuth2` tab. :::warn -**Note:** This guide requires enabling **Public Client** to allow you to get started with the SDK quickly. Most games will not want to ship as a public client. This setting should be reviewed by your team prior to releasing your game. [Learn more about public clients](/docs/discord-social-sdk/core-concepts#oauth2-client-types). +**Note:** This guide requires enabling **Public Client** to allow you to get started with the SDK quickly. Most games will not want to ship as a public client. This setting should be reviewed by your team prior to releasing your game. [Learn more about public clients](/docs/discord-social-sdk/core-concepts/oauth2-scopes#oauth2-client-types). ::: --- diff --git a/docs/discord-social-sdk/overview.mdx b/docs/discord-social-sdk/overview.mdx index 6b376f9b85..57304a9c9b 100644 --- a/docs/discord-social-sdk/overview.mdx +++ b/docs/discord-social-sdk/overview.mdx @@ -43,7 +43,7 @@ Start integrating the SDK into your game with our getting started guides, design Discord Social SDK features for text and voice communication are available but have limited access. :::preview -For more information on how to access these features, please see [Core Concepts: Limited Access Features](/docs/discord-social-sdk/core-concepts#limited-access-features). +For more information on how to access these features, please see [Core Concepts: Communication Features](/docs/discord-social-sdk/core-concepts/communication-features). ::: --- diff --git a/docs/discord-social-sdk/partials/callouts/limited-access.mdx b/docs/discord-social-sdk/partials/callouts/limited-access.mdx index 5d08228a0b..1d7ae843d2 100644 --- a/docs/discord-social-sdk/partials/callouts/limited-access.mdx +++ b/docs/discord-social-sdk/partials/callouts/limited-access.mdx @@ -1,3 +1,6 @@ :::preview -This feature is currently available with [limited access](/docs/discord-social-sdk/core-concepts#limited-access-features). To apply for full access to closed beta features, or to reach out to Discord directly to discuss your game, please fill out [this form](https://discord.com/developers/social-sdk-closed-beta-access-request-form). +This feature is currently available with +[limited access](/docs/discord-social-sdk/core-concepts/communication-features#limited-access). To apply for full access +to closed beta features, or to reach out to Discord directly to discuss your game, please fill out +[this form](https://discord.com/developers/social-sdk-closed-beta-access-request-form). ::: \ No newline at end of file diff --git a/docs/discord-social-sdk/partials/callouts/oauth-comms-scopes.mdx b/docs/discord-social-sdk/partials/callouts/oauth-comms-scopes.mdx index 8eda262266..e8d003ea33 100644 --- a/docs/discord-social-sdk/partials/callouts/oauth-comms-scopes.mdx +++ b/docs/discord-social-sdk/partials/callouts/oauth-comms-scopes.mdx @@ -1,6 +1,6 @@ :::warn To utilize this communication feature, you must enable [`Client::GetDefaultCommunicationScopes`] in your OAuth Scope configuration. -See the [OAuth Scopes Core Concepts Guide](/docs/discord-social-sdk/core-concepts#oauth2-scopes) for more details. +See the [OAuth Scopes Core Concepts Guide](/docs/discord-social-sdk/core-concepts/oauth2-scopes) for more details. ::: {/* Autogenerated Reference Links */} diff --git a/docs/discord-social-sdk/partials/callouts/public-client.mdx b/docs/discord-social-sdk/partials/callouts/public-client.mdx index 3c6adebda4..60b5c2c979 100644 --- a/docs/discord-social-sdk/partials/callouts/public-client.mdx +++ b/docs/discord-social-sdk/partials/callouts/public-client.mdx @@ -1,3 +1,3 @@ :::warn -This method requires enabling **Public Client** for your app. Most games will not want to ship with this enabled. [Learn more](/docs/discord-social-sdk/core-concepts#oauth2-client-types) +This method requires enabling **Public Client** for your app. Most games will not want to ship with this enabled. [Learn more](/docs/discord-social-sdk/core-concepts/oauth2-scopes#oauth2-client-types) ::: \ No newline at end of file