Mavis ID TypeScript SDK
Overview
The Mavis ID JS SDK lets developers integrate Mavis ID into browser games written in JavaScript or TypeScript. After the integration, users can sign in your game with Mavis ID and set up a Web3 wallet to interact with the blockchain to send and receive tokens, sign messages, and more.
The SDK provides the MavisIdWallet, a provider compatible with the EIP-1193 standard, letting developers use the standard Ethereum JavaScript libraries, such as Ethers.js, Web3.js, or viem) to interact with the blockchain.
Experience Mavis ID in the playground: Mavis ID Playground. Get some testnet RON tokens from the Ronin Faucet before you do.
Prerequisites
- A TypeScript or JavaScript game project.
- Node.js v20 or later.
- npm or yarn for package installation
- Next.js v14 or later.
- To run the demo app, pnpm v8 or later.
Quick start
A sample project built with Next.js is available in the Mavis ID TypeScript SDK repository, as a local version of the Mavis ID Playground. To set up the project, follow these steps:
- Clone the repository:
git clone https://github.com/skymavis/mavis-id-js.git
- Install the dependencies:
pnpm install
- Start the development server:
pnpm dev
Steps
Step 1. Install the SDK
To install the SDK, use the following command:
npm install @sky-mavis/mavis-id-sdk
# or
yarn add @sky-mavis/mavis-id-sdk
# or
pnpm install @sky-mavis/mavis-id-sdk
Step 2. Initialize the SDK
Import MavisIdWallet from the SDK and pass your app's client ID and the chain ID that you want to connect to:
import { MavisIdWallet } from "@sky-mavis/mavis-id-sdk"
const idWalletProvider = MavisIdWallet.create({
// Replace with the client ID from the Developer Console
clientId: process.env.YOUR_CLIENT_ID,
// Saigon testnet: 2021, Ronin mainnet: 2020
chainId: chainId,
})
Parameters:
clientId: the client ID registered in the Mavis ID settings in the Developer Console.chainId: the ID of the Ronin chain you want to connect to. Use2021for the Saigon testnet and2020for the Ronin mainnet.
On connection, you can use the MavisIdWallet provider with the common libraries as shown in the following examples:
- Web3.js
- Ethers.js
- viem
- Standalone usage
import Web3 from "web3"
const web3 = new Web3(idWalletProvider)
import * as ethers from "ethers"
const provider = new ethers.providers.Web3Provider(idWalletProvider)
import { createWalletClient, custom } from "viem"
import { saigon } from "viem/chains"
const walletClient = createWalletClient({ chain, transport: custom(idWalletProvider) })
const accounts = await idWalletProvider.request<string[]>({ method: "eth_requestAccounts" })
if (accounts.length) {
mavisIdProvider.request<string>({ method: "eth_getBalance", params: [accounts[0], "latest"] })
}
Step 3. Authorize users
Authorizes a user with an existing Mavis ID account, returning an ID token and the user's wallet address. You can use either a popup or a redirect flow:
- Popup
- Redirect
import { authorize } from "@sky-mavis/mavis-id-sdk";
authorize({
clientId: "your-client-id", // Replace with your actual client ID
idOrigin: "your-id-origin" // Replace with your actual ID origin
});
Example:
import { authorize } from "@sky-mavis/mavis-id-sdk"
export const Authorize = async () => {
const clientId = "your-client-id";
const idOrigin = "https://id.skymavis.com";
try {
const result = await authorize({
clientId,
idOrigin,
});
console.log("Authorization result:", result);
} catch (error) {
console.error("Authorization failed:", error);
}
};
Authorize();
import { parseRedirectUrl, redirectAuthorize } from "@sky-mavis/mavis-id-sdk";
redirectAuthorize({
clientId: "your-client-id", // Replace with your actual client ID
idOrigin: "your-id-origin" // Replace with your actual ID origin
});
const result = parseRedirectUrl();
console.log("Redirect - Authorization Result:", result);
Example:
import { parseRedirectUrl, redirectAuthorize } from "@sky-mavis/mavis-id-sdk";
// Function signature example
const clientId = "your-client-id";
const idOrigin = "https://id.skymavis.com";
// Redirect authorization function
const handleRedirectAuthorize = () => {
redirectAuthorize({
clientId,
idOrigin,
});
};
// Parse redirect URL function
const handleParseRedirectUrl = () => {
try {
const result = parseRedirectUrl();
console.log("Redirect - Authorization Result:", result);
} catch (error) {
console.error("Failed to parse redirect URL:", error);
}
};
// Usage example
handleRedirectAuthorize();
handleParseRedirectUrl();
Parameters:
clientId: the client ID registered in the Mavis ID settings in the Developer Console.idOrigin: the base URL of the Mavis ID service. Usehttps://id.skymavis.comfor production andhttps://id.skymavis.onefor testing.
Returns a promise that resolves to an object containing:
accessToken: the ID token that contains encoded user information.address: the user's MPC wallet address.
Step 4. Validate the ID token
After receiving the ID token, validate it to ensure that the user has successfully authenticated. Then you can issue an access token to allow access to your server's resources. For more information, see Validate ID tokens.
Step 5. Interact with the wallet
After the user is authorized, you can interact with the wallet to send transactions, sign messages, and more. Find the examples in the playground repository.
Reference
FAQ
Where can I find the client ID?
To find your app's client ID, open the Developer Console, then click ID Service, and then in the Client credentials section, locate the CLIENT ID (APPLICATION ID) field.
Where can I find the chain ID?
The chain ID is 2020 for the Ronin mainnet and 2021 for the Saigon testnet.
Can I use the SDK to call a contract function?
Yes. The MavisIdWallet provider is compatible with the EIP-1193 standard. This means you can use the contract call functions provided by any JavaScript Ethereum interface library, such as Web3.js, Ethers.js, or viem. Refer to the respective library documentation for more information: