novu-manage-preferences

管理偏好设置

Novu 有两级偏好设置系统：

1. 工作流默认值 —— 在仪表板中为基于 UI 的工作流配置，或在基于框架的工作流中通过代码配置，适用于所有订阅者。
2. 订阅者覆盖设置 —— 由最终用户设置，覆盖工作流默认值。

工作流级偏好设置

使用 @novu/framework 定义工作流时设置默认偏好：

import { workflow } from "@novu/framework";

const alertWorkflow = workflow("system-alert", execute, {
  preferences: {
    all: { enabled: true, readOnly: false },
    channels: {
      email: { enabled: true },
      sms: { enabled: false },
      push: { enabled: true },
      chat: { enabled: false },
      inApp: { enabled: true },
    },
  },
});

在代码中编写工作流？请参阅 framework-integration，了解完整的 Framework 设置、Bridge Endpoint、步骤控制和部署。

渠道类型

渠道	描述
email	电子邮件通知
sms	SMS 短信
push	移动端／Web 推送通知
chat	Slack、Discord、Teams 等
inApp	应用内 Inbox 通知

只读偏好设置

设置 readOnly: true，即可在偏好设置 UI 中隐藏工作流的渠道，订阅者无法将其开启或关闭：

const criticalAlertWorkflow = workflow("critical-alert", execute, {
  preferences: {
    all: { enabled: true, readOnly: true },  // subscriber CANNOT disable
  },
});

readOnly 与 critical——选择合适的选项

这是两种不同的机制，保证也各不相同。请参阅 design-workflow/references/severity-and-critical.md，查看完整对照表。

标记	作用
preferences.all.readOnly: true	仅影响 UI。 在偏好设置 UI 中隐藏工作流，订阅者无法切换其状态。
critical: true（工作流级）	影响运行时。 跳过订阅者偏好设置和摘要，不等待延迟。

如果你需要通知始终送达（账户已停用、安全警报、密码重置），请设置 critical: true——仅设置 readOnly: true 无法在运行时覆盖现有的订阅者覆盖设置。

可选（订阅者可编辑）偏好设置

const marketingWorkflow = workflow("weekly-newsletter", execute, {
  preferences: {
    all: { enabled: true, readOnly: false },  // subscriber CAN disable
    channels: {
      email: { enabled: true },
      sms: { enabled: false },  // off by default, subscriber can enable
    },
  },
});

订阅者级偏好设置

订阅者可以覆盖工作流默认值（除非设置了 readOnly: true）。

获取订阅者偏好设置

import { Novu } from "@novu/api";

const novu = new Novu({
  secretKey: process.env.NOVU_SECRET_KEY,
});

const preferences = await novu.subscribers.preferences.list({
  subscriberId: "subscriber-123",
});

更新订阅者偏好设置

await novu.subscribers.preferences.update(
  {
    workflowId: "weekly-newsletter",
    channels: {
      email: false,   // opt out of email
      inApp: true,    // keep in-app
    },
  },
  "subscriber-123"
);

全局偏好设置

省略 workflowId，即可更新所有工作流的偏好设置：

await novu.subscribers.preferences.update(
  {
    channels: {
      sms: false,  // disable SMS for all workflows
    },
  },
  "subscriber-123"
);

偏好设置的解析顺序

Novu 判断是否发送通知时：

1. 订阅者工作流偏好设置（最具体）——订阅者针对特定工作流设置的覆盖值
2. 订阅者全局偏好设置——订阅者在所有工作流中的默认值
3. 工作流默认值——开发者在代码中定义的默认值
4. 系统默认值——启用所有渠道

最具体的偏好设置优先。如果订阅者针对特定工作流关闭了电子邮件，即使其全局电子邮件偏好设置已启用，也会以该设置为准。

偏好设置 UI 组件

React

import { Inbox } from "@novu/react";

function App() {
  return (
    <Inbox
      applicationIdentifier="YOUR_NOVU_APP_ID"
      subscriberId="subscriber-123"
      subscriberHash="HMAC_HASH"
    >
      {/* The Preferences panel is built into the Inbox */}
    </Inbox>
  );
}

<Inbox /> 组件内置偏好设置面板，可通过设置图标打开。

独立偏好设置

单独使用 <Preferences /> 组件：

import { Inbox, Preferences } from "@novu/react";

function PreferencesPage() {
  return (
    <Inbox
      applicationIdentifier="YOUR_NOVU_APP_ID"
      subscriberId="subscriber-123"
    >
      <Preferences />
    </Inbox>
  );
}

常见模式

关键警报（始终启用）

preferences: {
  all: { enabled: true, readOnly: true },
}

订阅者无法选择退出。适用于安全警报、付款通知和法律通知。

营销通知（便于选择退出）

preferences: {
  all: { enabled: true, readOnly: false },
  channels: {
    email: { enabled: true },
    sms: { enabled: false },
  },
}

订阅者可以切换渠道。SMS 默认关闭。

默认仅应用内通知

preferences: {
  all: { enabled: false },
  channels: {
    inApp: { enabled: true },
  },
}

默认只启用应用内通知。订阅者可根据需要启用其他渠道。

常见问题

1. readOnly: true 是针对工作流，而非频道 — 你需要在 all 层级设置 readOnly。各个频道会继承此设置。
2. 订阅者的覆盖设置不适用于 readOnly 工作流 — 如果工作流为只读，则会忽略订阅者的偏好设置。
3. 工作流默认设置中的 enabled: false 表示该频道处于关闭状态 — 订阅者仍可启用该频道（除非设置了 readOnly: true）。
4. “偏好设置”界面仅显示非只读工作流 — 只读工作流会在订阅者的偏好设置面板中隐藏。
5. 全局偏好设置适用于所有非只读工作流 — 它们是“禁用所有邮件”这一设置的便捷选项，但工作流特定的偏好设置优先级更高。

参考

• 工作流偏好设置示例
• 订阅者偏好设置示例
• 偏好设置界面示例