Ecosystems

MetaFab Ecosystems are a powerful way to support a network of games with a consistent and standard single sign-on auth flow across them to enable new degrees of game interoperability, frictionless player experiences, and more. You can learn more details about how Ecosystems work here.

Create an Ecosystem Account

Before we dive in, you'll need to create an Ecosystem account. You can do this through the create Ecosystem API endpoint here.

Branding

You can quickly brand the look and feel of your entire Ecosystem's single sign-on flow using the update Ecosystem API endpoint.

You can set and update branding parameters for your Ecosystem through the update Ecosystem endpoint are:

• name: This is the name of your Ecosystem shown on the single sign-on flow.

• iconImageBase64: This is the image used for the icon at the top of your single sign-on flow. This parameter is set as a base64 representation of the image you want to use. You can use tools like https://www.base64-image.de/ to convert your image to its base64 version, such as data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

• coverImageBase64: This is the background image used for your single sign-on flow. This parameter is set as a base64 representation of the image you want to use. You can use tools like https://www.base64-image.de/ to convert your image to its base64 version, such as data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

• primaryColorHex: The hex color (#05B1A3, for example) to use for the buttons of your single sign-on flow.

Additionally, single sign-on flows use a combination of your Ecosystem's branding and the branding for the game a player is attempting to sign in to. Any games in your Ecosystem should set their name, iconImageBase64 and coverImageBase64 through the update game API endoint.

Setup & Configuration

All single sign-on flows for Ecosystems by default are set on the base URL: https://accounts.trymetafab.com/oauth. We also support single sign-on flows through your custom domain or subdomain.

You can configure usage by setting query parameters. These query parameters append to your single sign-on flow's base URL. For example, a valid configured single sign-on flow URL is: https://accounts.trymetafab.com/oauth/?ecosystem=b573c2dc-5e93-4c99-a57f-569480d05204&game=addd8995-50b3-4021-aa61-da7277432b9a&permissions={"version":"1.0.0","0x539bdE0d7Dbd336b79148AA742883198BBF60342":{"chain":"ARBITRUM","scopes":["transfers"],"erc20Limit":"*"}}

See the list of configurable query parameters and their explanations below.

Configuring Permissions

Setting the permissions query parameter by default is optional. If you omit it, your game will request the default player profile permissions which allow you to view all their wallet assets, mint and transfer assets to their profile wallet, and use their wallet credentials to interact with any contracts specifically created for and by your game based on the matching systemId assigned on-chain to your game (You can learn more about the systemId for custom contract here if you're curious).

The permissions request object follows a standard format; see the code example below to learn how to configure permissions.

{
  "version": "1.0.0", // For now, this is always "1.0.0"
  // The following contract permission configuration is an example showing all possible configurables.
  "0x539bdE0d7Dbd336b79148AA742883198BBF60342": { // The key is the contract address you want permissions for
    "chain": "ARBITRUM", // The chain this contract is on REQUIRED
    "scopes": [ // an array of scopes for standard function access OPTIONAL
      "transfers", // gives contract function call permission to all standard ERC20/ERC1155 type transfer functions
      "approvals" // gives contract function call permission to all standard ERC20/ERC1155 type approval functions
    ],
    "functions": [ // an array of contract specific functions to request permissions for OPTIONAL
      "doSomething", // can be any named function of the target contract
      "burnThings"
    ],
    "erc20Limit": "*", // If the contract is an ERC20 contract, sets the maximum lifetime amount of token that the game can use from the profile wallet. * = unilimited, 100 = 100 token OPTIONAL
    "erc1155Limits": { // If the contract is an ERC1155 contract, sets the maximum lifetime amount of specific item ids the game can use from the profile wallet. OPTIONAL
      "1": "10", // Key value pairs mapping item id -> item quantity
      "*": "*" // An item id of * means all items, an item quantity of * means unlimited quantity.
    }
  },
  // The following contract permission configuration is an example of what a configured contract permission request may look like
  "0x381227255ef6c5d85966b78d13e4b4a4c8719b5e": { // You can include as many or as few external contract addresses as you need to request permission for.
    "chain": "ARBITRUM",
    "scopes": [ "transfers" ],
    "erc1155Limits": { "*": "*" } // This contract permission example is basically saying "My game requests the ability to transfer any quantiy of any assets you hold for contract the Arbitrum contract at address 0x381227255ef6c5d85966b78d13e4b4a4c8719b5e"
  },
}

Custom Domain Support

If you'd like to route your Ecosystem's single sign-on flow through a custom domain or subdomain instead of https://accounts.trymetafab.com, please reach out to our team on Discord to configure this.

Example Flows & Implementation Patterns

We have a few possible patterns you may choose to integrate your single sign-on flow through, depending on your Ecosystem and game needs:

Redirect Pattern

Redirect patterns are common for web-based games or UI's where your players need to be redirected to a page on your game's website or a settings page on the web.

Setting the redirectUri, your game may choose to link a "Sign In With ... " button from your game's website to the https://accounts.trymetafab.com/oauth/?... single sign-on flow. From there, your player can log in to your game using their Ecosystem-level profile. After successfully logging in, the player will be redirected to the redirectUri you set in the configurable query parameters.

This redirect uri will have the authenticated player profile's accessToken, walletDecryptKey, and id. For example, a redirect uri may be https://mygame.com/game and the resulting redirect will become https://mygame.com/game#accessToken=PLAYER_ACCESS_TOKEN&walletDecryptKey=PLAYER_WALLET_DECRYPT_KEY&id=PLAYER_ID. From here, your game's webpage logic can grab the player accessToken, walletDecryptKey and id from the fragment (#) url parameters and perform any final login/authentication logic needed for your game. Profile accessToken and walletDecryptKey work the same as a standard player.

Embed Pattern

The embed pattern is intended for mobile apps, native games, or any non-web implementations.

For example, you may choose to build a mobile app or desktop game and an ecosystem's single sign-on for login.

You can use the embed pattern by excluding the redirectUri from the single sign-on flow's query parameters. This allows you to do an in-app or in-game web browser/modal window that opens the target ecosystem single sign-on flow webpage. Your player would login to their ecosystem profile through this flow, grant your game the requested permissions, and once finished the player's accessToken, walletDecryptKey, and id will be set and update the auth page's URL. An example final page URL after a player completes the flow may look like https://accounts.trymetafab.com/oauth/?ecosystem=b573c2dc-5e93-4c99-a57f-569480d05204&game=addd8995-50b3-4021-aa61-da7277432b9a

You can use a URL change listener for your in-app or in-game browser modal and wait for the #accessToken=, walletDecryptKey= &id= fragment properties to be set on the URL. Once set, you can extract the player's accessToken, walletDecryptKey, and id and perform any additional auth logic for your game from there and automatically close the browser modal/pop-up.