Merge pull request MetaMask#22 from MetaMask/5-sdk

Improve SDK documentation

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",
       ],
     },
     {

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.

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)

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.
 :::
 

api-sdk/how-to/use-sdk/index.md

@@ -1,50 +1,120 @@
+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
+
+<Tabs>
+<TabItem value="desktop" label="Desktop browser">
+
+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).
+
+</TabItem>
+<TabItem value="mobile" label="Mobile browser">
+
+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.
+
+<p align="center">
+
+![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.
+</p>
+
+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).
+
+</TabItem>
+<TabItem value="nodejs" label="Node.js">
+
+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.
+
+<p align="center">
+
+![SDK Node.js example](../../assets/sdk-nodejs.gif)
+
+</p>
+
+</TabItem>
+</Tabs>
 
 ## 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
 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);
 
 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.

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
 <head>
@@ -26,3 +30,9 @@ section of your website:
 ...
 </head>
 ```
+
+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.