From 200990e10edf7fbfce4554539ef4859b62e9e30e Mon Sep 17 00:00:00 2001 From: Alexandra Tran Carrillo <12214231+alexandratran@users.noreply.github.com> Date: Thu, 18 Apr 2024 13:11:55 -0700 Subject: [PATCH] Document Snaps lifecycle hooks (#1274) * Document Snaps lifecycle hooks * wording fix * fix order and wording --- docs/whats-new.md | 2 + snaps/features/lifecycle-hooks.md | 87 ++++++++++++++++++++++++++++ snaps/features/localization.md | 2 +- snaps/features/non-evm-networks.md | 2 +- snaps/features/signature-insights.md | 2 +- snaps/features/static-files.md | 2 +- snaps/index.mdx | 2 +- snaps/reference/entry-points.md | 6 +- snaps/reference/permissions.md | 3 +- 9 files changed, 100 insertions(+), 8 deletions(-) create mode 100644 snaps/features/lifecycle-hooks.md diff --git a/docs/whats-new.md b/docs/whats-new.md index 13aa3086edb..e74abea73db 100644 --- a/docs/whats-new.md +++ b/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 diff --git a/snaps/features/lifecycle-hooks.md b/snaps/features/lifecycle-hooks.md new file mode 100644 index 00000000000..cab67e36837 --- /dev/null +++ b/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. diff --git a/snaps/features/localization.md b/snaps/features/localization.md index 9c57209e1f4..f5b501134b9 100644 --- a/snaps/features/localization.md +++ b/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 diff --git a/snaps/features/non-evm-networks.md b/snaps/features/non-evm-networks.md index 8a90e1d96b3..be5e4c3f3bc 100644 --- a/snaps/features/non-evm-networks.md +++ b/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 diff --git a/snaps/features/signature-insights.md b/snaps/features/signature-insights.md index 80015c383f0..f64875a2818 100644 --- a/snaps/features/signature-insights.md +++ b/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 --- diff --git a/snaps/features/static-files.md b/snaps/features/static-files.md index 772170bf9e5..35caf057ea8 100644 --- a/snaps/features/static-files.md +++ b/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 diff --git a/snaps/index.mdx b/snaps/index.mdx index d1b4a6cefa5..965118fd9a7 100644 --- a/snaps/index.mdx +++ b/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." }, diff --git a/snaps/reference/entry-points.md b/snaps/reference/entry-points.md index 8038963c532..cff5aa64d85 100644 --- a/snaps/reference/entry-points.md +++ b/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 diff --git a/snaps/reference/permissions.md b/snaps/reference/permissions.md index 9d2d38cbf7d..3dce9ec5e1b 100644 --- a/snaps/reference/permissions.md +++ b/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)