Overview

ImmutableX Web Client SDK allows users to login with their Ethereum Wallet address. Authentication is performed with the browser wallet plugin, such as MetaMask.

Setup

To use ImmutableX Wallet login, you need to:

1. Configure Game Client to include ImmutableX Link SDK in WebGL build by setting the EnableWeb3 and EnableImmutableXLinkClientLibrary feature flags.

   In the GlobalOptions.cs, define:

   public MetaplayCoreOptions Options { get; } = new MetaplayCoreOptions(
       ...
       featureFlags: new MetaplayFeatureFlags
       {
           ...
           EnableWeb3: true,
           EnableImmutableXLinkClientLibrary: true
       }

2. Configure Game Server to support Wallet authentication:

   In the relevant Options.<env>.yaml, set:

   Web3:
       ImmutableXNetwork: GoerliTestnet
       EnableImmutableXPlayerAuthentication: true
       ImmutableXPlayerAuthenticationProductName: "My Game Name"
       ImmutableXPlayerAuthenticationChallengeHmacSecret: <random string>
       ImmutableXApiKey: <Optional ImmutableX API key, can be left empty>

   ImmutableXPlayerAuthenticationChallengeHmacSecret should be set to some arbitary, unpredictable string of your choosing. For example, you may use ([guid]::NewGuid()).ToString() in PowerShell or python -c "import uuid; print(uuid.uuid4())" to generate an unpredictable string for this purpose.

   Note that the ImmutableXNetwork is in this example GoerliTestnet. In production environments, this should be set to EthereumMainnet.

3. Implement the client side logic.

   In the game UI, add a button or other logic to invoke login flow. To start the login flow, simply call ImmutableXLinkSdkHelper.LoginWithImmutableXAsync. As the login flow is async, you may need wrap it in MetaTask.Run to invoke it from synchronous contexts. For example:

   public void OnClickImxLogin()
   {
       MetaTask.Run(async () =>
       {
           await ImmutableXLinkSdkHelper.LoginWithImmutableXAsync(forceResetup: false);
       });
   }

4. Test and fine tune prompts.

   

   To customize the login prompt on ImmutableX, you may edit Web3:ImmutableXPlayerAuthenticationDescriptionTemplate. To customize the prompt in the Wallet software, edit Web3:ImmutableXPlayerAuthenticationMessageTemplate. Both templates support following substitutions:

   • {ProductName} for ImmutableXPlayerAuthenticationProductName.
   • {PlayerId} for PlayerId
   • {EthAccount} for the claimed Ethereum Account address.
   • {ImxAccount} for the claimed ImmutableX account (Stark Address).
   • {Timestamp} for the current timestamp.
   • {Signature} for a HMAC of the login challenge parameters. This MUST be used in Web3:ImmutableXPlayerAuthenticationMessageTemplate as it is required to verify the challenge was generated by the appropriate game backend. If {Signature} is not present in the Template, it is an error and server will not start.