diff --git a/api-sdk-sidebar.js b/api-sdk-sidebar.js index 0c48f67e83f..28e252380fd 100644 --- a/api-sdk-sidebar.js +++ b/api-sdk-sidebar.js @@ -33,6 +33,7 @@ const sidebar = { items: [ "how-to/use-sdk/react-native", "how-to/use-sdk/pure-js", + "how-to/use-sdk/unity", ], }, "how-to/use-mobile", @@ -52,9 +53,10 @@ const sidebar = { label: "Concepts", link: { type: "generated-index" }, items: [ - "concepts/sdk", + "concepts/sdk-connections", "concepts/signing-methods", "concepts/onboarding-library", + "concepts/convenience-libraries", ], }, { diff --git a/api-sdk/assets/sdk-desktop-browser.gif b/api-sdk/assets/sdk-desktop-browser.gif new file mode 100644 index 00000000000..39c2b58f9e1 Binary files /dev/null and b/api-sdk/assets/sdk-desktop-browser.gif differ diff --git a/api-sdk/assets/sdk-mobile-browser.gif b/api-sdk/assets/sdk-mobile-browser.gif new file mode 100644 index 00000000000..d801aa2a800 Binary files /dev/null and b/api-sdk/assets/sdk-mobile-browser.gif differ diff --git a/api-sdk/assets/sdk-nodejs.gif b/api-sdk/assets/sdk-nodejs.gif new file mode 100644 index 00000000000..5059d52fa7c Binary files /dev/null and b/api-sdk/assets/sdk-nodejs.gif differ diff --git a/api-sdk/assets/sdk-react-native.gif b/api-sdk/assets/sdk-react-native.gif new file mode 100644 index 00000000000..84495e42f2c Binary files /dev/null and b/api-sdk/assets/sdk-react-native.gif differ diff --git a/api-sdk/concepts/convenience-libraries.md b/api-sdk/concepts/convenience-libraries.md new file mode 100644 index 00000000000..f5fe5f919cb --- /dev/null +++ b/api-sdk/concepts/convenience-libraries.md @@ -0,0 +1,16 @@ +# Convenience libraries + +Various convenience libraries exist for dapp developers. +Some of them simplify the creation of specific user interface elements, some entirely manage the +user account onboarding, and others give you a variety of methods for interacting with smart +contracts, for a variety of API preferences (for example, promises, callbacks, and strong types). + +The [MetaMask Ethereum provider API](../reference/provider-api.md) is very simple, and wraps +[Ethereum JSON-RPC](https://eth.wiki/json-rpc/API#json-rpc-methods) formatted messages, which is why +some developers use a convenience library for interacting with the provider, such as +[Ethers](https://www.npmjs.com/package/ethers), [web3.js](https://www.npmjs.com/package/web3), +[Truffle](https://www.trufflesuite.com/), and [Embark](https://framework.embarklabs.io/). +You can refer to those tools' documentation to interact with the provider. + +The provider API is all you need to create a full-featured web3 application, but if you need +higher-level abstractions than those provided by the API, we recommend using a convenience library. diff --git a/api-sdk/concepts/sdk-connections.md b/api-sdk/concepts/sdk-connections.md new file mode 100644 index 00000000000..d02e0576e11 --- /dev/null +++ b/api-sdk/concepts/sdk-connections.md @@ -0,0 +1,57 @@ +# MetaMask SDK connections + +You can [use MetaMask SDK](../how-to/use-sdk/index.md) to enable users to easily connect from your +dapp to the MetaMask browser extension and MetaMask Mobile. +When connecting to MetaMask Mobile, the SDK uses a secure [communication layer](#communication-layer), +and it's important to understand the [status of the connection](#connection-status). + +## Connection status + +### Paused connections + +Connections pause after MetaMask Mobile is in background (minimized) for 20 seconds. +This is to accommodate OS restrictions. + +When a connection pauses, all traffic to MetaMask Mobile pauses, and the SDK doesn't produce any +response until the user opens MetaMask Mobile again. +The SDK automatically deeplinks to MetaMask Mobile, so connections resume automatically. +If MetaMask Mobile is paused and the user completely closes MetaMask Mobile, the connection remains +paused and resumes when the user opens it again. + +Because of this, polling data from MetaMask Mobile may not work for long periods of time. + +### Cleared connections + +Connections clear if the user closes or refreshes your dapp, since MetaMask doesn't persist +connections on the dapp side. +This is for simplicity and security purposes. + +If the user completely closes MetaMask Mobile without [pausing the connection](#paused-connections) +first, MetaMask infers that the user isn't using the wallet and closes the connection. + +#### Close connections manually + +To close connections manually from MetaMask Mobile, go to **Settings > Experimental**, and select +**Clear MetaMask SDK connections**. + +## Communication layer + +The SDK uses elliptic curve integrated encryption scheme (ECIES) to communicate with MetaMask Mobile. +ECIES is a hybrid encryption scheme that combines the benefits of both symmetric and asymmetric encryption. +It's a secure method of exchanging encrypted messages between two parties. + +In ECIES, the sender (your dapp) generates a shared secret using the recipient's (MetaMask Mobile's) +public key and their own private key. +The shared secret is used to encrypt the message using a symmetric cipher (the SDK uses `AES-256-GCM`). +The encrypted message is then combined with a message authentication code (MAC) and sent to the recipient. + +MetaMask Mobile uses its private key and the dapp's public key to recreate the shared secret and +decrypt the message. +The MAC is used to verify the authenticity of the message. + +One of the main benefits of ECIES is that it allows the sender and recipient to exchange messages +without having to exchange a shared secret beforehand. +It also provides security against eavesdropping and tampering, since the shared secret is derived +from the sender's and recipient's private keys, which are both kept secret. + +![Sequence diagram](../assets/sdk-comm-diagram.svg) diff --git a/api-sdk/concepts/sdk.md b/api-sdk/concepts/sdk.md deleted file mode 100644 index 4f0ad9369b2..00000000000 --- a/api-sdk/concepts/sdk.md +++ /dev/null @@ -1,68 +0,0 @@ -# MetaMask SDK - -If you're developing a web application that users can access via a desktop or mobile browser, you -can [use MetaMask SDK](../how-to/use-sdk) to guide users to easily connect with MetaMask. - -If the user is on a desktop browser and doesn't have the MetaMask extension installed, a popup -appears that prompts users to either install the MetaMask extension or to connect with MetaMask -Mobile via a QR code. - -If on a mobile browser, the SDK automatically deeplinks into MetaMask Mobile (or prompt users to -install if they don't already have it) and once users accept the connection, they are -automatically redirected back to your web app. -This happens for all actions that need user approval. - -## Connections - -When connecting with MetaMask Mobile wallet, it's important to understand when connections get -paused, resumed and cleared. - -#### Paused connections - -Connections get paused after the MetaMask Mobile app is in background (minimized) for 20 seconds. -This is to accomodate OS restrictions, and it means that all traffic into MetaMask Mobile gets -paused and the SDK won't produce any response unless the MetaMask Mobile app is opened again. -The SDK automatically deeplinks into MetaMask Mobile so connections should be resumed automatically. -If MetaMask Mobile is in pause mode and the user completely closes the app, the connection is -maintained in paused mode until it's opened again. - -For this reason, polling data from the wallet may not work for long periods of time. - -#### Cleared connections - -Connections get cleared if the dapp is closed or refreshed (in the case of a browser) as MetaMask -doesn't persist connections on the dapp side. -This is for simplicity and for security purposes. -We believe that creating a connection should be very easy so there's no need to persist, but this -may change in the future. - -If the MetaMask Mobile app is completely closed without entering pause mode first, MetaMask infers -that the user isn't using the wallet and closes the connection. - -#### Close connections manually - -To close connections manually from the MetaMask Mobile app, go into **Settings > Experimental**. - -![Connections](../assets/sdk-clear-connections.png) - -## Communication layer - -The security layer is handled using elliptic curve integrated encryption scheme (ECIES). -ECIES is a hybrid encryption scheme that combines the benefits of both symmetric and asymmetric encryption. -It's a secure method of exchanging encrypted messages between two parties. - -In ECIES, the sender (for example, the dapp) generates a shared secret using the recipient's -(for example, MetaMask Mobile) public key and their own private key. -The shared secret is used to encrypt the message using a symmetric cipher (the SDK used `AES-256-GCM`). -The encrypted message is then combined with a message authentication code (`MAC`) and sent to the recipient. - -MetaMask Mobile uses its private key and the dapp's public key to recreate the shared secret and -decrypt the message. -The MAC is used to verify the authenticity of the message. - -One of the main benefits of ECIES is that it allows the sender and recipient to exchange messages -without having to exchange a shared secret beforehand. -It also provides security against eavesdropping and tampering, as the shared secret is derived from -the sender's and recipient's private keys, which are both kept secret. - -![Sequence diagram](../assets/sdk-comm-diagram.svg) diff --git a/api-sdk/how-to/migrate-api.md b/api-sdk/how-to/migrate-api.md index a401b8d4976..385298b36fc 100644 --- a/api-sdk/how-to/migrate-api.md +++ b/api-sdk/how-to/migrate-api.md @@ -52,7 +52,7 @@ MetaMask made the following breaking changes to the `window.ethereum` API: :::caution Pages no longer reload on chain changes Since we removed `window.web3`, MetaMask no longer automatically reloads the page on chain/network changes. -Please see [Handling the removal of `ethereum.autoRefreshOnNetworkChange`](#handling-the-removal-of-ethereumautorefreshonnetworkchange) +Please see [Handling the removal of `ethereum.autoRefreshOnNetworkChange`](#handle-the-removal-of-ethereumautorefreshonnetworkchange) for details. ::: diff --git a/api-sdk/how-to/use-sdk/index.md b/api-sdk/how-to/use-sdk/index.md index ec92804fbaf..2da18d75357 100644 --- a/api-sdk/how-to/use-sdk/index.md +++ b/api-sdk/how-to/use-sdk/index.md @@ -1,21 +1,88 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Use MetaMask SDK -[MetaMask SDK](../../concepts/sdk.md) currently supports JavaScript-based dapps. -It enables these dapps to easily connect with a MetaMask wallet client. +MetaMask SDK currently supports all JavaScript-based dapps and Unity gaming dapps. +It provides a reliable, secure, and seamless [connection](../../concepts/sdk-connections.md) from +your dapp to a MetaMask wallet client. + +The following instructions work for dapps based on standard JavaScript, React, Node.js, Electron, +and other web frameworks. +You can also see instructions for [React Native](react-native.md), [pure JavaScript](pure-js.md), +and [Unity gaming](unity.md) dapps. + +:::tip Coming soon +SDK support for Android native, iOS native, and Unreal Engine dapps is coming soon. +::: + +:::note +MetaMask SDK uses the [Ethereum provider](../../reference/provider-api.md) that developers are +already used to, so existing dapps work out of the box with the SDK. +::: + +## How it works + + + + +If a user accesses your web dapp on a desktop browser and doesn't have the MetaMask extension +installed, a popup appears that prompts the user to either install the MetaMask extension or connect +to MetaMask Mobile using a QR code. + +![SDK desktop browser example](../../assets/sdk-desktop-browser.gif) + +You can try the +[hosted test dapp with the SDK installed](https://c0f4f41c-2f55-4863-921b-sdk-docs.github.io/test-dapp-2/). +You can also see this +[React project example](https://github.com/MetaMask/examples/tree/main/metamask-with/metamask-sdk-create-react-app). + + + + +If a user accesses your web dapp on a mobile browser, the SDK automatically deeplinks to MetaMask +Mobile (or if the user doesn't already have it, prompts them to install it). +Once the user accepts the connection, they're automatically redirected back to your dapp. +This happens for all actions that need user approval. + +

+ +![SDK mobile browser example](../../assets/sdk-mobile-browser.gif) -The following instructions work for dapps based on standard JavaScript, React, NodeJS, Electron, and -other web frameworks. -MetaMask SDK also supports [React Native](react-native.md) and [pure JavaScript](pure-js.md) dapps. +

+ +You can try the +[hosted test dapp with the SDK installed](https://c0f4f41c-2f55-4863-921b-sdk-docs.github.io/test-dapp-2/). +You can also see this +[React project example](https://github.com/MetaMask/examples/tree/main/metamask-with/metamask-sdk-create-react-app). + +
+ + +When a user accesses your Node.js dapp, the SDK renders a QR code on the console which users can +scan with their MetaMask Mobile app. + +

+ +![SDK Node.js example](../../assets/sdk-nodejs.gif) + +

+ +
+
## Prerequisites -- MetaMask Mobile v5.8.1 or above +- An existing or [new project](../../get-started/set-up-dev-environment.md) set up +- [MetaMask Mobile](https://github.com/MetaMask/metamask-mobile) v5.8.1 or above - [Yarn](https://yarnpkg.com/getting-started/install) or [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) -## 1. Install the SDK +## Steps + +### 1. Install the SDK -Install the SDK using Yarn or npm: +In your project directory, install the SDK using Yarn or npm: ```bash yarn add @metamask/sdk @@ -23,13 +90,17 @@ or npm i @metamask/sdk ``` -## 2. Import the SDK +### 2. Import the SDK + +In your project script, add the following to import the SDK: ```javascript import MetaMaskSDK from '@metamask/sdk'; ``` -## 3. Instantiate the SDK +### 3. Instantiate the SDK + +Instantiate the SDK using any [options](../../reference/sdk-js-options.md): ```javascript const MMSDK = new MetaMaskSDK(options); @@ -37,14 +108,13 @@ const MMSDK = new MetaMaskSDK(options); const ethereum = MMSDK.getProvider(); // You can also access via window.ethereum ``` -See the [list of options](../../reference/sdk-js-options.md). +### 4. Use the SDK -## 4. Use the SDK +Use the SDK by calling any [provider API methods](../../reference/provider-api.md). +Always call [`eth_requestAccounts`](../../reference/rpc-api.md#eth_requestaccounts) using +[`ethereum.request()`](../../reference/provider-api.md#ethereumrequestargs) first, since it prompts +the installation or connection popup to appear. ```javascript ethereum.request({ method: 'eth_requestAccounts', params: [] }); ``` - -Always call `eth_requestAccounts` first, since it prompts the installation or connection popup to appear. - -See the [Ethereum provider API](../../reference/provider-api.md) for all methods. diff --git a/api-sdk/how-to/use-sdk/pure-js.md b/api-sdk/how-to/use-sdk/pure-js.md index c667da45c07..b16532378b4 100644 --- a/api-sdk/how-to/use-sdk/pure-js.md +++ b/api-sdk/how-to/use-sdk/pure-js.md @@ -4,8 +4,12 @@ title: Pure JavaScript # Use MetaMask SDK with pure JavaScript -If your project just uses pure JavaScript, you can import the SDK by putting a script on the head -section of your website: +You can import MetaMask SDK into your pure JavaScript dapp to enable your users to easily connect +with a MetaMask wallet client. +The SDK for pure JavaScript [works the same way](index.md#how-it-works) and has the +[same prerequisites](index.md#prerequisites) as for standard JavaScript and other web frameworks. + +To import, instantiate, and use the SDK, you can insert a script in the head section of your website: ```javascript @@ -26,3 +30,9 @@ section of your website: ... ``` + +You can configure the SDK using any [options](../../reference/sdk-js-options.md) and call any +[provider API methods](../../reference/provider-api.md). +Always call [`eth_requestAccounts`](../../reference/rpc-api.md#eth_requestaccounts) using +[`ethereum.request()`](../../reference/provider-api.md#ethereumrequestargs) first, since it prompts +the installation or connection popup to appear. diff --git a/api-sdk/how-to/use-sdk/react-native.md b/api-sdk/how-to/use-sdk/react-native.md index b1c35ebca8b..222b83c3f89 100644 --- a/api-sdk/how-to/use-sdk/react-native.md +++ b/api-sdk/how-to/use-sdk/react-native.md @@ -7,11 +7,39 @@ title: React Native You can import MetaMask SDK into your React Native dapp to enable your users to easily connect with their MetaMask Mobile wallet. +## How it works + +When a user accesses your mobile React Native dapp, the SDK automatically deeplinks to MetaMask +Mobile (or if the user doesn't already have it, prompts them to install it). +Once the user accepts the connection, they're automatically redirected back to your dapp. +This happens for all actions that need user approval. + +

+ +![SDK React Native example](../../assets/sdk-react-native.gif) + +

+ +You can download the +[React Native example](https://c0f4f41c-2f55-4863-921b-sdk-docs.github.io/downloads/reactNativeApp_v0.1.0.zip). +Install the example using `yarn setup` and run it using `yarn ios` or `yarn android`. + +## Prerequisites + +- A React Native project set up +- [MetaMask Mobile](https://github.com/MetaMask/metamask-mobile) v5.8.1 or above +- [Yarn](https://yarnpkg.com/getting-started/install) or + [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) + ## Install the SDK -Use [rn-nodeify](https://github.com/tradle/rn-nodeify) to install the SDK. +:::tip Coming soon +A `metamask-react-native-sdk` package that simplifies the installation of the SDK for React Native +dapps is coming soon. +::: -### 1. Install rn-nodeify +Use [`rn-nodeify`](https://github.com/tradle/rn-nodeify) to install the SDK. +In your project directory, install `rn-nodeify`: ```bash yarn add --dev rn-nodeify @@ -19,7 +47,7 @@ or npm i --dev rn-nodeify ``` -### 2. Install rn-nodeify libraries +Install the `rn-nodeify` libraries: ```bash yarn add react-native-crypto @@ -30,22 +58,23 @@ yarn add stream yarn add events ``` -### 3. Insert rn-nodeify post install script into `package.json` -> `"scripts"` +In your project's `package.json` file, insert the `rn-nodeify` command into the postinstall script: -```bash -"postinstall": "rn-nodeify --install 'crypto,process,stream,events' --hack" +```json title="package.json" +"scripts": { + ..., + "postinstall": "rn-nodeify --install 'crypto,process,stream,events' --hack" +} ``` -### 4. Import rn-nodeify shim.js - -rn-nodeify creates a shim.js file in your project root directory. -Import it in the root file of your application. +`rn-nodeify` creates a `shim.js` file in your project root directory. +Import it in the root file of your application: ```bash import './shim' ``` -### 5. Install react-native-background-timer +Install `react-native-background-timer`: ```bash yarn add react-native-background-timer @@ -53,23 +82,19 @@ yarn add react-native-background-timer cd ios && pod install && cd .. ``` -### 6. Install MetaMask SDK +Install MetaMask SDK: ```bash yarn add @metamask/sdk ``` -### 7. Run postinstall - -Run the postinstall script after everything is installed. +Run the postinstall script after everything is installed: ```bash yarn postinstall ``` -### 8. Install pods - -Finally, install the necessary pods that come with the libraries. +Finally, install the necessary pods that come with the libraries: ```bash cd ios && pod install && cd .. @@ -77,6 +102,8 @@ cd ios && pod install && cd .. ## Use the SDK +Import, instantiate, and use the SDK by adding something similar to the following to your project script: + ```javascript import MetaMaskSDK from '@metamask/sdk'; import { Linking } from 'react-native'; @@ -98,7 +125,13 @@ const ethereum = MMSDK.getProvider(); const accounts = await ethereum.request({ method: 'eth_requestAccounts' }); ``` -You can now use [EthersJS](https://docs.ethers.io/v5/getting-started/) with your React Native dapp: +You can configure the SDK using any [options](../../reference/sdk-js-options.md) and call any +[provider API methods](../../reference/provider-api.md). +Always call [`eth_requestAccounts`](../../reference/rpc-api.md#eth_requestaccounts) using +[`ethereum.request()`](../../reference/provider-api.md#ethereumrequestargs) first, since it prompts +the installation or connection popup to appear. + +You can use [EthersJS](https://docs.ethers.io/v5/getting-started/) with your React Native app: ```javascript const provider = new ethers.providers.Web3Provider(ethereum); @@ -111,15 +144,3 @@ const balance = await provider.getBalance(ethereum.selectedAddress); const balanceInETH = ethers.utils.formatEther(balance); // '0.182826475815887608' ``` - -:::note -The MetaMask team is creating a `metamask-react-native-sdk` package that will install all of this -automatically, making the installation much easier for React Native dapps. -::: - -## Examples - -View the [React Native dapp](https://recordit.co/FClppLgWzT) recording. - -View the [React Native example](https://c0f4f41c-2f55-4863-921b-sdk-docs.github.io/downloads/reactNativeApp_v0.1.0.zip). -Install the example using `yarn setup` and run it using `yarn ios` or `yarn android`. diff --git a/api-sdk/how-to/use-sdk/unity.md b/api-sdk/how-to/use-sdk/unity.md new file mode 100644 index 00000000000..ab1c8f0c567 --- /dev/null +++ b/api-sdk/how-to/use-sdk/unity.md @@ -0,0 +1,226 @@ +--- +title: Unity gaming +--- + +# Use MetaMask SDK with Unity + +You can import MetaMask SDK into your Unity game to enable users to easily connect to their MetaMask +Mobile wallet. +The MetaMask Unity SDK supports macOS, Windows, Linux, IOS, Android, and WebGL. + +## How it works + +The SDK renders a QR code in the UI using a dedicated prefab which players can scan with their +MetaMask Mobile app. +It also supports deeplinking on mobile platforms. +You can use all the [provider API methods](../../reference/provider-api.md) right from your game. + +## Video demo + +The following video demonstrates how to install and use the MetaMask Unity SDK. + +

+ +

+ +## Steps + +### 1. Install the SDK for Unity + +To install the module, first download the +[Unity SDK Package](https://drive.google.com/u/0/uc?id=1ArTJvKIZXK5vkUOM3cgr0t0NspenWRU9&export=download). + +Then, go to the menu > **Package Manager**. +Select **My Assets**, **MetaMask Unity SDK**, and **Install**. +You should see the MetaMask SDK package listed in the project packages and be able to interface +with it and its examples in the scene. + +You also need to install [TextMeshPro](https://docs.unity3d.com/Manual/com.unity.textmeshpro.html). +If you don't have TextMeshPro installed, the Unity editor automatically prompts you to install it. + +### 2. Initialize MetaMask + +The main class you interface with is called `MetaMaskWallet`. +It handles the connection to the user's wallet, as well as processing the requests to it using a +socket.io implementation. + +To use it inside Unity, you must attach the component called `MetaMaskUnity` to a game object within +the editor. +This component is a singleton and you can use its `Instance` property to access the wallet instance. +You first must initialize by doing one of the following: + +- Manually call `Initialize()`: + + ```csharp + MetaMaskUnity.Instance.Initialize(); + ``` + +- Check **Initialize On Start** on the component within the editor. + +This initializes the wallet instance, making it accessible from `MetaMaskUnity.Instance.Wallet`. +You can now make calls to the user's wallet using [provider API methods](../../reference/provider-api.md). + +### 3. Connect to MetaMask + +Once the wallet is prepared and initialized, you can connect to MetaMask. +Call the `Connect()` method on the wallet instance as follows: + +```csharp +var wallet = MetaMaskUnity.Instance.Wallet; +wallet.Connect(); +``` + +You can also subscribe to the `OnWalletConnected` callback on the wallet instance to be notified +once the wallet is connected: + +```csharp +wallet.WalletConnected += OnWalletConnected; + +void OnWalletConnected(object sender, EventArgs e) { + Debug.Log("Wallet is connected"); +} +``` + +You can also use the `Connect()` method from `MetaMaskUnity` that delegates the call to the wallet +instance: + +```csharp +MetaMaskUnity.Instance.Connect(); +``` + +There are a variety of sample buttons included inside the package that call this method when clicked. +These are provided as a convenience to get started quickly with your project. +Once the connection request is made, a QR code is generated, and based on the transport you're using +(`Unity UI` by default), either a new Canvas that contains the QR code is spawned or the +`MetaMaskUnityUIQRImage` generates the QR code when the connection is requested. + +If you want to use the latter, add an instance of the `MetaMaskUnityUIQRImage` component to the +scene with its fields provided. +The transport field is also required if you want to use it isolated from the canvas that is spawned +by the transport, then it generates the QR code for you. + +### 4. Use MetaMask + +Once the wallet is authorized, you can make requests to it. +The wallet is authorized when the buttons become interactable or the `WalletAuthorized` event is fired: + +```csharp +var wallet = MetaMaskUnity.Instance.Wallet; +wallet.WalletAuthorized += OnWalletAuthorized; + +void OnWalletAuthorized(object sender, EventArgs e) { + Deebug.Log("Wallet is authorized"); +} +``` + +You can call any Ethereum request on the wallet using `wallet.Request(myRequest)`. +The following is a sample transaction request: + +```csharp +var wallet = MetaMaskUnity.Instance.Wallet; +var transactionParams = new MetaMaskTranscation +{ + To = "0xd0059fB234f15dFA9371a7B45c09d451a2dd2B5a", + From = MetaMaskUnity.Instance.Wallet.SelectedAddress, + Value = "0x0" +}; + +var request = new MetaMaskEthereumRequest +{ + Method = "eth_sendTransaction", + Parameters = new MetaMaskTranscation[] { transactionParams } +}; +await wallet.Request(request); +``` + +### 5. Configure MetaMask + +You can customize the default configuration or create your own configuration. + +Edit the default configuration by doing one of the following: + +- Navigate to the **Window > MetaMask > Setup** menu item. +- Open the `MetaMaskConfig` asset in the project window. + +Edit the fields and save the changes. + +Create a new configuration by right-clicking on the project window and navigating to +**MetaMask > Config**. +Name the new configuration and use it when initializing the `MetaMaskUnity` instance. + +## API + +The following is an overview of the APIs from the most important classes. + +### MetaMaskUnity + +This is a singleton class that you can use to access the `MetaMaskWallet` instance, which is +specific to Unity. + +#### `Instance` + +This is the singleton instance of the `MetaMaskUnity` class that is lazy-loaded when you access it +for the first time. + +#### `Initialize` + +This method initializes the `MetaMaskWallet` instance and makes it accessible via the `Wallet` property. +You can also pass extra options and parameters to it to customize the wallet instance: + +```csharp +// Initialize using default settings +MetaMaskUnity.Instance.Initialize(); + +// Initialize using custom transport and socket provider +var transport = new MyCustomTransport(); +var socketProvider = new MyCustomSocketProvider(); +MetaMaskUnity.Instance.Initialize(transport, socketProvider); + +// Initialize using custom config, transport and socket provider +var config = myMetaMaskConfig; +var transport = new MyCustomTransport(); +var socketProvider = new MyCustomSocketProvider(); +MetaMaskUnity.Instance.Initialize(config, transport, socketProvider); +``` + +#### `SaveSession` + +This method saves the current session to the persistent storage. +This is useful when you want to save the session and restore it later. +This is automatically called when the application quits, but you can also manually call it. + +#### `LoadSession` + +This method loads the session from the persistent storage. +This is useful when you want to restore the session after the application quits. +This is automatically called when the application starts, but you can also manually call it. + +### MetaMaskWallet + +#### `Connect` + +This method connects to the MetaMask app. +It renders a generated QR code in the user interface for your users to scan with MetaMask Mobile. +After the user scans this QR code, a connect screen appears in MetaMask Mobile where the user can +approve the connection with your game application. + +#### `Disconnect` + +This method disconnects the user that is connected from the MetaMask app session. + +#### `Request` + +This method sends a request to MetaMask. +You can use it to call any [provider API method](../../reference/provider-api.md). + +## Package structure + +| File or directory | Contents | +| ------------------------ | ---------------------------------------------- | +| `Documentation` | Documentation and link to online documentation | +| `Editor` | Editor-only code such as Setup GUI windows, data persistence for SDK settings | +| `Plugins` | Plugins needed by the package (the ECIES Platform runtime libraries and core SDK Codebase) | +| `Runtime` | Main scripts for the SDK that are environment-agnostic, including the C# scripts that provide the base implementation of the SDK | +| `Samples` | Test application scene that can be used as a referral for your project, including modal popups and dynamic UI scaling | +| `LICENSE.md` | Package license | +| `Third Party Notices.md` | Third party notices | diff --git a/api-sdk/index.md b/api-sdk/index.md index ac67f69b844..eafd2a8c67f 100644 --- a/api-sdk/index.md +++ b/api-sdk/index.md @@ -4,63 +4,35 @@ title: Introduction # Integrate with MetaMask using the API and SDK -You can integrate your dapp with MetaMask using the -[MetaMask Ethereum provider API](#metamask-ethereum-provider-api) directly, -[MetaMask SDK](#metamask-sdk), or a [convenience library](#convenience-libraries). +Integrate your dapp with MetaMask using the [MetaMask Ethereum provider API](reference/provider-api.md), +which enables your dapp to interact with its users' Ethereum accounts. +We recommend using [MetaMask SDK](how-to/use-sdk) to easily enable your users to connect to their +MetaMask wallet from any platform. -## MetaMask Ethereum provider API +Get started by [setting up your development environment](get-started/set-up-dev-environment.md). -MetaMask injects a global [Ethereum provider API](reference/provider-api.md) into websites visited -by its users at `window.ethereum`. -This API allows websites to request users' Ethereum accounts, read data from blockchains the user is -connected to, and suggest that the user sign messages and transactions. -The presence of the provider object indicates an Ethereum user. +## What is the MetaMask Ethereum provider API? -The Ethereum provider API is specified by [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193). +The [MetaMask Ethereum provider API](reference/provider-api.md) is an API that MetaMask injects into +websites visited by MetaMask users. +Your dapp can use this API to request users' Ethereum accounts, read data from blockchains the user +is connected to, and suggest that the user sign messages and transactions. -[Get started using the API.](get-started/set-up-dev-environment.md) +## What is MetaMask SDK? -## MetaMask SDK +MetaMask SDK is a library that provides a reliable, secure, and seamless +[connection](concepts/sdk-connections.md) from your dapp to the MetaMask browser extension and +MetaMask Mobile. +You can install the SDK into your dapp to enable your users to easily connect to a MetaMask wallet +client from multiple platforms (web, desktop, and mobile). -MetaMask SDK provides an easy-to-use library for a reliable, secure, and seamless connection for -your dapp to the MetaMask extension and MetaMask Mobile. +For example, for dapps running on a desktop browser, MetaMask SDK checks if the MetaMask extension +is installed. +If MetaMask isn't installed, the SDK prompts the user to install it or connect to their MetaMask +Mobile wallet using a QR code. +For dapps running on a mobile browser, MetaMask SDK automatically deeplinks to the user's MetaMask +Mobile wallet to make the connection. -Our goal is to enable delightful user experiences for your apps that are built for diverse -communities of users and use cases, and compatible with various platforms (mobile apps, desktop -apps, and web apps). +[Get started using the SDK](how-to/use-sdk/index.md). -MetaMask SDK is a library that can be installed by developers in their projects and will -automatically guide their users to easily connect with a MetaMask wallet client. - -:::tip -The MetaMask SDK instance returns the [`ethereum` web3 provider](reference/provider-api.md) that -developers are already used to, so existing dapps work out of the box with the SDK! -::: - -[Get started using MetaMask SDK.](how-to/use-sdk/index.md) - -### Example use cases - -- Dapps running on a desktop browser: MetaMask SDK checks if the MetaMask wallet browser extension - is available and, if not, it prompts the user to install it or connect via QR code with their - MetaMask Mobile wallet. -- Native mobile applications: MetaMask SDK automatically deeplinks to the user's MetaMask Mobile - wallet to make the connection. - -## Convenience libraries - -Convenience libraries exist for a variety of reasons. - -Some of them simplify the creation of specific user interface elements, some entirely manage the -user account onboarding, and others give you a variety of methods for interacting with smart -contracts, for a variety of API preferences (for example, promises, callbacks, and strong types). - -The provider API itself is very simple, and wraps -[Ethereum JSON-RPC](https://eth.wiki/json-rpc/API#json-rpc-methods) formatted messages, which is why -developers usually use a convenience library for interacting with the provider, such as -[Ethers](https://www.npmjs.com/package/ethers), [web3.js](https://www.npmjs.com/package/web3), -[Truffle](https://www.trufflesuite.com/), and [Embark](https://framework.embarklabs.io/). -You can refer to those tools' documentation to interact with the provider. - -The provider API is all you need to create a full-featured web3 application, but if you need -higher-level abstractions than those provided by the API, we recommend using a convenience library. +If you have questions about the SDK, you can join the [MetaMask SDK Discord](https://discord.gg/N3jSkZbYm6). diff --git a/api-sdk/reference/provider-api.md b/api-sdk/reference/provider-api.md index 6575cf834ce..8f1b782ba6e 100644 --- a/api-sdk/reference/provider-api.md +++ b/api-sdk/reference/provider-api.md @@ -5,9 +5,9 @@ This API allows websites to request users' Ethereum accounts, read data from blo connected to, and suggest that the user sign messages and transactions. The presence of the provider object indicates an Ethereum user. We recommend using [`@metamask/detect-provider`](https://npmjs.com/package/@metamask/detect-provider) -to detect our provider, on any platform or browser. +to detect the provider, on any platform or browser. -The Ethereum JavaScript provider API is specified by [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193). +The Ethereum provider API is specified by [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193). ```javascript // This function detects most providers injected at window.ethereum diff --git a/api-sdk/reference/sdk-js-options.md b/api-sdk/reference/sdk-js-options.md index b2eeed11dcd..fa75036718e 100644 --- a/api-sdk/reference/sdk-js-options.md +++ b/api-sdk/reference/sdk-js-options.md @@ -1,7 +1,7 @@ -# MetaMask SDK JavaScript options +# MetaMask JavaScript SDK options -The JavaScript version of the MetaMask SDK takes several options. -For example: +The JavaScript version of [MetaMask SDK](../how-to/use-sdk/index.md) takes several options. +For example, you can specify options as follows: ```javascript const options = { @@ -14,27 +14,27 @@ const MMSDK = new MetaMaskSDK(options); The following table shows the full list of options: -| Option name | Type | Default value | Description | -| ------------------------------ | :--------------------------------------------: | :-----------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `dappMetadata` | `{name: "My Dapp", url: "https://mydapp.com"}` | `undefined` | Only required for non-web dapps (for example, React Native and Unity). | -| `injectProvider` | `boolean` | `true` | Doesn't inject in NodeJS or React Native since the window object is unavailable. | -| `forceInjectProvider` | `boolean` | `false` | Forces injection even if another provider is already present on the window object. | -| `forceDeleteProvider` | `boolean` | `false` | Forces deletion of a provider that exists on a window. | -| `checkInstallationImmediately` | `boolean` | `false` | The SDK checks if MetaMask is installed when a call to `eth_requestAccounts` is made. When `true`, it checks before any call is made. | -| `checkInstallationOnAllCalls` | `boolean` | `false` | Normally checked when a call to `eth_requestAccounts` is made. When `true`, it checks on all calls. | -| `shouldShimWeb3` | `boolean` | `true` | Set as `true` if `window.web3` should be shimmed for legacy compatibility purposes. See [more information](../how-to/migrate-api.md#replace-windowweb3) | +| Option name | Type | Default value | Description | +| ------------------------------ | :--------------------------------------------: | :-----------: | -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `dappMetadata` | `{name: "My Dapp", url: "https://mydapp.com"}` | `undefined` | Only required for non-web dapps (for example, React Native and Unity). | +| `injectProvider` | `boolean` | `true` | Doesn't inject in Node.js or React Native since the window object is unavailable. | +| `forceInjectProvider` | `boolean` | `false` | Forces injection even if another provider is already present on the window object. | +| `forceDeleteProvider` | `boolean` | `false` | Forces deletion of a provider that exists on a window. | +| `checkInstallationImmediately` | `boolean` | `false` | The SDK checks if MetaMask is installed when a call to `eth_requestAccounts` is made. When `true`, it checks before any call is made. | +| `checkInstallationOnAllCalls` | `boolean` | `false` | Normally checked when a call to `eth_requestAccounts` is made. When `true`, it checks on all calls. | +| `shouldShimWeb3` | `boolean` | `true` | Set as `true` if `window.web3` should be shimmed for [legacy compatibility purposes](../how-to/migrate-api.md#replace-windowweb3). | | `preferDesktop` | `boolean` | `false` | For a web dapp running on a desktop browser without a MetaMask extension, the SDK gives the option to connect with a MetaMask Mobile wallet via a QR code. When `true`, the SDK guides the user to install the MetaMask extension instead. | -| `openDeeplink` | `(deeplinkUrl: string) => void` | `undefined` | Platforms open deeplinks differently. For example, web: `window.open` versus React Native: `Linking.open`. This function retrieves the deeplink URL and allows developers to customize how it opens. | -| `getUniversalLink` | `() => string` | `undefined` | Get the universal link that is presented on the QR Code (web) and deeplinks (mobile). This makes it easier to enable users to connect with backend code. | -| `communicationLayerPreference` | `"socket" or "webrtc"` | `socket` | Defines the communication library that the dapp and MetaMask wallet use to communicate with each other. Waku or another similar decentralized communication layer solution coming soon. | -| `webRTCLib` | `WebRTC Lib` | `undefined` | Not installed on the SDK by default. Check the React Native section to see how to install it. | -| `WalletConnectInstance` | `WalletConnect Lib` | `undefined` | Another way of connecting a dapp to MetaMask. Not installed by default. Check [here](https://docs.walletconnect.com/) on how to install it. | -| `forceRestartWalletConnect` | `boolean` | `false` | Set `forceRestartWalletConnect` to `true` to kill the previous WalletConnect session and start another one. | -| `transports` | `['websocket', 'polling']` | `undefined` | Used to set the preference on socket.io transports to 'use'. Check the socket.io [documentation](https://socket.io/docs/v4/) for more details. | -| `timer` | `BackgroundTimer` | `undefined` | Used by React Native apps to keep the app alive while in the background using `react-native-background-timer` | -| `enableDebug` | `boolean` | `true` | Enables/disables the sending of debugging information to the `socket.io` server. The default is `true` for the beta version of the SDK. The default is `false` in production versions. | +| `openDeeplink` | `(deeplinkUrl: string) => void` | `undefined` | Platforms open deeplinks differently. For example, web: `window.open` versus React Native: `Linking.open`. This function retrieves the deeplink URL and allows developers to customize how it opens. | +| `getUniversalLink` | `() => string` | `undefined` | Get the universal link that is presented on the QR Code (web) and deeplinks (mobile). This makes it easier to enable users to connect with backend code. | +| `communicationLayerPreference` | `"socket" or "webrtc"` | `socket` | Defines the communication library that the dapp and MetaMask wallet use to communicate with each other. Waku or another similar decentralized communication layer solution coming soon. | +| `webRTCLib` | `WebRTC Lib` | `undefined` | Not installed on the SDK by default. | +| `WalletConnectInstance` | `WalletConnect Lib` | `undefined` | Connect a dapp to MetaMask using [WalletConnect](https://docs.walletconnect.com/). Not installed by default. | +| `forceRestartWalletConnect` | `boolean` | `false` | Set `forceRestartWalletConnect` to `true` to kill the previous WalletConnect session and start another one. | +| `transports` | `['websocket', 'polling']` | `undefined` | Used to set the preference on [socket.io](https://socket.io/docs/v4/) transports to `use`. | +| `timer` | `BackgroundTimer` | `undefined` | Used by React Native dapps to keep the dapp alive while using `react-native-background-timer` in the background | +| `enableDebug` | `boolean` | `true` | Enables/disables the sending of debugging information to the socket.io server. The default is `true` for the beta version of the SDK. The default is `false` in production versions. | :::tip -If your project is a web app and `injectProvider` is `true`, then the `ethereum` object should be +If your project is a web dapp and `injectProvider` is `true`, then the `ethereum` object should be available in `window.ethereum`. ::: diff --git a/docusaurus.config.js b/docusaurus.config.js index e819a055144..3f796080c77 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -66,8 +66,14 @@ const config = { themeConfig: /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ + docs: { + sidebar: { + hideable: true, + }, + }, navbar: { - title: "MetaMask Docs", + title: "MetaMask docs", + hideOnScroll: true, logo: { alt: "My Site Logo", src: "img/metamask-fox.svg", @@ -89,6 +95,7 @@ const config = { footer: {}, prism: { theme: codeTheme, + additionalLanguages: ["csharp"], }, }), };