Back to Details

novu-manage-preferences

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Manage Preferences

管理偏好设置

Novu has a two-level preference system:
  1. Workflow defaults — configured in the dashboard for UI based workflows or via code in framework based workflows, apply to all subscribers.
  2. Subscriber overrides — set by end users, override workflow defaults
Novu 拥有两级偏好设置系统：
  1. 工作流默认设置 — 在仪表板中针对基于UI的工作流配置，或通过代码针对基于框架的工作流配置，适用于所有订阅者。
  2. 订阅者覆盖设置 — 由终端用户设置，会覆盖工作流默认设置

Workflow-Level Preferences

工作流级偏好设置

Set default preferences when defining a workflow with 
@novu/framework
:
typescript
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 },
    },
  },
});
Authoring workflows in code? See 
framework-integration
 for the full Framework setup, Bridge Endpoint, step controls, and deployment.
使用 
@novu/framework
定义工作流时设置默认偏好：
typescript
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
 获取完整的框架设置、桥接端点、步骤控制和部署说明。

Channel Types

渠道类型

ChannelDescription
email
Email notifications
sms
SMS text messages
push
Mobile/web push notifications
chat
Slack, Discord, Teams, etc.
inApp
In-app Inbox notifications
渠道描述
email
电子邮件通知
sms
短信通知
push
移动端/网页端推送通知
chat
Slack、Discord、Teams等聊天通知
inApp
应用内收件箱通知

Read-Only Preferences

只读偏好设置

Set 
readOnly: true
to hide a workflow's channels from the Preferences UI — subscribers can't toggle them on or off:
typescript
const criticalAlertWorkflow = workflow("critical-alert", execute, {
  preferences: {
    all: { enabled: true, readOnly: true },  // subscriber CANNOT disable
  },
});
设置 
readOnly: true
可在偏好设置UI中隐藏工作流的渠道——订阅者无法切换其开关：
typescript
const criticalAlertWorkflow = workflow("critical-alert", execute, {
  preferences: {
    all: { enabled: true, readOnly: true },  // 订阅者无法禁用
  },
});

readOnly
vs 
critical
— pick the right one

readOnly
与 
critical
— 选择合适的选项

These are different mechanisms with different guarantees. See 
design-workflow/references/severity-and-critical.md
 for the full matrix.
FlagWhat it does
preferences.all.readOnly: true
UI only. Hides the workflow from the Preferences UI so subscribers can't toggle it.
critical: true
(workflow-level)		Runtime. Bypasses subscriber preferences, skips digest, runs without delays.
If you need the notification to always be delivered (account suspended, security alert, password reset), set 
critical: true
— 
readOnly: true
alone won't override existing subscriber overrides at runtime.
这是两种机制，具备不同的保障。查看 
design-workflow/references/severity-and-critical.md
 获取完整对比表。
标记作用
preferences.all.readOnly: true
仅UI层面。在偏好设置UI中隐藏该工作流，订阅者无法切换其开关。
critical: true
（工作流级）		运行时层面。绕过订阅者偏好设置，跳过摘要，无延迟运行。
如果需要通知始终被送达（如账户暂停、安全警报、密码重置），请设置 
critical: true
——仅设置 
readOnly: true
无法在运行时覆盖已有的订阅者覆盖设置。

Optional (Subscriber-Editable) Preferences

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

typescript
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
    },
  },
});
typescript
const marketingWorkflow = workflow("weekly-newsletter", execute, {
  preferences: {
    all: { enabled: true, readOnly: false },  // 订阅者可禁用
    channels: {
      email: { enabled: true },
      sms: { enabled: false },  // 默认关闭，订阅者可启用
    },
  },
});

Subscriber-Level Preferences

订阅者级偏好设置

Subscribers can override workflow defaults (unless 
readOnly: true
).
订阅者可覆盖工作流默认设置（除非设置了 
readOnly: true
）。

Get Subscriber Preferences

获取订阅者偏好设置

typescript
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",
});
typescript
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",
});

Update Subscriber Preferences

更新订阅者偏好设置

typescript
await novu.subscribers.preferences.update(
  {
    workflowId: "weekly-newsletter",
    channels: {
      email: false,   // opt out of email
      inApp: true,    // keep in-app
    },
  },
  "subscriber-123"
);
typescript
await novu.subscribers.preferences.update(
  {
    workflowId: "weekly-newsletter",
    channels: {
      email: false,   // 退订电子邮件
      inApp: true,    // 保留应用内通知
    },
  },
  "subscriber-123"
);

Global Preferences

全局偏好设置

Update preferences across all workflows by omitting 
workflowId
:
typescript
await novu.subscribers.preferences.update(
  {
    channels: {
      sms: false,  // disable SMS for all workflows
    },
  },
  "subscriber-123"
);
省略 
workflowId
即可更新所有工作流的偏好设置：
typescript
await novu.subscribers.preferences.update(
  {
    channels: {
      sms: false,  // 禁用所有工作流的短信通知
    },
  },
  "subscriber-123"
);

