Novu In-App 步骤应用内通知创作指南内容规则、Liquid 个性化变量与接收端联动【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu应用内In-App通知是 Novu 工作流中的默认主力通道适合承载实时更新、活动动态与高互动场景。本文以 Novu Dashboard 工作流中的 In-App 步骤内容创作为主线讲解正文/标题/操作按钮的编写准则、Liquid 个性化变量的使用边界与steps.http-step-id的引用前提并结合仓库源码说明消息模板底层结构与 Inbox 接收端行为。读完你将能规范地编写一个兼具个性化、可扫描性与强互动的 In-App 步骤并懂得何时为它配置步骤条件、以及它在收件端如何呈现。一、In-App 步骤定位先搞清楚它该承载什么在 Novu Dashboard 中每个工作流步骤都有对应的内容创作参考文档In-App 步骤的定位是实时更新、活动动态、高互动类内容。你可以对照步骤类型矩阵来看它在工作流中的位置步骤类型典型用途In-App实时更新、活动动态activity feed、高互动内容Email详细内容、正式沟通、回执Push移动端触达、再激活、时效性更新SMS紧急告警、验证码、时效性消息ChatSlack / Discord / Teams 团队与开发者告警出处步骤类型矩阵见 dashboard-workflows/SKILL.md。在选哪个通道的决策上In-App 几乎是所有产品内可见内容的默认选项只要收件人已登录并且正在使用你的产品就应考虑加入 In-App 通道反之如果用户在当下根本看不到产品界面如密码重置、OTP、注册前欢迎信则应跳过 In-App。选型决策树与用户指定通道优先、未指定按 In-App Email Chat Push SMS 优先级挑满 3 个等规则见 design-workflow/references/channel-selection.md。从 Dashboard 源码结构可以印证 In-App 步骤编辑器的组成工作流编辑器中 In-App 步骤的可视化配置由多个独立小组件组合而成目录 apps/dashboard/src/components/workflow-editor/steps/in-app/包括in-app-subject.tsx—— 标题subject输入in-app-body.tsx—— 正文body输入in-app-redirect.tsx—— 点击通知时的重定向目标配置in-app-action.tsx—— 操作按钮action buttons下拉配置封装InAppActionDropdownin-app-avatar.tsx—— 头像展示配置in-app-tabs-section.tsx、in-app-editor.tsx—— 编辑器标签页与整体编排。也就是说一个完整的 In-App 步骤内容通常包含标题、正文、重定向 URL、主/次操作按钮这些字段都支持模板变量与个性化。二、内容创作三条准则为收件端交互而写原文档 in-app-step.md 给出的 In-App 内容创作准则只有三条但每一条都对应着收件端的真实交互能力1. 为互动加入操作按钮Include action buttons for engagement。In-App 与短信、邮件不同通知发出后会直接出现在用户的产品界面中天然具备就地行动的能力。Novu Inbox 在接收端为每条通知渲染可点击的按钮并为主操作 / 次操作提供了独立点击回调见 inbox-integration/SKILL.md 中onPrimaryActionClick/onSecondaryActionClick与renderDefaultActions/renderCustomActions。因此正文里应尽量把下一步动作提炼成按钮文案例如查看订单确认收款而不是塞进正文里让用户去读。2. 聚焦单一动作或单一信息Focus on a single action or piece of information。一条通知只讲一件事。把你的订单已发货 账单已生成 新功能上线塞进同一消息会稀释用户注意力也破坏 Inbox 的单条可扫读布局。3. 可以比 Push 长但必须保持可扫读Can be longer than push — but stay scannable。因为载体是产品界面而非锁屏In-App 正文有更大的空间余量但空间大不等于可以堆砌首句就应点明主题正文保持简短段落长内容交给操作按钮跳转。底层数据结构上消息模板通过ctaCall-To-Action承载跳转地址IMessageTemplate中定义cta: { type: ChannelCTATypeEnum; data: { url?: string } }见 packages/shared/src/entities/message-template/message-template.interface.ts对应编辑器中的重定向配置与data.url的模板变量支持。三、Liquid 变量标题 / 正文 / 按钮文案的个性化语法In-App 步骤的标题、正文与操作按钮标签均支持Liquid 语法做个性化变量需用双大括号{{与}}包裹。可用的变量命名空间如下变量形式含义说明{{ subscriber.firstName }}订阅者收件人数据常用字段见下方系统变量说明{{ payload.* }}触发工作流时传入的 payload例如{{ payload.orderId }}、{{ payload.amount }}{{ steps.http-step-id.property }}上游 HTTP 步骤的响应数据仅当该 HTTP 步骤在其responseBodySchema中声明了该属性时才可用3.1 不要把 HTTP 响应字段编出来{{ steps.http-step-id.property }}有一个硬性前提引用的属性必须出现在上游 HTTP Request 步骤的responseBodySchema里。例如 HTTP 步骤fetch-user只在responseBodySchema声明了name与email那么只能写{{ steps.fetch-user.name }}、{{ steps.fetch-user.email }}想引用其他响应字段需要先把该属性加入 schema。这也是 Novu MCP/Dashboard 内容创作中最常见的坑之一详见 dashboard-workflows/SKILL.md 的 Common Pitfalls 第 2 条。3.2 系统变量说明从共享类型定义看消息模板中预置的系统变量命名空间为subscriber、step、branding、tenant、preheader、actor见 packages/shared/src/entities/message-template/message-template.interface.ts。其中subscriber命名空间声明了firstName、lastName、email、phone、avatar、locale、subscriberId等字符串字段——这些正是Hello {{ subscriber.firstName }}式个性化所依赖的数据来源。无论通过 Dashboard 手写还是通过 Novu MCP 的update_workflow_step调用写入控件都应遵循如下通则控件值中的 Liquid 变量一律使用{{ }}双括号例外Block EditoreditorType: block节点属性里禁止花括号须用裸变量名如payload.actionUrl见 email-step.md 的 Block Editor 规则不要硬编码 URL、名称或产品名一律从payload.*、subscriber.*提取引用 HTTP 响应字段前先确认其声明于responseBodySchema。四、In-App 步骤条件何时需要把关以及如何写原文档特别提醒给 In-App 步骤加条件step condition的情况很少见因为 In-App 通常就是主要通道default channel本身不应被轻易跳过。少数合理场景包括仅当上一条 In-App 通知未被阅读/未被看见时才补发等回退逻辑。条件使用 JSONLogic 表达完整规则见 step-conditions.md与 In-App 步骤强相关的两个模式// In-App 未被阅读时该步骤才执行 { : [{ var: steps.stepId.read }, false] }// In-App 未被看见时该步骤才执行 { : [{ var: steps.stepId.seen }, false] }需要注意操作语义用户说补充/也/并且时用 AND 合并为{ and: [existing, new] }说改为/设置成时整体替换说移除/清除时返回null步骤恒执行。Dashboard 中 In-App 步骤条件的完整字段位于 dashboard-workflows/references/step-conditions.md 的skip输出字段条件变量支持payload.*、subscriber.*与steps.*其中steps.http-step-id.*同样受responseBodySchema约束。五、收件端呈现In-App 通知如何在 Inbox 中落地内容写好后In-App 通知通过 Novu Inbox 组件在网页应用中呈现理解接收端才能倒推内容设计详见 inbox-integration/SKILL.md能力对应Inbox 提供铃铛图标与未读计数、通知流、已读/归档管理、操作按钮与基于 WebSocket 的实时更新——这也是上节写操作按钮、单条可扫读准则的现实基础。工作流标识客户端 Inbox 只会展示包含 In-App 步骤的工作流发出的通知若工作流没有 In-App 步骤Inbox 里什么都不会出现。这决定了In-App 是主通道的默认定位。重定向跳转点击通知时Novu 会调用routerPush并传入工作流中配置的redirect.url即cta.data.url应用侧通过routerPush{(path) router.push(path)}接上自己的路由体系。事件回调onPrimaryActionClick/onSecondaryActionClick可分别响应主、次操作按钮的点击用于埋点或业务动作。富文本若正文需要渲染 HTML需要工作流侧在 In-App 步骤中关闭内容净化Disable content sanitization与接收端用dangerouslySetInnerHTML两步同时生效仅启用其一无效且前提是你完全掌控触发 payload否则会引入 XSS 面。严重度与筛选Inbox 支持按 tags、data属性与严重度做 Tab 分组其中严重度来自 In-App 步骤自身的HIGH / MEDIUM / LOW设置而 workflow 级critical: true改变的是运行时投递语义绕过偏好、跳过 Digest并不直接作用于 Inbox 样式。从消息模板的content字段类型可以看出 In-App 步骤的内容结构支持string | IEmailBlock[]见 message-template.interface.ts即既可以是纯文本/HTML 字符串也可以是结构化的块内容配合 In-App 步骤的可选data对象最多 10 个标量键值对值可为字符串/数字/布尔/null字符串 ≤ 256 字符在客户端以notification.data供渲染分支与条件样式使用。六、实战检查清单写完一个 In-App 步骤后对照以下清单快速自检有没有行动路径互动类通知是否配了主/次操作按钮按钮文案是否来自变量而非硬编码是否聚焦单一信息正文只围绕一个动作或一件事展开是否可扫读正文是否长于 Push 但仍能一眼读完变量是否合法{{ subscriber.* }}、{{ payload.* }}用了双括号{{ steps.http-step-id.* }}中的字段已声明在上游 HTTP 步骤的responseBodySchema中是否需要条件默认不加条件确需未读才补发等逻辑时使用 JSONLogic 并注意 add/replace/remove 语义差异保持编辑模式不随意改动editorTypeemail 的block/html结构保持一致按照这些规则写出的 In-App 步骤既能贴合 Dashboard 与 Novu MCP 的内容创作约束也能在 Inbox 端呈现出一致、可互动、可个性化的高质量通知体验。【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考