Edit/document how-tos and reference

api-sdk/concepts/convenience-libraries.md

@@ -15,4 +15,7 @@ some developers use a convenience library for interacting with the provider, suc
 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.
+higher-level abstractions than those provided by the API, we recommend using a convenience library.
+
+## MetaMask SDK and WalletConnect
+

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,60 +1,119 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # Use MetaMask SDK
 
-[MetaMask SDK](../../concepts/sdk-connections.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 apps and Unity gaming apps.
+It enables these apps to easily connect with a MetaMask wallet client.
 
-The following instructions work for dapps based on standard JavaScript, React, NodeJS, Electron, and
+The following instructions work for apps based on standard JavaScript, React, Node.js, Electron, and
 other web frameworks.
-MetaMask SDK also supports [React Native](react-native.md), [pure JavaScript](pure-js.md), and
-[Unity gaming](unity.md) dapps.
+You can also see instructions for [React Native](react-native.md), [pure JavaScript](pure-js.md),
+and [Unity gaming](unity.md) apps.
 
-:::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!
+:::tip Coming soon
+SDK support for Android native apps, iOS native apps, and Unreal Engine is coming soon.
 :::
 
 :::note
-SDK support for Android native apps, iOS native apps, and Unreal Engine is coming soon.
+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 app 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 app 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 web app.
+This happens for all actions that need user approval.
+
+<p align="center">
+
+![SDK mobile browser example](../../assets/sdk-mobile-browser.gif)
+
+</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 app, 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 app 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.

api-sdk/how-to/use-sdk/react-native.md

@@ -4,22 +4,50 @@ title: React Native
 
 # Use MetaMask SDK with React Native
 
-You can import MetaMask SDK into your React Native dapp to enable your users to easily connect
+You can import MetaMask SDK into your React Native app to enable your users to easily connect
 with their MetaMask Mobile wallet.
 
+## How it works
+
+When a user accesses your mobile React Native app, 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 app.
+This happens for all actions that need user approval.
+
+<p align="center">
+
+![SDK React Native example](../../assets/sdk-react-native.gif)
+
+</p>
+
+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
+apps 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
 or
 npm i --dev rn-nodeify
 ```
 
-### 2. Install rn-nodeify libraries
+Install the `rn-nodeify` libraries:
 
 ```bash
 yarn add react-native-crypto
@@ -30,53 +58,52 @@ 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
 
 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 ..
 ```
 
 ## 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);
@@ -112,14 +145,6 @@ 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`.