|
| 1 | +--- |
| 2 | +title: Account Linking from Discord |
| 3 | +sidebar_label: Account Linking from Discord |
| 4 | +description: Adopt the new account linking APIs to allow Discord to show your players entry points for account linking within the Discord client |
| 5 | +--- |
| 6 | + |
| 7 | +import SupportCallout from '../partials/callouts/support.mdx'; |
| 8 | + |
| 9 | +[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > [Development Guides](/docs/discord-social-sdk/development-guides) > {sidebar_label} |
| 10 | + |
| 11 | +# {sidebar_label} |
| 12 | + |
| 13 | +## Overview |
| 14 | + |
| 15 | +To give players more flexibility and options for account linking, Discord can show prompts and buttons throughout the Discord client that encourage users to link their accounts with your game. These are called entry points for account linking. |
| 16 | + |
| 17 | +Higher account linking rates lead to better social features, improved engagement, and a stronger connection between your game and Discord users. |
| 18 | + |
| 19 | +This guide shows you how to enable Discord to display these account linking prompts to your players. |
| 20 | + |
| 21 | +### Prerequisites |
| 22 | + |
| 23 | +Before enabling these entry points, you must have: |
| 24 | + |
| 25 | +- **Discord application setup** |
| 26 | + - Created a Discord application in the [Developer Portal](https://discord.com/developers/applications) |
| 27 | + - Configured OAuth2 settings with appropriate redirect URLs |
| 28 | +- **Implemented account linking in your game** |
| 29 | + - Discord Social SDK downloaded and integrated into your game |
| 30 | + - SDK initialization working (can connect to Discord) |
| 31 | + - [Basic account linking flow](/docs/discord-social-sdk/development-guides/account-linking-with-discord) already implemented in your game |
| 32 | +- **Development environment ready** |
| 33 | + - Game can successfully authenticate users with Discord OAuth2 |
| 34 | + |
| 35 | +If you haven't completed these prerequisites, we recommend first following the [Getting Started](/docs/discord-social-sdk/getting-started) guide. |
| 36 | + |
| 37 | +--- |
| 38 | + |
| 39 | +## Entry Points & Account Linking Flows |
| 40 | + |
| 41 | +### What are Entry Points? |
| 42 | + |
| 43 | +Entry points are buttons, prompts, and UI elements that Discord shows throughout the Discord client to encourage account linking. Think of them as "Link your account" buttons that appear in various places where users might see your game. |
| 44 | + |
| 45 | +### Example of an Entry Point |
| 46 | + |
| 47 | +Discord automatically chooses which entry points to show based on what features you've implemented and whether your game is currently running. |
| 48 | + |
| 49 | + |
| 50 | + |
| 51 | +### Account Linking Flows |
| 52 | + |
| 53 | +At this time, Discord provides two different flows for account linking from the client, the connected game flow and the web flow. When a user clicks on one of the entry points within their Discord client, it will choose one of the currently available flows to send the user through. To provide a good user experience, flows are chosen in the following priority order: |
| 54 | + |
| 55 | +- [Connected game flow](/docs/discord-social-sdk/development-guides/account-linking-from-discord#connected-game-flow) |
| 56 | +- [Web flow](/docs/discord-social-sdk/development-guides/account-linking-from-discord#web-flow) |
| 57 | + |
| 58 | +Choose which flows work best for your game and follow the implementation guides below. You can implement one or both flows to give your players more options for linking their accounts. |
| 59 | + |
| 60 | +--- |
| 61 | + |
| 62 | +## Connected Game Flow |
| 63 | + |
| 64 | +This is our prefered account linking flow as we think it provides the best user experience when it's available. The connected game flow will send the user into your game client to begin the account linking flow. |
| 65 | + |
| 66 | +### Prerequisites |
| 67 | + |
| 68 | +- Upgrade to SDK version 1.6 or higher |
| 69 | +- Implement [account linking](/docs/discord-social-sdk/development-guides/account-linking-with-discord) in your game |
| 70 | + |
| 71 | +### Implementing the Connected Game Flow |
| 72 | + |
| 73 | +Once you have adopted SDK version 1.6 or higher, there will be two new methods on the Client object, [`Client::RegisterAuthorizeRequestCallback`] and [`Client::RemoveAuthorizeRequestCallback`]. These two new methods will allow you to enable and disable this flow while your game is running. |
| 74 | + |
| 75 | +:::warn |
| 76 | + Before calling [`Client::RegisterAuthorizeRequestCallback`], ensure |
| 77 | + [`Client::SetApplicationId`] has been called. This ensures that your game is |
| 78 | + properly identifying itself to the Discord client and that all requests are |
| 79 | + associated with the correct application. |
| 80 | +::: |
| 81 | + |
| 82 | +Calling [`Client::RegisterAuthorizeRequestCallback`] with a callback function will signal to the Discord client that your game is running and able to start the account linking process. You should run this as soon as your game is able to handle an account link, for instance just after your user has logged in or reached the main menu. |
| 83 | + |
| 84 | +When a user clicks one of the account linking entry points in their Discord client, the SDK will run your callback. Treat this as if the user had just clicked one of your in-game account linking buttons and begin the authorization flow right away. |
| 85 | + |
| 86 | +:::info |
| 87 | + When your game receives this callback, the user is most likely focused on the |
| 88 | + Discord client, not the game client. Make sure to pull focus or otherwise |
| 89 | + alert the user that something is happening in the game. The Discord client |
| 90 | + will notify them to check the game as well. For a more seamless |
| 91 | + experience, you should pull them back into the game. |
| 92 | +::: |
| 93 | + |
| 94 | +Calling [`Client::RemoveAuthorizeRequestCallback`] will signal to the Discord client that your game is no longer able to start the account linking process. Call this whenever your game client is entering a state where starting the account linking process wouldn't work, for instance if the player enters a match, logs out, or is in some other full screen flow like a cutscene. |
| 95 | + |
| 96 | +This is all you need to enable the connected game flow, you can test and debug this flow using our new [built-in developer tools](/docs/discord-social-sdk/how-to/debug-log#client-tools) in the Discord client. |
| 97 | + |
| 98 | +```cpp |
| 99 | +// If you haven't already |
| 100 | +client.SetApplicationId("123456789"); |
| 101 | + |
| 102 | +client.RegisterAuthorizeRequestCallback([client, myGameAuthorizationHandler]() { |
| 103 | + // Pull focus into your game using native APIs |
| 104 | + // ... |
| 105 | + |
| 106 | + // Run your normal authorization flow |
| 107 | + myGameAuthorizationHandler.StartDiscordAccountLink(); |
| 108 | +}); |
| 109 | +``` |
| 110 | + |
| 111 | +### Connected Game Best Practices |
| 112 | + |
| 113 | +When a user clicks the account link button in their Discord client, this is a high intent action. We recommend skipping any extra upsells you have until after the user has linked their account, as any extra steps added to this linking flow increases the areas where users may drop off. Show them any upsells after they've linked to reaffirm all the new features and any rewards they may have unlocked by linking their account. |
| 114 | + |
| 115 | +Ensure you're enabling and disabling the callback at the appropriate times. If a user clicks an entry point in their Discord client and it launches the account linking flow in the middle of a match, this can interrupt gameplay and pull them out of your intended experience. |
| 116 | + |
| 117 | +Don't worry about checking if the user is already linked, the Discord client will handle hiding the entry point for users that have already linked their accounts. This will keep your implementation simpler and reduce surface for issues. |
| 118 | + |
| 119 | +## Web Flow |
| 120 | + |
| 121 | +The web flow is an alternative to the connected game flow, allowing you to send users to a webpage to begin the account linking process. |
| 122 | + |
| 123 | +:::preview |
| 124 | +At this time, this flow is only available to select partners. |
| 125 | +::: |
| 126 | + |
| 127 | +### Prerequisites |
| 128 | + |
| 129 | +- Implement the [standard OAuth2 flow](/docs/topics/oauth2) on your website |
| 130 | + |
| 131 | +### Implementing the Web Flow |
| 132 | + |
| 133 | +Ensure your webpage meets the following requirements: |
| 134 | + |
| 135 | +- If the user isn't signed in to their game account, it should prompt them to sign in and then take them immediately back to the authorization flow. |
| 136 | +- The authorization should request the same scopes that you request in your game |
| 137 | +- After authorization is complete, the token should be saved to the user's account the same way you would during in-game authorization so that it's ready the next time the user launches their game |
| 138 | +- If the user is currently in game, send an update to their client with the token and call [`Client::UpdateToken`] to sign them in right away without needing to restart their game |
| 139 | + |
| 140 | +--- |
| 141 | + |
| 142 | +## Next Steps |
| 143 | + |
| 144 | +Now that you've successfully implemented account linking with Discord, you can integrate more social features into your game. |
| 145 | + |
| 146 | +<Container> |
| 147 | + <Card |
| 148 | + title="Design: Signing In" |
| 149 | + link="/docs/discord-social-sdk/design-guidelines/signing-in" |
| 150 | + icon="PaintPaletteIcon" |
| 151 | + > |
| 152 | + Design guidelines for account linking and user authentication |
| 153 | + </Card> |
| 154 | + <Card |
| 155 | + title="Creating a Unified Friends List" |
| 156 | + link="/docs/discord-social-sdk/development-guides/creating-a-unified-friends-list" |
| 157 | + icon="ListViewIcon" |
| 158 | + > |
| 159 | + Combine Discord and game friends into a single list for easy management. |
| 160 | + </Card> |
| 161 | + <Card |
| 162 | + title="Setting Rich Presence" |
| 163 | + link="/docs/discord-social-sdk/development-guides/setting-rich-presence" |
| 164 | + icon="UserIcon" |
| 165 | + > |
| 166 | + Display game status and information to Discord friends. |
| 167 | + </Card> |
| 168 | +</Container> |
| 169 | + |
| 170 | +<SupportCallout /> |
| 171 | + |
| 172 | +--- |
| 173 | + |
| 174 | +## Change Log |
| 175 | + |
| 176 | +| Date | Changes | |
| 177 | +|-------------------|-----------------| |
| 178 | +| December 16, 2025 | initial release | |
| 179 | + |
| 180 | +{/* Autogenerated Reference Links */} |
| 181 | +[`Client::RegisterAuthorizeRequestCallback`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a5f34b873e127a446c9ab549e4588ccd7 |
| 182 | +[`Client::RemoveAuthorizeRequestCallback`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#ab7e48864b0cedf3e8572a228ca401f2a |
| 183 | +[`Client::SetApplicationId`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#ad452335c06b28be0406dab824acccc49 |
| 184 | +[`Client::UpdateToken`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a606b32cef7796f7fb91c2497bc31afc4 |
0 commit comments