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:

  1. A quest tells you an account is missing.
  2. You send the fan to the proxy to connect it.
  3. The proxy sends them back to your callback page with a token.
  4. You redeem the token.
  5. 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.

Linking Discord, start to finishTry it
Your redirect URL
  1. 1The quest says an account is missing
    state.machine.reason is SOCIAL_NOT_LINKED
  2. 2You send the fan to connect Discord
    A plain link to buildBindUrl
  3. 3The proxy sends them back to your callback
    parseBindCallback reads the token
  4. 4You redeem the token
    useBind().bind, within five minutes
  5. 5The quest re-checks
    useLinkedSocials feeds authProfile, and the button enables
The clock runs 30 times faster than real time. Example flow.

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.reason
state.machine.reasonMeansShow
SOCIAL_NOT_LINKEDThe quest needs an account the fan has not linkedA connect button
SOCIAL_EXPIREDThey linked it, but the link has expiredA reconnect prompt, over the same button
SERVER_SELECTION_REQUIREDA Riot account is linked with no regionA 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 null

It 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_TYPECan also sign inNotes
DISCORDyes
TWITTERyes
TWITCHyesExpires after 30 days
STEAMno
FACEITno
RIOTnoRank quests need a region, which linking does not set
YOUTUBEno
EPICno
BATTLENETnoExpires after one day
SPOTIFYno
BUSHInoGame-specific. Ask us before relying on it.
APEIRONnoGame-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.

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

ErrorMeansShow
BindTokenExpiredErrorThe five minutes ran out"That took too long. Try again", and the connect link again
BindAccountTypeMismatchErrorThe account type you sent does not match what they connectedA bug in your redirect URL. Log it.
SocialAlreadyBoundErrorThis account is linked to a different fan"Already connected to another account". Retrying will not help.
SocialReconnectionLimitErrorThey have relinked too many timesPoint 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.socials comes from useLinkedSocials
  • 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

On this page