Skip to content

Commit 8e93a93

Browse files
markmandelmarkmandel
authored
Social SDK: Add OAuth Communications Scope warnings (#7653)
* Social SDK: Add OAuth Communications Scope warnings Devs keep running into the issue that they aren't aware that to use communication features, they need to enable communication OAuth scopes (mainly because we're not explicit about it anywhere). This aims to fix this! This PR includes: - Reorganize core concepts page to prioritize OAuth scopes - Add implementation details to OAuth guide - Add warnings to guides using Communications features about scope requirements * Review updates.
1 parent 3bd60ee commit 8e93a93

File tree

6 files changed

+125
-66
lines changed

6 files changed

+125
-66
lines changed

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

Lines changed: 81 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,76 @@ The Discord Social SDK is available for the following platforms:
8888

8989
---
9090

91+
## OAuth2 Scopes
92+
93+
OAuth2 scopes define the level of access your app has to a user's Discord account
94+
95+
What OAuth scopes are available to your integration are set via
96+
[`AuthorizationArgs::SetScopes`] on [`AuthorizationArgs`] which is passed to [`Client::Authorize`] on Social SDK
97+
authentication.
98+
99+
### Default Presence Scopes
100+
101+
At a minimum, the Social SDK uses the following scopes to use features like rich presence and friends list:
102+
103+
- `openid`
104+
- `sdk.social_layer_presence`
105+
106+
The default presence features include:
107+
108+
* [Account Linking](/docs/discord-social-sdk/core-concepts#account-linking)
109+
* [Provisional Accounts](/docs/discord-social-sdk/core-concepts#provisional-accounts)
110+
* [Friend System & Relationships](/docs/discord-social-sdk/core-concepts#friend-system-relationships)
111+
* [Presence & Rich Presence](/docs/discord-social-sdk/core-concepts#presence-rich-presence)
112+
113+
The Social SDK provides the helper method [`Client::GetDefaultPresenceScopes`], which returns `openid sdk.social_layer_presence`,
114+
that you can use when setting up your OAuth2 flow, for integrations that only need the above functionality.
115+
116+
:::warn
117+
With only the default presence scopes, your game will not be able to use any of the limited access
118+
communications features.
119+
:::
120+
121+
### Default Communication Scopes
122+
123+
The communications features are currently available but have limited access. Those features **require** the scope
124+
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.
125+
126+
- `openid`
127+
- `sdk.social_layer`
128+
129+
These communication features include:
130+
* [Messaging & Communication](/docs/discord-social-sdk/core-concepts#messaging-communication)
131+
* [Lobbies & In-Game Chat](/docs/discord-social-sdk/core-concepts#lobbies-ingame-chat)
132+
* [Linked Channels](/docs/discord-social-sdk/core-concepts#linked-channels)
133+
134+
The Social SDK provides the helper method [`Client::GetDefaultCommunicationScopes`], which returns `openid sdk.social_layer`,
135+
that you can use when setting up your OAuth2 flow, for integrations that integrates both the default and limited communications features.
136+
137+
:::preview
138+
For more information about these features, please see [Core Concepts: Limited Access Features](/docs/discord-social-sdk/core-concepts#limited-access-features).
139+
:::
140+
141+
If your game requires additional scopes, you can add them to the default scopes to authorize additional access from your users.
142+
143+
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.
144+
145+
See [available OAuth2 scopes](/docs/topics/oauth2#shared-resources-oauth2-scopes) available with the Discord API.
146+
147+
### OAuth2 Client Types
148+
149+
OAuth2 has two client types: **Public** and **Confidential**. Most games will not want to ship with **Public Client** enabled.
150+
151+
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**.
152+
153+
- Public clients cannot securely store client secrets.
154+
- Using confidential clients with proper secret management for production applications is generally recommended.
155+
- Your security team should review this setting and authentication flows before releasing your game.
156+
157+
[Learn more about OAuth2 client types](https://oauth.net/2/client-types)
158+
159+
---
160+
91161
## Core Features
92162

93163
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.
@@ -138,8 +208,8 @@ The SDK models friendships and relationships in two ways:
138208

139209
Users can communicate via direct messages (DMs) and voice calls:
140210

141-
- DMs: One-on-one private chat (`MessageHandle`).
142-
- Calls: Real-time voice communication inside a game lobby (`Call`).
211+
- DMs: One-on-one private chat ([`MessageHandle`]).
212+
- Calls: Real-time voice communication inside a game lobby ([`Call`]).
143213

144214
| Development Guides |
145215
|------------------------------------------------------------------------------------------------|
@@ -200,47 +270,6 @@ Games can link in-game chat with Discord's server-based text channels in their U
200270
- Respect user privacy: Never send friend requests or messages without user consent.
201271
- Design intuitive UI/UX: Ensure social features blend seamlessly with the gameplay.
202272

203-
### OAuth2 Scopes
204-
205-
OAuth2 scopes define the level of access your app has to a user's Discord account.
206-
207-
At a minimum, the Social SDK uses the following scopes to use features like rich presence and friends list:
208-
209-
- `openid`
210-
- `sdk.social_layer_presence`
211-
212-
Some SDK features are currently available but have limited access. Those features require the following 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.
213-
214-
- `openid`
215-
- `sdk.social_layer`
216-
217-
:::preview
218-
For more information about these features, please see [Core Concepts: Limited Access Features](/docs/discord-social-sdk/core-concepts#limited-access-features).
219-
:::
220-
221-
The Social SDK provides two helper methods that you can use when setting up your OAuth2 flow:
222-
223-
- [`Client::GetDefaultPresenceScopes`], which returns "openid sdk.social_layer_presence".
224-
- [`Client::GetDefaultCommunicationScopes`], which returns "openid sdk.social_layer".
225-
226-
If your game requires additional scopes, you can add them to the default scopes to authorize additional access from your users.
227-
228-
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.
229-
230-
See [available OAuth2 scopes](/docs/topics/oauth2#shared-resources-oauth2-scopes) available with the Discord API.
231-
232-
### OAuth2 Client Types
233-
234-
OAuth2 has two client types: **Public** and **Confidential**. Most games will not want to ship with **Public Client** enabled.
235-
236-
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**.
237-
238-
- Public clients cannot securely store client secrets.
239-
- Using confidential clients with proper secret management for production applications is generally recommended.
240-
- Your security team should review this setting and authentication flows before releasing your game.
241-
242-
[Learn more about OAuth2 client types](https://oauth.net/2/client-types)
243-
244273
### Design Guidelines
245274

246275
Check out the [Discord Social SDK Design Guidelines](/docs/discord-social-sdk/design-guidelines) for more best practices and common integration scenarios.
@@ -265,13 +294,18 @@ Learn more about [Using the Discord HTTP API](/docs/discord-social-sdk/developme
265294

266295
## Change Log
267296

268-
| Date | Changes |
269-
|----------------|-----------------|
270-
| March 17, 2025 | initial release |
297+
| Date | Changes |
298+
|----------------|--------------------------|
299+
| June 30, 2025 | restructure oauth scopes |
300+
| March 17, 2025 | initial release |
271301

272302
{/* Autogenerated Reference Links */}
303+
[`AuthorizationArgs`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1AuthorizationArgs.html#adb47ac55258db29d4cb8a2c506093eed
304+
[`AuthorizationArgs::SetScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1AuthorizationArgs.html#aa3714d11a196e0d71c8c1cf38c506d92
305+
[`Call`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Call.html#a1cc8a7f73c15a960bc409d734b5edbd1
273306
[`Client`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a91716140c699d8ef0bdf6bfd7ee0ae13
274307
[`Client::Authorize`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#ace94a58e27545a933d79db32b387a468
275308
[`Client::GetDefaultCommunicationScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a71499da752fbdc2d4326ae0fd36c0dd1
276309
[`Client::GetDefaultPresenceScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a7648bd1d2f7d9a86ebd0edb8bef12b5c
277-
[`Client::GetProvisionalToken`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a8003130b6c46e54ac68442483bf0480c
310+
[`Client::GetProvisionalToken`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a8003130b6c46e54ac68442483bf0480c
311+
[`MessageHandle`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1MessageHandle.html#ae25595b43bc74b0c4c92c5165d16382f

‎docs/discord-social-sdk/development-guides/linked-channels.mdx

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
sidebar_label: Linked Channels
33
---
44
import LimitedAccessCallout from '../partials/callouts/limited-access.mdx';
5-
import PublicClient from '../partials/callouts/public-client.mdx';
65
import SupportCallout from '../partials/callouts/support.mdx';
6+
import CommsScopeWarning from '../partials/callouts/oauth-comms-scopes.mdx';
77

88
[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > [Development Guides](/docs/discord-social-sdk/development-guides) > {sidebar_label}
99

@@ -27,6 +27,8 @@ Before implementing Linked Channels, make sure you have:
2727
- [Set up the Discord Social SDK](/docs/discord-social-sdk/getting-started)
2828
- An understanding of [Creating and Managing Lobbies](/docs/discord-social-sdk/development-guides/managing-lobbies)
2929

30+
<CommsScopeWarning />
31+
3032
---
3133

3234
## Linked Channel Requirements
@@ -313,9 +315,10 @@ int main() {
313315
314316
## Change Log
315317
316-
| Date | Changes |
317-
|----------------|-----------------|
318-
| March 17, 2025 | initial release |
318+
| Date | Changes |
319+
|----------------|----------------------------------|
320+
| June 30, 2025 | Add communications scope warning |
321+
| March 17, 2025 | initial release |
319322
320323
{/* Autogenerated Reference Links */}
321324
[`Client::GetGuildChannels`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#adba1e5a83c219a9c4f6dab1657778017

‎docs/discord-social-sdk/development-guides/managing-lobbies.mdx

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
sidebar_label: Managing Lobbies
33
---
44
import LimitedAccessCallout from '../partials/callouts/limited-access.mdx';
5-
import PublicClient from '../partials/callouts/public-client.mdx';
65
import SupportCallout from '../partials/callouts/support.mdx';
6+
import CommsScopeWarning from '../partials/callouts/oauth-comms-scopes.mdx';
77

88
[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > [Development Guides](/docs/discord-social-sdk/development-guides) > {sidebar_label}
99

@@ -27,6 +27,8 @@ Before you begin, make sure you have:
2727

2828
- Set up the Discord Social SDK with our [Getting Started guide](/docs/discord-social-sdk/getting-started)
2929

30+
<CommsScopeWarning />
31+
3032
---
3133

3234
## Lobby Features
@@ -195,9 +197,10 @@ With your game able to create and manage lobbies, you can now implement addition
195197

196198
## Change Log
197199

198-
| Date | Changes |
199-
|----------------|-----------------|
200-
| March 17, 2025 | initial release |
200+
| Date | Changes |
201+
|----------------|----------------------------------|
202+
| June 30, 2025 | Add communications scope warning |
203+
| March 17, 2025 | initial release |
201204

202205
{/* Autogenerated Reference Links */}
203206
[`ChannelHandle`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1ChannelHandle.html#ac32096b2ef15c5c220e9b7b92253cc46

‎docs/discord-social-sdk/development-guides/managing-voice-chat.mdx

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
sidebar_label: Managing Voice Chat
33
---
44
import LimitedAccessCallout from '../partials/callouts/limited-access.mdx';
5-
import PublicClient from '../partials/callouts/public-client.mdx';
65
import SupportCallout from '../partials/callouts/support.mdx';
6+
import CommsScopeWarning from '../partials/callouts/oauth-comms-scopes.mdx';
77

88
[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > [Development Guides](/docs/discord-social-sdk/development-guides) > {sidebar_label}
99

@@ -27,7 +27,9 @@ This guide will show you how to:
2727

2828
Before you can start a voice call, you must complete these essential steps:
2929

30-
### 1. Lobby Management (Required)
30+
<CommsScopeWarning />
31+
32+
### 1. Lobby Management
3133

3234
**Voice calls require an active lobby with participants.** You must:
3335

@@ -295,10 +297,11 @@ This information is particularly useful for:
295297
296298
## Change Log
297299
298-
| Date | Changes |
299-
|----------------|-----------------|
300-
| March 17, 2025 | initial release |
301-
| June 19, 2025 | released guide |
300+
| Date | Changes |
301+
|----------------|----------------------------------|
302+
| June 30, 2025 | Add communications scope warning |
303+
| June 19, 2025 | released guide |
304+
| March 17, 2025 | initial release |
302305
303306
{/* Autogenerated Reference Links */}
304307
[`Call`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Call.html#a1cc8a7f73c15a960bc409d734b5edbd1

‎docs/discord-social-sdk/development-guides/sending-direct-messages.mdx

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
sidebar_label: Sending Direct Messages
33
---
44
import LimitedAccessCallout from '../partials/callouts/limited-access.mdx';
5-
import PublicClient from '../partials/callouts/public-client.mdx';
65
import SupportCallout from '../partials/callouts/support.mdx';
6+
import CommsScopeWarning from '../partials/callouts/oauth-comms-scopes.mdx';
77

88
[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > [Development Guides](/docs/discord-social-sdk/development-guides) > {sidebar_label}
99

@@ -18,6 +18,14 @@ Direct Messages (DMs) allow players to communicate privately. This guide will sh
1818
- Send text messages between users
1919
- Handle displaying messages in your game
2020

21+
### Prerequisites
22+
23+
Before you begin, make sure you have:
24+
25+
- Set up the Discord Social SDK with our [Getting Started guide](/docs/discord-social-sdk/getting-started)
26+
27+
<CommsScopeWarning />
28+
2129
### Types of Chat Messages
2230

2331
The Discord Social SDK SDK supports two types of chat:
@@ -143,10 +151,11 @@ Now that you know how to send and receive messages, check out these other Discor
143151

144152
## Change Log
145153

146-
| Date | Changes |
147-
|----------------|---------------------|
148-
| May 06, 2025 | link to DM Settings |
149-
| March 17, 2025 | initial release |
154+
| Date | Changes |
155+
|----------------|----------------------------------|
156+
| June 30, 2025 | Add communications scope warning |
157+
| May 06, 2025 | link to DM Settings |
158+
| March 17, 2025 | initial release |
150159

151160
{/* Autogenerated Reference Links */}
152161
[`ChannelHandle`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1ChannelHandle.html#ac32096b2ef15c5c220e9b7b92253cc46

‎docs/discord-social-sdk/partials/callouts/oauth-comms-scopes.mdx

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
:::warn
2+
To utilize this communication feature, you must enable [`Client::GetDefaultCommunicationScopes`] in your OAuth Scope configuration.
3+
See the [OAuth Scopes Core Concepts Guide](/docs/discord-social-sdk/core-concepts#oauth2-scopes) for more details.
4+
:::
5+
6+
{/* Autogenerated Reference Links */}
7+
[`Client::GetDefaultCommunicationScopes`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a71499da752fbdc2d4326ae0fd36c0dd1

0 commit comments

Comments
 (0)