Document Snaps lifecycle hooks

docs/whats-new.md

@@ -11,6 +11,8 @@ of the [MetaMask developer page](https://metamask.io/developer/).
 
 ## April 2024
 
+- Documented [Snaps lifecycle hooks](/snaps/features/lifecycle-hooks).
+  ([#1274](https://github.com/MetaMask/metamask-docs/pull/1274))
 - Documented [Snaps cron jobs](/snaps/features/cron-jobs).
   ([#1271](https://github.com/MetaMask/metamask-docs/pull/1271))
 - Updated [how to connect to MetaMask](/wallet/how-to/connect) with vanilla TypeScript and React

snaps/features/lifecycle-hooks.md

@@ -0,0 +1,87 @@
+---
+sidebar_position: 5
+description: Call an action when your Snap is installed or updated.
+---
+
+# Lifecycle hooks
+
+You can implement lifecycle hooks to automatically run an action, such as displaying a dialog or
+notification, when a user installs or updates your Snap.
+
+## Steps
+
+### 1. Request permission to implement lifecycle hooks
+
+Request the [`endowment:lifecycle-hooks`](../reference/permissions.md#endowmentlifecycle-hooks)
+permission.
+Add the following to your Snap's manifest file:
+
+```json title="snap.manifest.json"
+"initialPermissions": {
+  "endowment:lifecycle-hooks": {}
+}
+```
+
+### 2. Run an action on installation
+
+To run an action when a user installs your Snap, expose the
+[`onInstall`](../reference/entry-points.md#oninstall) entry point and implement the action.
+For example, you can use `onInstall` to perform any initialization that is required upon installation.
+
+The following example displays an [alert dialog](../reference/snaps-api.md#alert-dialog) upon installation:
+
+```typescript title="index.ts"
+import type { OnInstallHandler } from "@metamask/snaps-sdk";
+import { heading, panel, text } from "@metamask/snaps-sdk";
+
+export const onInstall: OnInstallHandler = async () => {
+  await snap.request({
+    method: "snap_dialog",
+    params: {
+      type: "alert",
+      content: panel([
+        heading("Installation successful"),
+        text(
+          "To use this Snap, visit the companion dapp at [metamask.io](https://metamask.io).",
+        ),
+      ]),
+    },
+  });
+};
+```
+
+### 3. Run an action on update
+
+To run an action when a user updates your Snap, expose the
+[`onUpdate`](../reference/entry-points.md#onupdate) entry point and implement the action.
+For example, you can use `onUpdate` to perform any migrations that are required upon update.
+
+The following example displays an [alert dialog](../reference/snaps-api.md#alert-dialog) upon update:
+
+```typescript title="index.ts"
+import type { OnUpdateHandler } from "@metamask/snaps-sdk";
+import { heading, panel, text } from "@metamask/snaps-sdk";
+
+export const onUpdate: OnUpdateHandler = async () => {
+  await snap.request({
+    method: "snap_dialog",
+    params: {
+      type: "alert",
+      content: panel([
+        heading("Update successful"),
+        text(
+          "New features added in this version:",
+        ),
+        text(
+          "Added a dialog that appears when updating."
+        ), 
+      ]),
+    },
+  });
+};
+```
+
+## Example
+
+See the [`@metamask/lifecycle-hooks-example-snap`](https://github.com/MetaMask/snaps/tree/main/packages/examples/packages/lifecycle-hooks)
+package for a full example of implementing lifecycle hooks.

snaps/features/localization.md

@@ -1,6 +1,6 @@
 ---
 description: Display your Snap's UI and metadata in the user's language.
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # Localization

snaps/features/non-evm-networks.md

@@ -1,6 +1,6 @@
 ---
 description: Manage users' non-EVM accounts and assets.
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 # Non-EVM networks

snaps/features/signature-insights.md

@@ -1,6 +1,6 @@
 ---
 description: Provide insights to your users in MetaMask's signature confirmation flow.
-sidebar_position: 7
+sidebar_position: 8
 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: 8
+sidebar_position: 9
 ---
 
 # Static files

snaps/index.mdx

@@ -86,7 +86,7 @@ The following Snaps features are available in the stable version of MetaMask:
     },
     {
       icon: require("./assets/features/lifecycle-hooks.png").default,
-      href: "reference/permissions#endowmentlifecycle-hooks",
+      href: "features/lifecycle-hooks",
       title: "Lifecycle hooks",
       description: "Call an action when your Snap is installed or updated."
     },

snaps/reference/entry-points.md

@@ -137,7 +137,8 @@ module.exports.onHomePage = async () => {
 
 ## `onInstall`
 
-To run an action on installation, a Snap must expose the `onInstall` entry point.
+To implement a [lifecycle hook](../features/lifecycle-hooks.md) that runs an action upon
+installation, a Snap must expose the `onInstall` entry point.
 MetaMask calls the `onInstall` handler method after the Snap is installed successfully.
 
 :::note
@@ -569,7 +570,8 @@ module.exports.onTransaction = async ({
 
 ## `onUpdate`
 
-To run an action on update, a Snap must expose the `onUpdate` entry point.
+To implement a [lifecycle hook](../features/lifecycle-hooks.md) that runs an action upon update, a
+Snap must expose the `onUpdate` entry point.
 MetaMask calls the `onUpdate` handler method after the Snap is updated successfully. 
 
 :::note

snaps/reference/permissions.md

@@ -128,7 +128,8 @@ Specify this permission in the manifest file as follows:
 
 ### `endowment:lifecycle-hooks`
 
-To run an action when the user installs or updates the Snap, a Snap must request the `endowment:lifecycle-hooks` permission.
+To implement a [lifecycle hook](../features/lifecycle-hooks.md) that runs an action when a user
+installs or updates a Snap, the Snap must request the `endowment:lifecycle-hooks` permission.
 This permission allows the Snap to expose the 
 [`onInstall`](../reference/entry-points.md#oninstall) and 
 [`onUpdate`](../reference/entry-points.md#onupdate)