Skip to content

Commit b633ef6

Browse files
markmandelmarkmandel
committed
Restructure Discord Social SDK Core Concepts documentation
Split the large core-concepts.mdx file into focused subpages for better navigation and maintainability: - Created core-concepts/core-features.mdx covering account linking, provisional accounts, friend systems, and presence - Created core-concepts/communication-features.mdx for messaging, lobbies, and linked channels - Created core-concepts/integration-overview.mdx with implementation steps and workflow - Created core-concepts/platform-compatibility.mdx with supported platforms and SDK availability - Created core-concepts/oauth2-scopes.mdx covering authentication scopes and client types - Updated main core-concepts.mdx to serve as landing page with overview and navigation cards - Added subpages configuration and proper breadcrumb navigation - Updated change log entries to reflect documentation restructuring
1 parent 881ed83 commit b633ef6

File tree

12 files changed

+468
-295
lines changed

12 files changed

+468
-295
lines changed

‎docs/discord-social-sdk/core-concepts.mdx‎

Lines changed: 38 additions & 289 deletions
Large diffs are not rendered by default.

‎docs/discord-social-sdk/core-concepts/communication-features.mdx‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
sidebar_label: Communication Features
3+
---
4+
5+
[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > [Core Concepts](/docs/discord-social-sdk/core-concepts) > {sidebar_label}
6+
7+
# Communication Features
8+
9+
The Discord Social SDK provides powerful communication features to enhance player interaction in your game.
10+
These features include messaging, voice chat, and in-game lobbies, allowing players to connect seamlessly.
11+
12+
## Limited Access
13+
14+
The following communication features are available to be used, but are only fully unlocked when joining the closed beta.
15+
16+
:::preview
17+
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).
18+
:::
19+
20+
Without full access, these features are available for development and testing, but they are not suitable for a
21+
production environments as their usage is capped with a rate limit. Please read our
22+
[documentation on rate limits](/docs/topics/rate-limits) to learn more.
23+
24+
## Messaging & Communication
25+
26+
Users can communicate via direct messages (DMs) and voice calls:
27+
28+
- DMs: One-on-one private chat ([`MessageHandle`]).
29+
- Calls: Real-time voice communication inside a game lobby ([`Call`]).
30+
31+
| Development Guides |
32+
|------------------------------------------------------------------------------------------------|
33+
| [Sending Direct Messages](/docs/discord-social-sdk/development-guides/sending-direct-messages) |
34+
| [Managing Voice Chat](/docs/discord-social-sdk/development-guides/managing-voice-chat) |
35+
36+
| Design Guidelines |
37+
|-------------------------------------------------------------------------------|
38+
| [Direct Messages](/docs/discord-social-sdk/design-guidelines/direct-messages) |
39+
40+
## Lobbies & In-Game Chat
41+
42+
A lobby is a virtual space where players can interact through voice and text chat.
43+
44+
- Your game controls lobbies, which can have different membership rules.
45+
- Integrated voice chat allows real-time communication among players in a session.
46+
47+
| Development Guides |
48+
|---------------------------------------------------------------------------------|
49+
| [Manging Lobbies](/docs/discord-social-sdk/development-guides/managing-lobbies) |
50+
51+
## Linked Channels
52+
53+
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.
54+
55+
| Development Guides |
56+
|--------------------------------------------------------------------------------|
57+
| [Linked channels](/docs/discord-social-sdk/development-guides/linked-channels) |
58+
59+
| Design Guidelines |
60+
|-------------------------------------------------------------------------------|
61+
| [Linked channels](/docs/discord-social-sdk/design-guidelines/linked-channels) |
62+
63+
---
64+
65+
## Next Steps
66+
67+
Learn about integration steps, check platform support, and explore implementation guides:
68+
69+
<Container>
70+
<Card title="Integration Overview"
71+
link="/docs/discord-social-sdk/core-concepts/integration-overview" icon="HammerIcon">
72+
Learn about the integration overview and implementation steps.
73+
</Card>
74+
<Card title="Platform Compatibility" link="/docs/discord-social-sdk/core-concepts/platform-compatibility"
75+
icon="UserPlatformIcon">
76+
See supported platforms and download information.
77+
</Card>
78+
<Card title="Development Guides" link="/docs/discord-social-sdk/development-guides" icon="BookCheckIcon">
79+
Learn how to implement messaging, voice chat, and linked channels.
80+
</Card>
81+
</Container>
82+
83+
---
84+
85+
## Change Log
86+
87+
| Date | Changes |
88+
|---------------|-----------------|
89+
| July 21, 2025 | initial release |
90+
91+
92+
{/* Autogenerated Reference Links */}
93+
[`Call`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Call.html#a1cc8a7f73c15a960bc409d734b5edbd1
94+
[`MessageHandle`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1MessageHandle.html#ae25595b43bc74b0c4c92c5165d16382f

‎docs/discord-social-sdk/core-concepts/core-features.mdx‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
sidebar_label: Core Features
3+
---
4+
5+
[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > [Core Concepts](/docs/discord-social-sdk/core-concepts) > {sidebar_label}
6+
7+
# Core Features
8+
9+
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.
10+
11+
## Account Linking
12+
13+
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.
14+
15+
| Development Guides |
16+
|----------------------------------------------------------------------------------------------------------|
17+
| [Account Linking with Discord](/docs/discord-social-sdk/development-guides/account-linking-with-discord) |
18+
| [Account Linking on Consoles](/docs/discord-social-sdk/development-guides/account-linking-on-consoles) |
19+
20+
| Design Guidelines |
21+
|----------------------------------------------------------------------------------|
22+
| [Signing in with Discord](/docs/discord-social-sdk/design-guidelines/signing-in) |
23+
| [Consoles](/docs/discord-social-sdk/design-guidelines/consoles) |
24+
25+
## Provisional Accounts
26+
27+
Provisional accounts let players use social features in your game without linking a Discord account so all players can have a consistent gameplay experience.
28+
29+
| Development Guides |
30+
|------------------------------------------------------------------------------------------------------|
31+
| [Using Provisional Accounts](/docs/discord-social-sdk/development-guides/using-provisional-accounts) |
32+
33+
| Design Guidelines |
34+
|-----------------------------------------------------------------------------------------|
35+
| [Provisional Accounts](/docs/discord-social-sdk/design-guidelines/provisional-accounts) |
36+
37+
## Friend System & Relationships
38+
39+
The SDK models friendships and relationships in two ways:
40+
41+
- Discord Friends: Persistent across all games.
42+
- Game-Specific Friends: Limited to the current game.
43+
44+
| Development Guides |
45+
|----------------------------------------------------------------------------------------------------------------|
46+
| [Creating a Unified Friends List](/docs/discord-social-sdk/development-guides/creating-a-unified-friends-list) |
47+
48+
| Design Guidelines |
49+
|-----------------------------------------------------------------------------------------|
50+
| [Unified Friends List](/docs/discord-social-sdk/design-guidelines/provisional-accounts) |
51+
| [Game Friends](/docs/discord-social-sdk/design-guidelines/game-friends) |
52+
53+
## Presence & Rich Presence
54+
55+
Presence refers to a user's online status, while Rich Presence provides game-specific activity data:
56+
57+
- Displays if a user is online, idle, or offline.
58+
- Shows detailed game stats (e.g., what level they're playing and time played).
59+
- Allows users to send game invites through Discord and in-game.
60+
61+
| Development Guides |
62+
|--------------------------------------------------------------------------------------------|
63+
| [Setting Rich Presence](/docs/discord-social-sdk/development-guides/setting-rich-presence) |
64+
65+
| Design Guidelines |
66+
|-------------------------------------------------------------------------------------------|
67+
| [Status & Rich Presence](/docs/discord-social-sdk/design-guidelines/status-rich-presence) |
68+
69+
70+
---
71+
72+
## Next Steps
73+
74+
Learn the implementation steps, configure authentication, and explore development guides:
75+
76+
<Container>
77+
<Card title="Communication Features" link="/docs/discord-social-sdk/core-concepts/communication-features"
78+
icon="PhoneCallIcon">
79+
Learn about messaging, voice chat, and in-game lobbies.
80+
</Card>
81+
<Card title="Integration Overview"
82+
link="/docs/discord-social-sdk/core-concepts/integration-overview" icon="HammerIcon">
83+
Learn about the integration overview and implementation steps.
84+
</Card>
85+
<Card title="Development Guides" link="/docs/discord-social-sdk/development-guides" icon="BookCheckIcon">
86+
Step-by-step guides for implementing each social feature.
87+
</Card>
88+
</Container>
89+
90+
---
91+
92+
## Change Log
93+
94+
| Date | Changes |
95+
|---------------|-----------------|
96+
| July 21, 2025 | initial release |

‎docs/discord-social-sdk/core-concepts/integration-overview.mdx‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
sidebar_label: Integration Overview
3+
---
4+
5+
[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > [Core Concepts](/docs/discord-social-sdk/core-concepts) > {sidebar_label}
6+
7+
# Integration Overview
8+
9+
To implement the Discord Social SDK, developers for all platforms will generally follow these steps:
10+
11+
1. Import the SDK
12+
2. Initialize the SDK:
13+
- Create a [`Client`] instance.
14+
- Set up event listeners to monitor SDK events and callbacks
15+
3. Authenticate users with flexible account options
16+
- Link an existing Discord account via OAuth ([`Client::Authorize`]).
17+
- Create and manage provisional accounts for users who don't have or want a Discord account ([`Client::GetProvisionalToken`]).
18+
4. Implement social features
19+
- 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).
20+
- Use [rich presence](/docs/discord-social-sdk/development-guides/setting-rich-presence) for game activity updates.
21+
- 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).
22+
- 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).
23+
5. Handle events & API calls:
24+
- Listen for changes in friend lists, presence updates, and chat messages.
25+
- Use Discord's APIs to update statuses, send messages, and manage connections.
26+
27+
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.
28+
29+
---
30+
31+
## Next Steps
32+
33+
Check platform compatibility, explore communication features, and start your integration:
34+
35+
<Container>
36+
<Card title="Platform Compatibility" link="/docs/discord-social-sdk/core-concepts/platform-compatibility"
37+
icon="UserPlatformIcon">
38+
See supported platforms and download information.
39+
</Card>
40+
<Card title="Communication Features" link="/docs/discord-social-sdk/core-concepts/communication-features"
41+
icon="PhoneCallIcon">
42+
Learn about messaging, voice chat, and in-game lobbies.
43+
</Card>
44+
<Card title="Getting Started" link="/docs/discord-social-sdk/getting-started" icon="PlayIcon">
45+
Choose your platform and follow step-by-step setup instructions.
46+
</Card>
47+
</Container>
48+
49+
---
50+
51+
## Change Log
52+
53+
| Date | Changes |
54+
|---------------|-----------------|
55+
| July 21, 2025 | initial release |
56+
57+
{/* Autogenerated Reference Links */}
58+
[`Client`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a91716140c699d8ef0bdf6bfd7ee0ae13
59+
[`Client::Authorize`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#ace94a58e27545a933d79db32b387a468
60+
[`Client::GetProvisionalToken`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a8003130b6c46e54ac68442483bf0480c

‎docs/discord-social-sdk/core-concepts/oauth2-scopes.mdx‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
---
2+
sidebar_label: OAuth2 Scopes
3+
---
4+
5+
[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > [Core Concepts](/docs/discord-social-sdk/core-concepts) > {sidebar_label}
6+
7+
# OAuth2 Scopes
8+
9+
OAuth2 scopes define the level of access your app has to a user's Discord account
10+
11+
What OAuth scopes are available to your integration are set via
12+
[`AuthorizationArgs::SetScopes`] on [`AuthorizationArgs`] which is passed to [`Client::Authorize`] on Social SDK
13+
authentication.
14+
15+
## Default Presence Scopes
16+
17+
At a minimum, the Social SDK uses the following scopes to use features like rich presence and friends list:
18+
19+
- `openid`
20+
- `sdk.social_layer_presence`
21+
22+
The default presence features include:
23+
24+
* [Account Linking](/docs/discord-social-sdk/core-concepts/core-features#account-linking)
25+
* [Provisional Accounts](/docs/discord-social-sdk/core-concepts/core-features#provisional-accounts)
26+
* [Friend System & Relationships](/docs/discord-social-sdk/core-concepts/core-features#friend-system-relationships)
27+
* [Presence & Rich Presence](/docs/discord-social-sdk/core-concepts/core-features#presence-rich-presence)
28+
29+
The Social SDK provides the helper method [`Client::GetDefaultPresenceScopes`], which returns `openid sdk.social_layer_presence`,
30+
that you can use when setting up your OAuth2 flow, for integrations that only need the above functionality.
31+
32+
:::warn
33+
With only the default presence scopes, your game will not be able to use any of the limited access
34+
communications features.
35+
:::
36+
37+
## Default Communication Scopes
38+
39+
The communications features are currently available but have limited access. Those features **require** the scope
40+
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.
41+
42+
- `openid`
43+
- `sdk.social_layer`
44+
45+
These communication features include:
46+
* [Messaging & Communication](/docs/discord-social-sdk/core-concepts/communication-features#messaging-communication)
47+
* [Lobbies & In-Game Chat](/docs/discord-social-sdk/core-concepts/communication-features#lobbies-ingame-chat)
48+
* [Linked Channels](/docs/discord-social-sdk/core-concepts/communication-features#linked-channels)
49+
50+
The Social SDK provides the helper method [`Client::GetDefaultCommunicationScopes`], which returns `openid sdk.social_layer`,
51+
that you can use when setting up your OAuth2 flow, for integrations that integrates both the default and limited communications features.
52+
53+
:::preview
54+
For more information about these features, please see [Core Concepts: Communication Features](/docs/discord-social-sdk/core-concepts/communication-features).
55+
:::
56+
57+
If your game requires additional scopes, you can add them to the default scopes to authorize additional access from your users.
58+
59+
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.
60+
61+
See [available OAuth2 scopes](/docs/topics/oauth2#shared-resources-oauth2-scopes) available with the Discord API.
62+
63+
## OAuth2 Client Types
64+
65+
OAuth2 has two client types: **Public** and **Confidential**. Most games will not want to ship with **Public Client** enabled.
66+
67+
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**.
68+
69+
- Public clients cannot securely store client secrets.
70+
- Using confidential clients with proper secret management for production applications is generally recommended.
71+
- Your security team should review this setting and authentication flows before releasing your game.
72+
73+
[Learn more about OAuth2 client types](https://oauth.net/2/client-types)
74+
75+
---
76+
77+
## Next Steps
78+
79+
Start your integration, implement user authentication, and learn about UI design:
80+
81+
<Container>
82+
<Card title="Getting Started" link="/docs/discord-social-sdk/getting-started" icon="PlayIcon">
83+
Choose your platform and follow step-by-step setup instructions.
84+
</Card>
85+
<Card title="Account Linking" link="/docs/discord-social-sdk/development-guides/account-linking-with-discord"
86+
icon="LinkIcon">
87+
Implement user authentication with Discord OAuth2.
88+
</Card>
89+
<Card title="Design Guidelines" link="/docs/discord-social-sdk/design-guidelines" icon="PaintPaletteIcon">
90+
Learn how to design your game's UI to integrate social features.
91+
</Card>
92+
</Container>
93+
94+
---
95+
96+
## Change Log
97+
98+
| Date | Changes |
99+
|---------------|-----------------|
100+
| July 21, 2025 | initial release |
101+
102+
{/* Autogenerated Reference Links */}
103+
[`AuthorizationArgs`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1AuthorizationArgs.html#adb47ac55258db29d4cb8a2c506093eed
104+
[`AuthorizationArgs::SetScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1AuthorizationArgs.html#aa3714d11a196e0d71c8c1cf38c506d92
105+
[`Client::Authorize`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#ace94a58e27545a933d79db32b387a468
106+
[`Client::GetDefaultCommunicationScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a71499da752fbdc2d4326ae0fd36c0dd1
107+
[`Client::GetDefaultPresenceScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a7648bd1d2f7d9a86ebd0edb8bef12b5c

0 commit comments

Comments
 (0)