如何向 Farcaster Mini App 用户发送通知

本指南将带您了解如何向 Mini App 用户发送通知。本指南使用 Monad Mini App 模板,该模板已经包含发送通知的代码;您只需修改几行代码。如果您没有使用该模板,仍可以按照本指南操作;可根据需要从模板中复制代码。

演示

如果您想体验 Mini App 通知效果,可以尝试 Monad Mini App 模板应用。

修改 Mini App manifest

在 Mini App 能够发送通知之前,必须完成 Mini App 账户关联流程。

Mini Apps 可以在以下情形下向用户发送通知:

用户已添加 Mini App 并未手动关闭通知
用户明确订阅了来自 Mini App 的通知

Farcaster 应用或客户端会向 Mini App 的 webhook 端点发送 miniapp_added、miniapp_removed、notifications_disabled 和 notifications_enabled 等事件,这使 Mini App 能够跟踪它可以向哪些用户发送通知。 webhookUrl 必须在 Mini App manifest 文件中指定:

app/.well-known/farcaster.json/route.ts

...

export async function GET() {
  const farcasterConfig = {
    // TODO: Add your own account association
    frame: {
        version: "1",
        name: "Monad Farcaster Mini App Template",
        ...
        splashBackgroundColor: "#ffffff",
        webhookUrl: `${APP_URL}/api/webhook`, // <--- Edit this
    },
};

...

如果您使用的是 Monad Mini App 模板,则无需编辑 webhookUrl。

处理 Farcaster 客户端事件

处理 webhook 事件的代码位于文件 /app/api/webhook/route.ts 中。

验证 webhook 事件

事件由用户的 app key 使用 JSON Farcaster Signature 进行签名。这使 Mini Apps 可以验证生成通知的 Farcaster 客户端以及所对应的 Farcaster 用户。验证事件很重要,以确保 Mini App 正确跟踪它可以向哪些用户发送通知。如果您使用的是 Monad Mini App 模板,验证事件的代码已经存在于 /app/api/webhook/route.ts。如果没有使用模板,您可以从同一文件复制代码。

需要 Neynar API key 才能验证 webhook 事件。您可以在 Neynar 服务上注册并免费获取 API key。获取后,在您的 .env 文件中添加一个名为 NEYNAR_API_KEY 的环境变量。

处理 webhook 载荷

一旦指定了 webhookUrl,Farcaster 应用和客户端将向该 webhook 端点发送客户端事件。 miniapp_added 和 notifications_enabled 事件由 Mini App 与 fid 和 notificationDetails 一起接收。 notificationDetails 包含一个 url 和一个 token,可用于向特定 Farcaster 用户发送通知。 Webhook 载荷示例:

{
    "fid": 17979,
    "event": {
        "event": "notifications_enabled",
        "notificationDetails": {
            "url": "https://api.farcaster.xyz/v1/frame-notifications",
            "token": "a05059ef2415c67b08ecceb539201cbc6"
        }
    }
}

您可以在 /app/api/webhook/route.ts 中找到处理 Farcaster 客户端事件的代码。 Mini App 可以使用任何自选的数据库服务来存储 url 和 token,并在发送通知时使用它们。 Monad Mini App 模板使用 Upstash 的 Redis 服务存储 notificationDetails,如果您希望使用不同的数据库,可以在 /lib/kv.ts 中修改。

由于 Monad Mini App 模板使用 Redis 存储通知的 url 和 token,.env 中需要 UPSTASH_REDIS_REST_URL 和 UPSTASH_REDIS_REST_TOKEN 环境变量。在您注册 Upstash 服务并创建 Redis 数据库后,便可获得这些环境变量。如果您计划使用其他数据库,请相应地调整环境变量。

将通知详情存储到 Redis 的示例:

/lib/kv.ts

...

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL,
  token: process.env.UPSTASH_REDIS_REST_TOKEN,
});

...

export async function setUserNotificationDetails(
    fid: number,
    notificationDetails: MiniAppNotificationDetails
): Promise<void> {
    // Modify lines that use redis to use your own database implementation
    await redis.set(getUserNotificationDetailsKey(fid), notificationDetails);  
}

...

发送通知

Example of a notification sent from a Farcaster Mini App

一旦您获取了用户的通知 token,即可通过向该 token 关联的 URL 发送 POST 请求来向用户发送通知。如果您使用的是 Monad Mini App 模板,发送通知的代码已经存在于文件 /app/api/send-notification/route.ts 中。如果没有,您可以从 /lib/notifs.ts 和 /app/api/send-notification/route.ts 复制代码。

个性化通知内容

您可以在 /app/api/send-notification/route.ts 文件中修改几行代码来个性化通知:

/app/api/send-notification/route.ts

...

// This function sends the notification
const sendResult = await sendFrameNotification({
    fid: requestBody.data.fid,
    // You can modify/personalize the below line to make the title of the notification dynamic based on the fid (user)
    title: "Test notification",
    // You can modify/personalize the below line to make the body of the notification dynamic based on the fid (user)
    body: "Sent at " + new Date().toISOString(),
});

...

通知速率限制

Farcaster 强制执行的标准速率限制为:

每个 token 每 30 秒 1 条通知
每个 token 每天 100 条通知

如果您使用的是 Monad Mini App 模板,您可以通过对 /api/send-notification 端点发起 POST 请求,从服务器或 Mini App 发送通知! 这就是您向 Mini App 用户发送通知所需的全部!

简介

开发者要点

工具和基础设施

JSON-RPC

指南

资源

面向 AI 智能体

如何向 Farcaster Mini App 用户发送通知

演示

修改 Mini App manifest

处理 Farcaster 客户端事件

验证 webhook 事件

处理 webhook 载荷

发送通知

个性化通知内容

通知速率限制

​演示

​修改 Mini App manifest

​处理 Farcaster 客户端事件

​验证 webhook 事件

​处理 webhook 载荷

​发送通知

​个性化通知内容

​通知速率限制

演示

修改 Mini App manifest

处理 Farcaster 客户端事件

验证 webhook 事件

处理 webhook 载荷

发送通知

个性化通知内容

通知速率限制