V2 请求体 / V1 query+form 共用的推送字段（小写键名），按 Bark 官方分类组织：

内容

字段	类型	iOS	HarmonyOS
title	string	推送标题，显示在通知卡片的第一行；不传时通知只显示正文，服务端自动填 "Bark"	同 iOS，服务端自动填 "订阅通知"
subtitle	string	推送副标题，显示在标题下方、正文上方的较小字号位置，适合放来源、状态之类的补充信息；不传则不显示这一行。设置了 subtitle 之后 title 和 body 必填	同 iOS（但系统通知卡片不会显示，仅在 App 里显示）
body	string	推送正文，通知卡片上的主要内容；全空时服务端自动填 "Empty Message"	同 iOS
markdown	string	非空时优先于 body；服务端透传原文，由 Bark 客户端解析系统通知并在 App 历史中保留 Markdown	非空时服务端生成纯文本供系统通知、列表、搜索和复制全文使用，原文保留供 App 详情渲染 Markdown；解析后无内容则回退 body。链接和图片在纯文本中保留地址

设备

字段	类型	说明
device_key	string	推送目标设备的 key，作用和 URL 路径里的 key 一样；V2 JSON 且路径为 /push 时放在请求体中，与 device_keys 二选一
device_keys	string[]	key 数组，一次推送给多台设备，仅支持 JSON 请求；批量上限由 --max-batch-push-count 控制（默认 -1 无限）

展示与分组

字段	类型	iOS	HarmonyOS
group	string	对消息分组，同一个 group 的推送在系统通知中心和历史记录里归到一组；可在 App 历史消息列表按分组查看，长按或下拉系统通知横幅可对分组静音，静音期间该分组的推送不亮屏提醒	系统通知中心不支持分组，仅在 App 里显示分组
icon	string	自定义通知图标，填图片 URL，设置后替换通知里默认的 Bark 图标；图标自动缓存在本机，同一 URL 只下载一次，之后即使图片地址不可用也能正常显示，首次下载超过 10 秒会退回默认图标；需 iOS 15+	通知图 URL，会在通知卡片右侧显示（如果华为后期开放可能放到左侧图标右下角），客户端列表/详情作为左侧图标显示
image	string	推送图片的 URL，收到推送后展开通知即可看到大图，App 历史记录里也会显示；图片自动缓存在本机，下载超过 10 秒时这条推送不带图片显示	icon 为空时，显示到通知卡片右侧，客户端列表作为右侧缩略图、详情作为正文大图显示。华为会自动校验图片，要求 HTTPS，支持 PNG/JPG/JPEG/BMP/WEBP，总字节数不超过 192KB
badge	integer	App 图标角标数，直接设置成传入的值，不会在原有数字上累加；传 0 会清除角标，同时清掉通知中心里该 App 的通知	可改 App 图标右上角数字，传 0 清除角标

提醒与铃声

字段	类型	iOS	HarmonyOS
level	string	推送级别：active（默认，立即亮屏显示）/timeSensitive（时效性通知，专注模式下也能显示）/passive（仅加入通知列表，不亮屏提醒）/critical（重要警告，静音模式下也响铃）；critical 需在 App 内授权「重要警告」，未授权时降级为普通通知，铃声音量由 volume 控制。需 iOS 15+	active 正常发送；passive 不调用华为 Push V3，只写服务端历史，待客户端同步；timeSensitive、critical 暂降级为普通 active 通知，不具备特殊提醒权益。历史中保留原始 level
volume	string	重要警告（level=critical）的通知音量，取值范围 0-10，不传默认 5；只在重要警告时生效，普通推送的音量由系统控制，不受这个参数影响	-
call	string	传 "1" 时把通知铃声循环播放 30 秒（默认只响一次），用于强提醒场景；配合 sound 指定铃声，与 level=critical 一起用时可用 volume 调整音量	-
sound	string	推送使用的铃声名称，例如 minuet（自动补 .caf 后缀）；App 内置铃声和自己导入的铃声都可用，导入铃声需 .caf 格式、不超过 30 秒，在 App 内铃声设置导入；不传时使用 App 设置里的默认铃声，名称不存在时回退默认提示音；内置铃声列表见 Bark Sounds	铃声名与 Bark 一致，自动补 .mp3 后缀

复制与跳转

