Linking accounts
Connect Discord, X, Twitch, Steam and more to a signed-in fan, so the quests that need them open up.
Separate from sign-in, and the reason most social quests work at all. A fan signs in with Google, opens a Discord quest, and needs their Discord linked before they can do it.
How it works
Five steps, and your app owns two of them:
- A quest tells you an account is missing.
- You send the fan to the proxy to connect it.
- The proxy sends them back to your callback page with a token.
- You redeem the token.
- The quest re-checks and opens up.
Linking needs a fan who is already signed in. It never signs anyone in, and never touches their session.
- 1The quest says an account is missingstate.machine.reason is
SOCIAL_NOT_LINKED - 2You send the fan to connect DiscordA plain link to
buildBindUrl - 3The proxy sends them back to your callback
parseBindCallbackreads the token - 4You redeem the token
useBind().bind, within five minutes - 5The quest re-checks
useLinkedSocialsfeedsauthProfile, and the button enables
1. Know what is missing
Do not scan the fan's accounts yourself. The quest's state machine already knows, and tells you why the quest is closed:
import { useQuest } from '@xborglabs/fanbase-react'
const { state } = useQuest()
const reason = state.machine.reasonstate.machine.reason | Means | Show |
|---|---|---|
SOCIAL_NOT_LINKED | The quest needs an account the fan has not linked | A connect button |
SOCIAL_EXPIRED | They linked it, but the link has expired | A reconnect prompt, over the same button |
SERVER_SELECTION_REQUIRED | A Riot account is linked with no region | A region picker. This one is not solved by linking. |
state.disabledReasonLabel already says which account, in a sentence you can show. Quest detail covers where it goes on the page.
2. Send them to connect
A plain link. No request, no button handler.
import { BIND_ACCOUNT_TYPE, buildBindUrl } from '@xborglabs/fanbase-react'
const connectUrl = buildBindUrl({
oauthProxyUrl: proxyUrl,
provider: 'discord',
redirectUrl: `https://yoursite.com/link/callback?accountType=${BIND_ACCOUNT_TYPE.DISCORD}`,
})
<a href={connectUrl} className="your-button">Connect Discord</a>proxyUrl is the same one you built for sign-in. Building the sign-in URL.
Put the account type in your redirectUrl. Worth reading twice: when the fan comes back, nothing in the callback says what they just connected, or even that it was a link rather than a sign-in. The only way your callback page knows is if you told it on the way out. Like sign-in, the redirect URL has to be registered with the proxy.
provider is the proxy's lowercase name for the service, discord or twitter. BIND_ACCOUNT_TYPE.DISCORD is the SDK's name for the same account. They are two different vocabularies, which is why both appear above.
3. Read the callback
On your callback page:
import { parseBindCallback } from '@xborglabs/fanbase-react'
const callback = parseBindCallback(window.location.search)
// { token: '…', accountType: 'DISCORD' } or nullIt returns null when there is no token in the URL. Show a message in that case, not a spinner.
It reads the account type from the URL you built in step 2. If it cannot find one, accountType is null. Keep the type you sent in sessionStorage as a backup, the same way sign-in carries the provider through.
4. Redeem the token
import { useBind } from '@xborglabs/fanbase-react'
const { bind, isPending } = useBind()
await bind({ token: callback.token, accountType })Redeem it on the callback page, straight away. The token expires five minutes after the redirect. Not after a form, not behind a "Confirm" button.
The token also works more than once inside those five minutes, so treat it like a password. Keep it out of any URL you share, your logs and your analytics, and drop it once it is redeemed.
5. Let the quest re-check
bind refreshes the fan's linked accounts and every quest on success. For the quest to see the new account, feed the linked accounts into it:
import { Quest, useLinkedSocials } from '@xborglabs/fanbase-react'
const { data: socials = [] } = useLinkedSocials()
const profile = useFanProfile() // wallets still come from the fan profile
<Quest.Provider questId={questId} authProfile={{ socials, wallets: profile?.wallets }} fetchRewards>The quest's button enables on its own, with no page reload.
Use useLinkedSocials for this, not the fan profile. It is the only read that includes when a link expires and which Riot region an account is on, and the quest needs both to tell an expired link from a working one. An authProfile built from the profile endpoint leaves the fan stuck on an expired link with no way to see why.
Do not refresh the session afterwards. Linking does not change it, and a session refresh here only adds a request.
What can be linked
BIND_ACCOUNT_TYPE | Can also sign in | Notes |
|---|---|---|
DISCORD | yes | |
TWITTER | yes | |
TWITCH | yes | Expires after 30 days |
STEAM | no | |
FACEIT | no | |
RIOT | no | Rank quests need a region, which linking does not set |
YOUTUBE | no | |
EPIC | no | |
BATTLENET | no | Expires after one day |
SPOTIFY | no | |
BUSHI | no | Game-specific. Ask us before relying on it. |
APEIRON | no | Game-specific. Ask us before relying on it. |
Google can sign a fan in, but it cannot be linked. Wallets are not linked this way at all: a wallet quest takes the address as its input. Quest templates.
Expired links
Twitch and Battle.net links expire. The platform does not stop the fan using an expired one, it just records the date, and the quest machine checks it and reports SOCIAL_EXPIRED.
Show a reconnect prompt, pointing at the same connect link as step 2. Relinking replaces the old link. It is not an error, and the fan does not need to disconnect first.
Riot regions
Riot rank quests need to know which region the fan plays on, and linking a Riot account does not record it. The platform has no way to set it through this flow, so a linked Riot account alone cannot clear SERVER_SELECTION_REQUIRED.
If Riot rank quests matter to your community, talk to your FanBase contact before you launch them.
Errors
| Error | Means | Show |
|---|---|---|
BindTokenExpiredError | The five minutes ran out | "That took too long. Try again", and the connect link again |
BindAccountTypeMismatchError | The account type you sent does not match what they connected | A bug in your redirect URL. Log it. |
SocialAlreadyBoundError | This account is linked to a different fan | "Already connected to another account". Retrying will not help. |
SocialReconnectionLimitError | They have relinked too many times | Point them at support. Do not retry automatically. |
Switch on the error class, never the message.
One case raises no error at all. For Discord, X and Twitch, linking also lets the account sign in. If that account already signs in a different fan, the platform links it and quietly skips the sign-in part, and reports success. So after a link, trust useLinkedSocials, not the success response.
Checklist
- A quest missing an account shows a connect link, driven by
state.machine.reason - The redirect URL carries the account type
- The callback page redeems the token straight away
- The quest's button enables after linking, with no reload
authProfile.socialscomes fromuseLinkedSocials- An expired Twitch link shows a reconnect prompt
- Each of the four errors shows its own message
- The token never reaches a log or an analytics call