Merge branch 'main' into add-listen

docs/whats-new.md

@@ -9,10 +9,15 @@ The latest major MetaMask documentation updates are listed by the month they wer
 For a comprehensive list of recent product changes, visit the "Release Notes" section at the bottom
 of the [MetaMask developer page](https://metamask.io/developer/).
 
-## April 2024
+## May 2024
 
 - Documented [provider API methods for removing event listeners](/wallet/reference/provider-api/#remove-event-listeners).
   ([#1288](https://github.com/MetaMask/metamask-docs/pull/1288))
+
+## April 2024
+
+- Documented [Snaps notifications](/snaps/features/notifications).
+  ([#1292](https://github.com/MetaMask/metamask-docs/pull/1292))
 - Moved Snaps-specific Wallet API methods from the
   [Wallet JSON-RPC API reference](/wallet/reference/json-rpc-api) to the
   [Snaps reference](/snaps/reference/wallet-api-for-snaps).

snaps/features/custom-ui/index.md

@@ -77,9 +77,6 @@ await snap.request({
 
 ### `button`
 
-:::flaskOnly
-:::
-
 Outputs a button that the user can select.
 For use in [interactive UI](interactive-ui.md).
 
@@ -179,9 +176,6 @@ module.exports.onHomePage = async () => {
 
 ### `form`
 
-:::flaskOnly
-:::
-
 Outputs a form for use in [interactive UI](interactive-ui.md).
 
 #### Parameters
@@ -296,9 +290,6 @@ module.exports.onHomePage = async () => {
 
 ### `input`
 
-:::flaskOnly
-:::
-
 Outputs an input component for use in [interactive UI](interactive-ui.md).
 
 #### Parameters

snaps/features/custom-ui/interactive-ui.md

@@ -1,15 +1,10 @@
 ---
 description: Display and update interactive user interfaces.
 sidebar_position: 1
-sidebar_custom_props:
-  flask_only: true
 ---
 
 # Interactive UI
 
-:::flaskOnly
-:::
-
 You can display interactive user interface (UI) components.
 Interactive UI is an extension of [custom UI](index.md).
 It allows interfaces returned from [`snap_dialog`](../../reference/snaps-api.md#snap_dialog),

snaps/features/notifications.md

@@ -0,0 +1,73 @@
+---
+description: Notify users directly in MetaMask, or natively in their OS.
+sidebar_position: 9
+---
+
+# Notifications
+
+You can display notifications directly in MetaMask or natively in a user's operating system (OS)
+using the [`snap_notify`](../reference/snaps-api.md#snap_notify) API method.
+
+## Steps
+
+### 1. Get permission to notify users
+
+Request the [`snap_notify`](../reference/snaps-api.md#snap_notify) permission.
+Add the following to your Snap's manifest file:
+
+```json title="snap.manifest.json"
+"initialPermissions": {
+  "snap_notify": {}
+}
+```
+
+### 2. Create a notification
+
+Create a notification by calling [`snap_notify`](../reference/snaps-api.md#snap_notify), which takes
+a notification `type` and `message`.
+Specify `type: "inApp"` to display the notification in the MetaMask UI, or `type: "native"` to
+display the notification in the user's OS.
+
+:::note
+We recommend using `type: "inApp"` because there's no guarantee that native notifications are
+displayed to the user.
+You can also call `snap_notify` twice, which each notification type, to trigger both an in-app and
+native notification.
+:::
+
+The following example displays a notification in MetaMask, with the message "Hello, world!":
+
+```javascript title="index.js"
+await snap.request({
+  method: "snap_notify",
+  params: {
+    type: "inApp",
+    message: "Hello, world!",
+  },
+});
+```
+
+<div class="row">
+    <div class="column">
+        <img src={require("../assets/notifications-1.png").default} width="250px" alt="Notification alert" style={{border: '1px solid #DCDCDC'}} />
+    </div>
+    <div class="column">
+        <img src={require("../assets/notifications-2.png").default} width="300px" alt="Notification message" style={{border: '1px solid #DCDCDC'}} />
+    </div>
+</div>
+
+:::info Notification rate limits
+Each Snap can trigger up to:
+
+- Five in-app notifications per minute.
+- Two native notifications per five minutes.
+:::
+
+## Example
+
+See the
+[`@metamask/notifications-example-snap`](https://github.com/MetaMask/snaps/tree/main/packages/examples/packages/notifications)
+package for a full example of implementing notifications using
+[`snap_notify`](../reference/snaps-api.md#snap_notify).
+This example exposes a [custom JSON-RPC API](../learn/about-snaps/apis.md#custom-json-rpc-apis) for
+dapps to display in-app and native notifications.

snaps/features/signature-insights.md

@@ -1,6 +1,6 @@
 ---
 description: Provide insights to your users in MetaMask's signature confirmation flow.
-sidebar_position: 9
+sidebar_position: 10
 sidebar_custom_props:
   flask_only: true
 ---

snaps/features/static-files.md

@@ -1,6 +1,6 @@
 ---
 description: Include and retrieve static files in the Snap bundle.
-sidebar_position: 10
+sidebar_position: 11
 ---
 
 # Static files

snaps/index.mdx

@@ -32,9 +32,9 @@ The following Snaps features are available in the stable version of MetaMask:
     },
     {
       icon: require("./assets/features/notifications.png").default,
-      href: "reference/snaps-api#snap_notify",
+      href: "features/notifications",
       title: "Notifications",
-      description: "Notify users directly in MetaMask, or in their OS."
+      description: "Notify users directly in MetaMask, or natively in their OS."
     },
     {
       icon: require("./assets/features/state.png").default,
@@ -66,6 +66,12 @@ The following Snaps features are available in the stable version of MetaMask:
       title: "Custom UI",
       description: "Display custom UI in MetaMask using a set of pre-defined components."
     },
+    {
+      icon: require("./assets/features/custom-ui.png").default,
+      href: "features/custom-ui/interactive-ui",
+      title: "Interactive UI",
+      description: "Display interactive UI in MetaMask that can be updated dynamically."
+    },
     {
       icon: require("./assets/features/network.png").default,
       href: "reference/permissions#endowmentnetwork-access",
@@ -117,13 +123,6 @@ the canary distribution of MetaMask:
       description: "Add extra friction to the transaction flow if a transaction looks risky.",
       flaskOnly: true
     },
-    {
-      icon: require("./assets/features/custom-ui.png").default,
-      href: "features/custom-ui/interactive-ui",
-      title: "Interactive UI",
-      description: "Display interactive UI in MetaMask using a set of pre-defined components.",
-      flaskOnly: true
-    },
     {
       icon: require("./assets/features/signature-insights.png").default,
       href: "features/signature-insights",

snaps/reference/snaps-api.md

@@ -833,25 +833,16 @@ await snap.request({
 
 ## `snap_notify`
 
-Displays a notification in MetaMask or natively in the browser.
+Displays a [notification](../features/notifications.md) in MetaMask or natively in the OS.
 Snaps can trigger a short notification text for actionable or time sensitive information.
 
-:::info Notification rate limits
-The ability for Snaps to trigger notifications is rate-limited to:
-
-- 2 native notifications per 5 minutes per Snap.
-- 5 in-app notifications per minute per Snap.
-:::
-
 #### Parameters
 
 An object containing the contents of the notification:
 
-- `type` - The notification type.
-  Specify `inApp` to display the notification in the MetaMask UI, and `native` to display the
-  notification in the browser.
-  We recommend using `inApp` because there's no guarantee that native notifications are displayed to
-  the user.
+- `type` - The notification type (`"inApp"` or `"native"`).
+  We recommend using `type: "inApp"` because there's no guarantee that native notifications are
+  displayed to the user.
 - `message` - A message to show in the notification.
 
 #### Example
@@ -873,9 +864,6 @@ These methods do not require requesting permission in the Snap manifest file.
 
 ### `snap_createInterface`
 
-:::flaskOnly
-:::
-
 Creates an interactive interface for use in [interactive UI](../features/custom-ui/interactive-ui.md).
 
 #### Parameters
@@ -916,9 +904,6 @@ await snap.request({
 
 ### `snap_getInterfaceState`
 
-:::flaskOnly
-:::
-
 Gets the state of an interactive interface by its ID.
 For use in [interactive UI](../features/custom-ui/interactive-ui.md).
 
@@ -983,9 +968,6 @@ console.log(state);
 
 ### `snap_updateInterface`
 
-:::flaskOnly
-:::
-
 Updates an interactive interface.
 For use in [interactive UI](../features/custom-ui/interactive-ui.md).