字段	类型	iOS	HarmonyOS
copy	string	指定复制推送时复制的内容，比如只复制正文里的验证码；不传这个参数时，复制到的是推送正文	详情页 action 区在最左侧显示"复制"按钮（仅 copy 时独占整行，与 url 并存时三项等宽）；autoCopy 触发时优先复制此字段，为空则回退复制 body；可放入加密载荷
autoCopy	string	1 时自动复制	1 时客户端同步到新通知后自动复制最新一条到剪贴板并 Toast 提示：仅非首次历史同步才触发、通知产生 5 分钟内有效、同一轮多条只取时间最新的一条（时间相同取 id 最大），避免打开 App 时积压的旧验证码覆盖剪贴板；首轮其余消息可在通知详情手动复制。后台不触发：App 在后台被系统冻结/未启动时，无法拉取消息并执行复制，需用户切回前台（或点系统通知跳进 App）才会触发；要实现"推送到达即复制"需 Push Kit push-type: 2 扩展通知权益，普通应用暂申请不到
url	string	点击推送时跳转的 URL，支持 URL Scheme 和 Universal Link；http/https 链接优先用 Universal Link 打开，失败时用 Safari，其他 Scheme 直接交给系统处理	点击跳转到指定 URL
action	string	传 alert 时，点击推送打开 App 会弹出操作弹窗，可复制推送内容或分享；传 none 时只打开 App，不跳转到具体页面，其他值按默认行为处理；同时传了 url 时优先按 url 跳转	alert（默认）同步并打开对应通知详情；单服务器视图会切到来源服务。none 只打开通知首页；url 优先。未归档、过期或来源不可用时停留首页并提示

加密

字段	类型	iOS	HarmonyOS
ciphertext	string	加密推送的 Base64 密文：推送内容对 Bark 服务器和苹果 APNs 都不可见，只有本机 App 能解密；密文里可放 title、subtitle、body、sound、group、badge 等参数（加密方法见 推送加密）；解密失败时通知内容显示 Decryption Failed	通知卡片显示安全占位通知；归档与非归档使用不同提示文案，服务端不解密；App 中能看到解密信息
iv	string	加密时使用的随机 IV 值，需一并传给服务器；ECB 可省略	同 iOS

保存与管理

字段	类型	iOS	HarmonyOS
id	string / integer	通知唯一标识：使用相同的 id 时，新推送会更新替换原通知（不重复堆叠，适合进度/状态类）；delete 删除通知也靠它定位 需 Bark v1.5.2、bark-server v2.2.5 以上；官方 App 要求 JSON 传参使用字符串，本服务端会把数字 id 归一化为字符串下发，故 V2 JSON 传字符串或整数均生效，服务端保留整数的精确十进制形式 传 id 时监控流（/:device_key/message）中同一 device_key + extras.id 的消息会被覆盖（保留原消息 ID），不传 id 则追加新消息	integer 映射 notification.notifyId（int，范围 [0, 2147483647]），相同 id 的通知会互相覆盖；非数字 id 被忽略（由 Push Kit 自动生成标识）；也是 delete 删除模式的目标 notifyId（见 通知删除）
isArchive	string	是否把这条推送保存到 App 的历史记录：传 1 保存，传其他值不保存；不传时按 App 内的设置决定，默认为保存	同 iOS；未归档的普通通知不写历史，但 level=passive 为保证可同步仍写服务端历史。未归档的加密通知会暂存至客户端成功同步并删除远端，不在本地保留
ttl	integer	已保存推送的有效期（秒），只对保存到历史记录的消息生效；到期后 App 自动删除这条历史记录，同时移除通知中心里对应的推送；适合只在一段时间内有意义的消息，比如验证码、临时告警	同 iOS；正整数秒数随历史同步到客户端，客户端按推送时间计算过期时间并清理本地记录
delete	string	传 "1" 时删除指定通知：同时从系统通知中心和 Bark App 历史记录里移除，需搭配 id 使用；指令经静默推送（ContentAvailable）下发，需在系统设置里为 Bark 开启「后台 App 刷新」，否则无效	真值时删除相同 id 的通知（华为 v1 messages:revoke，需正整数 id）；短路整条推送链路——忽略其它所有参数、不写监控流。见 通知删除

扩展字段

跨平台自有能力与 HarmonyOS 特有字段，不在 Bark 官方参数目录中：

字段	类型	iOS	HarmonyOS
soundDuration	integer	-	通知铃声时长（单位秒），仅同时传了 sound 才生效，取值范围 [1, 60]（超出自动截断为 60），铃声不足该时长会循环播放；不传时铃声超过 30 秒截断
foregroundShow	string	-	普通通知默认 1，非空 ciphertext 的加密通知默认 0；显式传值时以传值为准。1 表示应用在前台也展示通知，其它值表示前台不展示
inboxContent	string[]	-	多行消息（传了替换 body）：例 "inboxContent": ["1. 通知栏消息样式", "2. 通知栏消息提醒方式和展示方式", "3. 通知栏消息语言本地化"]；传该字段时自动携带 style=3（收件箱样式），无需单独传 style
data	string	-	自定义数据载荷

表外字段原样透传为 APNs 自定义字段（payload.custom），key 转小写。

HarmonyOS 加密推送安全占位通知