Preference Resolution Order

偏好设置解析顺序

When Novu determines whether to deliver a notification:
  1. Subscriber workflow preference (most specific) — subscriber's override for this specific workflow
  2. Subscriber global preference — subscriber's default across all workflows
  3. Workflow default — developer-defined default in code
  4. System default — all channels enabled
The most specific preference wins. If a subscriber disables email for a specific workflow, that takes precedence even if their global email preference is enabled.
当Novu决定是否发送通知时：
  1. 订阅者工作流偏好设置（最具体）—— 订阅者针对该特定工作流的覆盖设置
  2. 订阅者全局偏好设置 — 订阅者在所有工作流中的默认设置
  3. 工作流默认设置 — 开发者在代码中定义的默认值
  4. 系统默认设置 — 所有渠道均启用
最具体的偏好设置优先级最高。如果订阅者禁用了某个特定工作流的电子邮件通知，即使其全局电子邮件偏好设置为启用，该特定设置仍会生效。

Preferences UI Component

偏好设置UI组件

React

React

tsx
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>
  );
}
The 
<Inbox />
component includes a built-in Preferences panel accessible via the settings icon.
tsx
import { Inbox } from "@novu/react";

function App() {
  return (
    <Inbox
      applicationIdentifier="YOUR_NOVU_APP_ID"
      subscriberId="subscriber-123"
      subscriberHash="HMAC_HASH"
    >
      {/* 偏好设置面板已内置到收件箱中 */}
    </Inbox>
  );
}
<Inbox />
组件包含内置的偏好设置面板，可通过设置图标访问。

Standalone Preferences

独立偏好设置组件

Use the 
<Preferences />
component independently:
tsx
import { Inbox, Preferences } from "@novu/react";

function PreferencesPage() {
  return (
    <Inbox
      applicationIdentifier="YOUR_NOVU_APP_ID"
      subscriberId="subscriber-123"
    >
      <Preferences />
    </Inbox>
  );
}
可独立使用 
<Preferences />
组件：
tsx
import { Inbox, Preferences } from "@novu/react";

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

Common Patterns

常见模式

Critical Alerts (Always On)

关键警报（始终启用）

typescript
preferences: {
  all: { enabled: true, readOnly: true },
}
Subscribers cannot opt out. Use for security alerts, payment notifications, legal notices.
typescript
preferences: {
  all: { enabled: true, readOnly: true },
}
订阅者无法退订。适用于安全警报、付款通知、法律通知。

Marketing (Opt-Out Friendly)

营销通知（支持退订）

typescript
preferences: {
  all: { enabled: true, readOnly: false },
  channels: {
    email: { enabled: true },
    sms: { enabled: false },
  },
}
Subscribers can toggle channels. SMS is off by default.
typescript
preferences: {
  all: { enabled: true, readOnly: false },
  channels: {
    email: { enabled: true },
    sms: { enabled: false },
  },
}
订阅者可切换渠道。短信默认关闭。

In-App Only by Default

默认仅启用应用内通知

typescript
preferences: {
  all: { enabled: false },
  channels: {
    inApp: { enabled: true },
  },
}
Only in-app is on. Subscribers can enable other channels if desired.
typescript
preferences: {
  all: { enabled: false },
  channels: {
    inApp: { enabled: true },
  },
}
仅启用应用内通知。订阅者可根据需要启用其他渠道。

Common Pitfalls

常见误区

  1. readOnly: true
    is per-workflow, not per-channel     — you set 
    readOnly
    on the 
    all
    level. Individual channels inherit it.
  2. Subscriber overrides don't apply to 
    readOnly
    workflows     — if the workflow is read-only, subscriber preferences are ignored.
  3. enabled: false
    in the workflow default means the channel is off     — subscribers can still enable it (unless 
    readOnly: true
    ).
  4. The Preferences UI only shows non-readOnly workflows — read-only workflows are hidden from the subscriber's preference panel.
  5. Global preferences apply across all non-readOnly workflows — they're a convenient "disable all email" setting, but workflow-specific preferences take precedence.
  1. readOnly: true
    是针对工作流而非渠道     — 你需要在
    all
    级别设置
    readOnly
    ，各个渠道会继承该设置。
  2. 订阅者覆盖设置不适用于
    readOnly
    工作流     — 如果工作流是只读的，订阅者偏好设置会被忽略。
  3. 工作流默认设置中的
    enabled: false
    意味着渠道处于关闭状态     — 订阅者仍可启用该渠道（除非设置了
    readOnly: true
    ）。
  4. 偏好设置UI仅显示非只读工作流 — 只读工作流会从订阅者的偏好设置面板中隐藏。
  5. 全局偏好设置适用于所有非只读工作流 — 这是一个便捷的“关闭所有电子邮件”设置，但工作流特定的偏好设置优先级更高。

References

参考文档

  • Workflow Preferences Examples
  • Subscriber Preferences Examples
  • Preferences UI Examples
  • Workflow Preferences Examples
  • Subscriber Preferences Examples
  • Preferences UI Examples