Web SDK: opt-out for auto-login on Beam.init

[allister-beamable]

Problem

Beam.init() in the web SDK currently auto-mints a guest account whenever no stored access token is found. The auto-login path is in web/src/core/Beam.ts:143-144:

if (!accessToken) {
  // If no access token exists, login as a guest
  tokenResponse = await this.clientServices.auth.loginAsGuest();
}

There is no configuration knob to suppress this behavior. Every fresh page load on a site that calls Beam.init on boot - including bots, scrapers, and visitors who close the tab before doing anything - results in a brand-new guest dbid against the realm.

For projects with an open web surface this can inflate platform-side player counts by one to two orders of magnitude relative to the population of users who actually interacted with the game. It also produces a long tail of dbids that mint a token, hit a handful of bootstrap services, and are never seen again.

Proposal

Add an option to BeamConfig (working name: autoGuestLogin: boolean, default true for backwards compatibility) that, when set to false, skips the loginAsGuest() call inside the connect flow. With the option off, the SDK initializes in an unauthenticated state and waits for the integrator to call loginAsGuest() (or any other auth method) explicitly in response to a user action.

This lets integrators defer dbid creation until a visitor demonstrates intent (clicks "Play", connects a wallet, signs in via federated identity, etc.), which both reduces stray account creation and gives the integrator full control over when the account is minted.

Acceptance criteria

• BeamConfig accepts an opt-out flag (name TBD) that disables the auto-guest path on Beam.init.
• With the flag set, Beam.init completes without calling /basic/auth/token and without writing token state.
• API calls that require auth raise a clear "not authenticated" error rather than silently triggering a guest login.
• Default behavior is unchanged so existing integrations are not affected.

Notes

• Unity SDK has a similar shape (BeamContext initialization implies a guest login when no token is present); a follow-up parity issue may be warranted, but this issue is scoped to web.

[allister-beamable]

I think the magnitude of importance differs between Web and Unity; with a Unity game, unless it is WebGL, presumably the player has to intentionally install it before launching -- they are more player-like than someone who lands on a website, decides the thing is not for them, and closes the tab.

[cdhanna]

@allister-beamable , what is the use case for calling Init on the webSDK without a beamable token to begin with?

Perhaps the issue is that we want to be able to send credentials into the SDK on init? I don't think having an SDK instance object with no credentails is useful, because... it can't do anything.

Technically, at the moment, we can override the tokenStorage options and preconfigure a user; but that is pretty obtuse.

[allister-beamable]

@cdhanna it may be moot in the customer use case that I am aware of.

What the customer wants:

• only ever create Beamable player accounts after game-specific OAuth is verified

How they are currently doing it:

• gate Beam.init behind logic that flips a boolean variable to true when their OAuth is verified

Part of the investigation that led to this issue was that the customer in question has loads of spurious MAU: player IDs in the database that never actually played the game, according to analytics. At first, my theory was that people were hitting the game's website and then leaving, causing unused Beam.inits to happen. But with the OAuth gate, that theory is debunked.

So, as long as game developers have control over whether Beam.init happens at all, that is baseline "good enough". The beyond-good-enough solution would be to honor this:

Perhaps the issue is that we want to be able to send credentials into the SDK on init?

^ if devs can specify "init Beamable, but only with these pre-validated OAuth creds (that is, Federated Identity)" that gives them total confidence that any player they see in Portal or in analytics is a "real player"