> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monad.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 如何使用 Next.js PWA Privy 嵌入式钱包模板

本指南将带您使用 [模板](https://github.com/monad-developers/next-serwist-privy-embedded-wallet),该模板使用 [Next.js](https://nextjs.org/docs)、[Serwist](https://serwist.pages.dev/)(离线能力) 和 [Privy 嵌入式钱包](https://docs.privy.io/wallets/wallets/create/create-a-wallet) 在 Monad 上构建渐进式 Web 应用(PWA)。

> [!NOTE]
>
> 该模板还有一个 `no-privy` 分支,您可以切换到该分支以在不使用 Privy 的情况下开始。
>
> 您可以使用以下命令切换分支:
>
> ```
> git checkout no-privy
> ```

## 前置条件

* [Node.js](https://nodejs.org/)(v18 或更高版本)
* 一个 [Privy 账户](https://www.privy.io/)

> [accordion] 设置 Privy
>
> 1. 创建您的 Privy 应用:
>
> ![Create your app](https://mintcdn.com/monadfoundation-40611fb6/-TCPhWHMfGzx9j3a/static/img/templates/next-serwist-privy-embedded-wallet/pwa_click_new_app.png?fit=max\&auto=format\&n=-TCPhWHMfGzx9j3a\&q=85\&s=1e77926c75632003b07c0873df222853)
>
> 选择 "Web" 作为平台。然后点击 "Create app"。
>
> ![Name your app](https://mintcdn.com/monadfoundation-40611fb6/-TCPhWHMfGzx9j3a/static/img/templates/next-serwist-privy-embedded-wallet/pwa_click_create_app.png?fit=max\&auto=format\&n=-TCPhWHMfGzx9j3a\&q=85\&s=456c94c880237d9cad357fe01aee07ab)
>
> 在下一个页面,请确保保存您的 App ID。
>
> 2. 设置登录方式:
>
> ![Set up login methods](https://mintcdn.com/monadfoundation-40611fb6/-TCPhWHMfGzx9j3a/static/img/templates/next-serwist-privy-embedded-wallet/pwa_configure_user_login_methods.png?fit=max\&auto=format\&n=-TCPhWHMfGzx9j3a\&q=85\&s=b24f7eeb75a7baf469c06b3e5a730b28)
>
> 3. 禁用外部钱包:
>
> ![Disable external wallets](https://mintcdn.com/monadfoundation-40611fb6/-TCPhWHMfGzx9j3a/static/img/templates/next-serwist-privy-embedded-wallet/pwa_disable_external_wallets.png?fit=max\&auto=format\&n=-TCPhWHMfGzx9j3a\&q=85\&s=8135a7da5ffbea2176ae017db3a0a9d9)
>
> 4. 向下滚动并启用 "Automatically create embedded wallets on login" 并选择 "EVM Wallets":
>
> ![Create wallets automatically](https://mintcdn.com/monadfoundation-40611fb6/-TCPhWHMfGzx9j3a/static/img/templates/next-serwist-privy-embedded-wallet/pwa_automatically_create_embedded_wallets.png?fit=max\&auto=format\&n=-TCPhWHMfGzx9j3a\&q=85\&s=6f86d8d0d92e80de47368a7d3b73bb60)
>
> > [!TIP]
> >
> > 您可以启用 "Test Accounts" 用于测试目的:
> >
> > ![Test accounts](https://mintcdn.com/monadfoundation-40611fb6/-TCPhWHMfGzx9j3a/static/img/templates/next-serwist-privy-embedded-wallet/pwa_test_accounts.png?fit=max\&auto=format\&n=-TCPhWHMfGzx9j3a\&q=85\&s=84dc582ebe6d505ddfbfe992a8c84f09)

## 设置

1. 克隆仓库:

   ```bash theme={null}
   git clone https://github.com/monad-developers/next-serwist-privy-embedded-wallet.git
   ```

2. `cd` 进入项目目录:

   ```bash theme={null}
   cd next-serwist-privy-embedded-wallet
   ```

3. 安装依赖:

   ```bash theme={null}
   npm install
   ```

4. 在根目录创建 `.env.local` 文件:

   ```bash theme={null}
   cp .env.example .env.local
   ```

5. 开始向 `.env.local` 文件添加环境变量:

   ```bash theme={null}
   # Privy
   NEXT_PUBLIC_PRIVY_APP_ID=your_privy_app_id_here
   NEXT_PUBLIC_PRIVY_CLIENT_ID= # optional, you can leave this empty

   # VAPID Keys for push notifications
   NEXT_PUBLIC_VAPID_PUBLIC_KEY=your_vapid_public_key_here
   VAPID_PRIVATE_KEY=your_vapid_private_key_here
   ```

   如果您丢失了 Privy App ID,可以在 Privy 仪表盘中找到。

6. 为 Web 推送通知生成 VAPID 密钥:

   ```bash theme={null}
   npx web-push generate-vapid-keys --json
   ```

   将生成的密钥复制到您的 .env.local 文件中(替换步骤 5 中的占位值)。

7. 运行应用:

   **开发模式**:

   ```bash theme={null}
   npm run dev
   ```

   应用将在 [http://localhost:3000](http://localhost:3000) 上可用。

   **生产模式:**

   完整的 PWA 功能(包括安装提示):

   ```bash theme={null}
   npm run build && npm run start
   ```

## 模板文件夹结构

```
next-serwist-privy-embedded-wallet/
├── app/
│   ├── components/         # React components
│   │   ├── InstallPWA.tsx  # PWA install prompt
│   │   └── ...
│   ├── ~offline/           # Offline page
│   └── ...
├── public/                 # Static assets
└── ...
```

## 更改应用名称

* 编辑 [`public/manifest.json`](https://github.com/monad-developers/next-serwist-privy-embedded-wallet/blob/main/public/manifest.json):
  * 修改 `name` 和 `short_name` 字段
* 运行 `npm run build` 更新应用

## 通知设置

> [!WARNING]
>
> 要接收此应用的推送通知,您需要在浏览器和/或系统设置中启用通知:

### 浏览器设置

> [accordion] Chrome/Edge
>
> 1. 点击地址栏中的锁形图标 🔒
> 2. 将 "Notifications" 设置为 "Allow"
> 3. 或前往 Settings → Privacy and security → Site Settings → Notifications

> [accordion] Firefox
>
> 1. 点击地址栏中的盾牌图标 🛡️
> 2. 如有需要,为此站点关闭 "Enhanced Tracking Protection"
> 3. 在出现提示时允许通知
> 4. 或前往 Settings → Privacy & Security → Permissions → Notifications

> [accordion] Safari
>
> 1. 前往 Safari → Settings → Websites → Notifications
> 2. 找到您的站点并将其设置为 "Allow"

### 系统设置

> [accordion] macOS
>
> 1. System Preferences → Notifications & Focus
> 2. 找到您的浏览器并确保通知已启用
> 3. 在浏览器设置中勾选 "Allow notifications from websites"

> [accordion] Windows
>
> 1. Settings → System → Notifications & actions
> 2. 确保您的浏览器可以发送通知
> 3. 检查浏览器通知设置

> [accordion] iOS
>
> 1. Settings → Notifications → \[您的浏览器]
> 2. 启用 "Allow Notifications"
> 3. 同时在浏览器设置中启用

> [accordion] Android
>
> 1. Settings → Apps → \[您的浏览器] → Notifications
> 2. 启用通知
> 3. 检查浏览器通知权限

### 需要后端集成

> [!NOTE]
>
> [`SendNotification.tsx`](https://github.com/monad-developers/next-serwist-privy-embedded-wallet/blob/main/app/components/SendNotification.tsx) 需要后端实现:
>
> * 在用户订阅时 **保存订阅数据**(参见代码中的 TODO 注释)
> * 在用户取消订阅时 **删除订阅数据**
> * **实现 `/notification` 端点** 以发送实际的推送通知
> * 使用 **`web-push` 库** 或类似方案进行服务器端通知投递

### 自定义通知内容

要自定义推送通知内容,请编辑 [`app/notification/route.ts`](https://github.com/monad-developers/next-serwist-privy-embedded-wallet/blob/main/app/notification/route.ts) ,并修改 `sendNotification` 调用中的 `title`、`message`、`icon` 及其他属性。

## 修改应用图标和启动画面

### 应用图标

将 [`public/icons/`](https://github.com/monad-developers/next-serwist-privy-embedded-wallet/tree/main/public/icons) 目录下的图标文件替换为您的自定义图标:

* **`icon-512x512.png`** - 主应用图标(512×512px)
* **`android-chrome-192x192.png`** - Android 图标(192×192px)
* **`apple-touch-icon.png`** - iOS 主屏幕图标(180×180px)

同时更新 favicon:

* **`public/favicon.ico`** - 浏览器 favicon
* **`app/favicon.ico`** - Next.js 应用 favicon

### 启动画面

启动画面根据您的应用图标和在以下位置定义的主题颜色自动生成: [`public/manifest.json`](https://github.com/monad-developers/next-serwist-privy-embedded-wallet/blob/main/public/manifest.json)。要自定义:

1. 在以下位置更新 `theme_color` 和 `background_color`: [`public/manifest.json`](https://github.com/monad-developers/next-serwist-privy-embedded-wallet/blob/main/public/manifest.json)
2. 确保您的主图标(`icon-512x512.png`)代表您的品牌
3. 运行 `npm run build` 以应用更改

> [!TIP]
>
> 使用 [PWA Asset Generator](https://www.pwabuilder.com/imageGenerator) 等工具从单张源图片生成所有所需的图标尺寸。

## 部署到 Vercel

### 使用 Vercel 仪表盘

1. **连接您的仓库**:
   * 将您的代码推送到 GitHub
   * 访问 [vercel.com](https://vercel.com) 并导入您的仓库

2. **配置环境变量**:
   * 在您的 Vercel 项目仪表盘,前往 Settings → Environment Variables
   * 添加与您的 `.env.local` 相同的变量:
     ```
     NEXT_PUBLIC_PRIVY_APP_ID
     NEXT_PUBLIC_PRIVY_CLIENT_ID
     NEXT_PUBLIC_VAPID_PUBLIC_KEY
     VAPID_PRIVATE_KEY
     ```

3. **部署**:Vercel 将自动构建并部署您的应用

4. **更新 Privy 设置**:在您的 Privy 仪表盘中,将您的 Vercel 域名(例如 `your-app.vercel.app`)添加到允许的来源

> [!TIP]
>
> PWA 功能(安装提示、离线支持、推送通知)会在 HTTPS 域名上(如 Vercel 部署)自动生效。

### 使用 Vercel CLI

或者,使用 Vercel CLI 部署:

1. **安装 Vercel CLI**:
   ```bash theme={null}
   npm i -g vercel
   ```

2. **登录 Vercel**:
   ```bash theme={null}
   vercel login
   ```

3. **部署**:
   ```bash theme={null}
   vercel
   ```
   按照提示配置您的项目。

4. **添加环境变量**:

   ```bash theme={null}
   vercel env add NEXT_PUBLIC_PRIVY_APP_ID
   vercel env add NEXT_PUBLIC_PRIVY_CLIENT_ID  
   vercel env add NEXT_PUBLIC_VAPID_PUBLIC_KEY
   vercel env add VAPID_PRIVATE_KEY
   ```

   您也可以前往 Vercel 仪表盘在那里添加环境变量。

5. **使用环境变量重新部署**:
   ```bash theme={null}
   vercel --prod
   ```

## 了解更多

* Serwist:[文档](https://serwist.pages.dev/) | [指南](https://serwist.pages.dev/docs/next/getting-started)
* Privy:[创建钱包](https://docs.privy.io/wallets/wallets/create/create-a-wallet) | [发送交易](https://docs.privy.io/wallets/using-wallets/ethereum/send-a-transaction) | [签署交易](https://docs.privy.io/wallets/using-wallets/ethereum/sign-a-transaction)
* Monad:[支持的工具和基础设施](https://docs.monad.xyz/zh/tooling-and-infra.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.