请求包含非空 ciphertext 时，iOS 仍沿用 Bark/APNs 加密字段；HarmonyOS 因普通应用无法取得 push-type: 2 扩展通知权益，直接使用普通 push-type: 0 通知：

• 缺省或 isArchive=1：标题为 [订阅] 加密通知，正文为 请打开及时通知查看加密内容；
• 显式关闭归档：标题为 [订阅] 加密即时通知，正文为 请打开及时通知解密并查看，此通知不会保存到历史记录；
• 系统通知中不携带密文、IV 或原始通知内容；
• 铃声、角标、前台展示设置和 notifyId 仍然生效；未显式传 foregroundShow 时默认 0，显式传值优先；
• ciphertext 与 iv 暂存在消息历史中，用户打开客户端后拉取并在本地解密；
• 服务端不持有 Key、不解析密文、不解密消息。

后台到达即解密/复制的能力限制：Push Kit push-type: 2 扩展通知（类似 iOS Bark Notification Service Extension）能让系统在通知展示前唤醒独立扩展进程做解密、autoCopy 等处理，不依赖主 App 是否启动。但该权益目前普通应用申请不到，因此 App 在后台被冻结/未启动时无法触发解密或自动复制，必须等用户切回前台（或点系统通知跳进 App）后由客户端主动拉取并处理。

Harmony 客户端的 Padding 由模式固定：CBC/ECB 使用 PKCS7，GCM 使用 NoPadding，不可单独选择。

发送端应先把完整通知内容编码为 UTF-8 JSON，可包含 title、body、subtitle、icon、image、group、url、copy、autoCopy、inboxContent、isArchive 和 ttl，再按接收端为该服务器配置的参数加密：

• 算法支持 AES128、AES192、AES256，Key 分别必须为 16、24、32 个 UTF-8 字节；
• 模式支持 CBC、ECB、GCM；
• CBC/ECB 固定使用 PKCS7，GCM 固定使用 NoPadding；
• CBC 的 IV 必须为 16 个 UTF-8 字节，GCM 的 IV 必须为 12 个 UTF-8 字节，并由发送端为每条消息重新随机生成；ECB 不使用 IV，可省略 iv；
• GCM 不使用 AAD，使用 16 字节认证标签；发送端需要将认证标签拼接在密文末尾，再把完整的 ciphertext || authTag 编码为 Base64；
• 解密结果必须是 JSON 对象。解密失败时客户端显示安全占位内容，不会尝试其它服务器的 Key；
• Key 按服务器独立保存在 HarmonyOS Asset Store 中，禁止设备克隆和云同步，不上传及时通知服务器，也不写入普通 Preferences、消息缓存或日志。
• Harmony 客户端的 Key 输入框使用明文显示，也可点击重置图标调用系统密码学安全随机数生成器，按当前 AES 算法生成 16、24 或 32 字节的可打印 Key。
• 随机生成的新 Key 在点击保存前只是候选值。已有配置的 Key、算法或模式发生变化时，客户端会在保存前提醒用户备份旧 Key 并同步更新发送端；确认保存后，使用旧配置加密的历史密文不保证继续可解密。

ciphertext 为空时保持现有普通通知行为。没有扩展通知权益时，系统通知栏无法在展示前显示解密后的内容。

Harmony 客户端将远程消息历史作为待迁移队列：首次进入及之后每次轮询都从 after=0 检查远程记录。每页通知先完成解密，再应用 isArchive/ttl：缺省或 isArchive=1 且尚未过期的通知会将明文、原始 ciphertext/iv、加密标记与绝对过期时间写入本地数据库；显式关闭归档或同步时已经过期的通知不落本地。TTL 剩余不足 1 小时时列表显示“即将过期”标签；详情页按剩余时间显示约 N 分钟、约 N 小时或具体过期时间，不使用秒级倒计时。对于密文且不归档、尚未过期的通知，客户端会通过 Notification Kit 逐条发布包含解密后真实标题和正文的本地通知；开启“加密通知重发”后，归档加密通知也会补发。点击已归档且来源实例可确认的重发通知会打开对应详情；点击非归档或来源实例缺失的通知只进入通知首页，因为无法可靠定位本地详情。点击目标创建及本地通知发布成功后才删除远程密文，失败则保留远程记录供下次同步重试。同一消息使用稳定标识更新，不会在删除重试时重复堆叠。客户端手动删除已迁移通知时只清理本地副本；单条、多选、分组和全部删除遇到解密失败通知时，会先核对服务器当前持久化实例 ID，确认匹配后删除远端密文，成功后才删除本地记录。无法确认实例或远端删除失败的条目保留供重试；旧实例或来源不明的本地记录不向当前服务器发送删除请求；分组删除覆盖尚未加载到界面的本地通知。