> ## 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 赞助交易模板

本指南将带您使用 [模板](https://github.com/monad-developers/next-serwist-privy-smart-wallet),该模板使用 [Next.js](https://nextjs.org/docs)、[Serwist](https://serwist.pages.dev/)(离线能力) 和 [Privy 智能钱包](https://docs.privy.io/wallets/using-wallets/evm-smart-wallets/overview)(身份验证和交易赞助)在 Monad 上构建渐进式 Web 应用(PWA)。

## 前置条件

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

<Accordion title="设置 Privy">
  1. 创建您的 Privy 应用:

       <img src="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" alt="Create your app" width="3454" height="1978" data-path="static/img/templates/next-serwist-privy-embedded-wallet/pwa_click_new_app.png" />

     选择 "Web" 作为平台。然后点击 "Create app"。

       <img src="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" alt="Name your app" width="3456" height="1980" data-path="static/img/templates/next-serwist-privy-embedded-wallet/pwa_click_create_app.png" />

     在下一个页面,请确保保存您的 App ID。

  2. 设置登录方式:

       <img src="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" alt="Set up login methods" width="3456" height="1978" data-path="static/img/templates/next-serwist-privy-embedded-wallet/pwa_configure_user_login_methods.png" />

  3. 禁用外部钱包:

       <img src="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" alt="Disable external wallets" width="3446" height="1980" data-path="static/img/templates/next-serwist-privy-embedded-wallet/pwa_disable_external_wallets.png" />

  4. 向下滚动并启用 "Automatically create embedded wallets on login" 并选择 "EVM Wallets":

       <img src="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" alt="Create wallets automatically" width="3454" height="1978" data-path="static/img/templates/next-serwist-privy-embedded-wallet/pwa_automatically_create_embedded_wallets.png" />

  <Tip>
    您可以启用 "Test Accounts" 用于测试目的:

    <img src="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" alt="Test accounts" width="3456" height="1978" data-path="static/img/templates/next-serwist-privy-embedded-wallet/pwa_test_accounts.png" />
  </Tip>
</Accordion>

<Accordion title="设置 Pimlico">
  1. 注册 Pimlico 账户并前往 "API Keys"

       <img src="https://mintcdn.com/monadfoundation-40611fb6/-TCPhWHMfGzx9j3a/static/img/templates/next-serwist-privy-smart-wallet/click_create_api_key.webp?fit=max&auto=format&n=-TCPhWHMfGzx9j3a&q=85&s=e73da4b3399b80aefa361f1a9b762113" alt="Pimlico API Keys" width="3450" height="1974" data-path="static/img/templates/next-serwist-privy-smart-wallet/click_create_api_key.webp" />

  2. 创建新的 API key:

       <img src="https://mintcdn.com/monadfoundation-40611fb6/-TCPhWHMfGzx9j3a/static/img/templates/next-serwist-privy-smart-wallet/click_create_api_key.webp?fit=max&auto=format&n=-TCPhWHMfGzx9j3a&q=85&s=e73da4b3399b80aefa361f1a9b762113" alt="Pimlico Create API Key" width="3450" height="1974" data-path="static/img/templates/next-serwist-privy-smart-wallet/click_create_api_key.webp" />

  3. 点击 RPC URLs,然后选择 "Monad Testnet",并复制 RPC URL:

       <img src="https://mintcdn.com/monadfoundation-40611fb6/-TCPhWHMfGzx9j3a/static/img/templates/next-serwist-privy-smart-wallet/click_monad_testnet.webp?fit=max&auto=format&n=-TCPhWHMfGzx9j3a&q=85&s=c155069885ad773a93881101e8c79e35" alt="Pimlico RPC URLs" width="3448" height="1980" data-path="static/img/templates/next-serwist-privy-smart-wallet/click_monad_testnet.webp" />

  4. 复制该 RPC URL 并保存到您的 `.env.local` 文件,变量名为 `NEXT_PUBLIC_PIMLICO_BUNDLER_URL`。
</Accordion>

## 设置

1. 克隆仓库:

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

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

   ```bash theme={null}
   cd next-serwist-privy-smart-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

   # Web Push
   WEB_PUSH_EMAIL=user@example.com
   WEB_PUSH_PRIVATE_KEY=your_vapid_private_key
   NEXT_PUBLIC_WEB_PUSH_PUBLIC_KEY=your_vapid_public_key

   # Pimlico
   NEXT_PUBLIC_PIMLICO_BUNDLER_URL=your_pimlico_bundler_url
   ```

   如果您丢失了 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
   ```

## 发送赞助交易

下面是一个使用 [`useSmartWallet`](https://github.com/monad-developers/next-serwist-privy-smart-wallet/blob/main/app/hooks/useSmartWallet.tsx) hook 发送赞助交易的示例。您可以修改代码来发送自己的交易,或者将其集成到您现有的项目中。

```tsx theme={null}
// Use `useSmartWallet` hook
const { smartAccountAddress, smartAccountClient, smartAccountReady } = useSmartWallet();

// Send sponsored transaction
const txHash = await smartAccountClient?.sendTransaction({
  account: smartAccountClient?.account,
  chain: monadTestnet, // Import this from `viem/chains`
  to: NFT_CONTRACT_ADDRESS,
  data,
});
```

### 发送批量赞助交易

您也可以发送批量的赞助交易:

```tsx theme={null}
const txHash = await smartAccountClient?.sendTransaction({
  calls: [
    {
      to: NFT_CONTRACT_ADDRESS,
      data,
    },
    {
      to: NFT_CONTRACT_ADDRESS,
      data,
    },
  ],
});
```

此示例使用 Kernel 智能账户以及 Entrypoint v7。请参见 [`useSmartWallet.tsx`](https://github.com/monad-developers/next-serwist-privy-smart-wallet/blob/main/app/hooks/useSmartWallet.tsx) 了解实现细节。

## 模板文件夹结构

```
next-serwist-privy-smart-wallet/
├── app/
│   ├── components/         # React components
│   │   ├── InstallPWA.tsx  # PWA install prompt
│   │   └── ...
│   ├── hooks/                  # Custom React hooks
│   │   └── useSmartWallet.tsx  # Smart wallet management hook
│   ├── ~offline/           # Offline page
│   └── ...
├── public/                 # Static assets
└── ...
```

## 更改应用名称

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

## 通知设置

<Warning title="启用通知以获得最佳体验!">
  要接收此应用的推送通知,您需要在浏览器和/或系统设置中启用通知:
</Warning>

### 浏览器设置

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

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

<Accordion title="Safari">
  1. 前往 Safari → Settings → Websites → Notifications
  2. 找到您的站点并将其设置为 "Allow"
</Accordion>

### 系统设置

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

<Accordion title="Windows">
  1. Settings → System → Notifications & actions
  2. 确保您的浏览器可以发送通知
  3. 检查浏览器通知设置
</Accordion>

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

<Accordion title="Android">
  1. Settings → Apps → \[您的浏览器] → Notifications
  2. 启用通知
  3. 检查浏览器通知权限
</Accordion>

### 需要后端集成

<Info title="`SendNotification.tsx` 组件是示例代码">
  [`SendNotification.tsx`](https://github.com/monad-developers/next-serwist-privy-smart-wallet/blob/main/app/components/SendNotification.tsx) 需要后端实现:

  * 在用户订阅时 **保存订阅数据**(参见代码中的 TODO 注释)
  * 在用户取消订阅时 **删除订阅数据**
  * **实现 `/notification` 端点** 以发送实际的推送通知
  * 使用 **`web-push` 库** 或类似方案进行服务器端通知投递
</Info>

### 自定义通知内容

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

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

### 应用图标

将 [`public/icons/`](https://github.com/monad-developers/next-serwist-privy-smart-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-smart-wallet/blob/main/public/manifest.json)。要自定义:

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

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

## 部署到 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
     WEB_PUSH_EMAIL
     WEB_PUSH_PRIVATE_KEY
     NEXT_PUBLIC_WEB_PUSH_PUBLIC_KEY
     NEXT_PUBLIC_PIMLICO_BUNDLER_URL
     ```

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

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

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

### 使用 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 WEB_PUSH_EMAIL
   vercel env add WEB_PUSH_PRIVATE_KEY
   vercel env add NEXT_PUBLIC_WEB_PUSH_PUBLIC_KEY
   vercel env add NEXT_PUBLIC_PIMLICO_BUNDLER_URL
   ```

   您也可以前往 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)
* Pimlico:[文档](https://docs.pimlico.io/) | [指南](https://docs.pimlico.io/guides/getting-started)
* Monad:[支持的工具和基础设施](/zh/tooling-and-infra)