Livedeck widget 的 manifest.json:字段、权限和错误代码

manifest.json 的所有字段、权限和设置类型,以及各错误代码的含义。

阅读约 8 分钟 更新于 2026年11月4日

manifest.json 用于描述你的 widget。Livedeck 在上传时读取它,据此生成编辑器设置,并且只授予其中列出的权限。未知字段会报错,这样拼写错误就不会被忽略。

json
{
  "manifestVersion": 1,
  "name": "Gift Goal",
  "version": "1.0.0",
  "sdk": "1",
  "entry": "index.html",
  "description": "A bar that fills up with gifts.",
  "formats": ["9:16", "16:9"],
  "size": { "default": [600, 160], "min": [300, 80], "max": [1080, 400] },
  "permissions": ["events.gift", "media.play"],
  "settings": [
    { "key": "goal", "type": "number", "label": { "de": "Ziel", "en": "Goal" }, "default": 100, "min": 1 },
    { "key": "giftId", "type": "gift", "label": { "de": "Nur dieses Geschenk", "en": "Only this gift" } },
    { "key": "accent", "type": "color", "label": { "de": "Farbe", "en": "Colour" }, "default": "#22c55e" },
    { "key": "doneSound", "type": "media", "label": { "de": "Ton bei Ziel", "en": "Goal sound" }, "accept": "audio" }
  ],
  "locales": ["de", "en"]
}

字段

manifestVersion

必填: 是

含义: 始终为 1

name

必填: 是

含义: widget 名称,最多 60 个字符

version

必填: 是

含义: 版本号 x.y.z,例如 1.2.0

sdk

必填: 是

含义: SDK 版本,目前为 "1"

entry

必填: 否

含义: 起始文件,默认为 index.html。必须以 .html 结尾。

description

必填: 否

含义: 简短描述,最多 300 个字符

formats

必填: 否

含义: ["9:16"]、["16:9"] 或两者(默认:两者)

size

必填: 是

含义: 在 overlay 画布上的像素尺寸:default、min 和 max,格式为 [宽, 高]

permissions

必填: 否

含义: widget 可获取哪些数据(见下文)

settings

必填: 否

含义: 用户可在编辑器中修改的设置(最多 40 个)

locales

必填: 否

含义: widget 支持的语言,例如 ["de", "en"]

画布在 9:16 下为 1080 × 1920 像素,在 16:9 下为 1920 × 1080 像素。尺寸范围为 16 到 3840 像素。min 和 max 是用户在编辑器中调整 widget 大小时的限制,未设置时使用 default。请按 default 以固定像素制作 widget:用户调整大小时,Livedeck 会随框体缩放整个页面(文字、图片和间距一起放大)。如果框体形状与 default 不同,页面会在该方向获得额外空间,因此需要填满的地方请使用 100% 宽/高、flexbox 或 grid。livedeck.context.size 是以 CSS 像素表示的页面尺寸,livedeck.context.scale 是缩放比例。

权限

买家在购买前会看到此列表,编辑器也会在「可访问」下显示。只申请你真正需要的权限。

events.gift

礼物(事件 gift)

events.chat

聊天消息(chat)

events.like

点赞,合并推送(like)

events.follow

新粉丝(follow)

events.share

LIVE 分享(share)

events.join

观众进入 LIVE(join)

events.fanclub

加入粉丝团(fanclub)

events.viewers

观众人数(viewers)

stream.status

直播中、离线或审核中(stream)

media.play

可通过 Livedeck 播放媒体设置中的声音

host.profile

主播的名称和头像(livedeck.host)

设置

每项设置都有 key、type 和 label。key 以小写字母开头,后接字母、数字或 _(最多 32 个字符)。label 可以是文本,也可以是多语言对象,如 {"de": "Farbe", "en": "Colour"},最多 80 个字符。widget 从 livedeck.settings 读取这些值。

text

字段: default、maxLength(最多 200)

widget 中的值: 文字

number

字段: default、min、max、step(均为可选)

widget 中的值: 数字

range

字段: default、min 和 max(必填)、step

widget 中的值: 数字,在编辑器中显示为滑块

boolean

字段: default

widget 中的值: true 或 false

color

字段: default,格式为 #rrggbb

widget 中的值: 颜色,格式为 #rrggbb

select

字段: options(1 到 50 个,每个含 value 和 label)、default

widget 中的值: 所选选项的 value

gift

字段: default(礼物 ID 或 null)

widget 中的值: 数字形式的礼物 ID,或 null

media

字段: accept:audio、image 或 video。无 default。

widget 中的值: 用户选择了自己的文件时为 true,否则为 false

注意:媒体设置永远不会向 widget 提供文件地址。用 livedeck.media.play(key) 播放声音;用 livedeck.media.url(key) 获取图片和视频片段。

如果某个值缺失或无效,widget 会得到默认值。这样,即使更新加入了新设置,所有已在使用你 widget 的人也都能正常使用。

manifest.json 中的错误

如果检查失败并提示“manifest.json is invalid”,下方会列出错误代码和位置,例如 settings[2].default。

manifest_not_object

文件不是 JSON 对象。

manifest_too_large

文件大于 64 KB。

manifest_invalid_json

不是有效的 JSON(常见原因是多了或少了一个逗号)。

unknown_field

该字段不存在,通常是拼写错误。

required

缺少必填字段。

wrong_type

类型错误,例如应为列表却写成了文本。

unsupported_manifest_version

manifestVersion 不是 1。

unsupported_sdk

sdk 不是 "1"。

invalid_name

名称为空、超过 60 个字符或包含不可见的控制字符。

invalid_text

文本为空、过长或包含不可见的控制字符。

invalid_version

版本号不是 x.y.z 格式(例如 1.0.0)。

invalid_entry

entry 不是指向 .html 文件的相对路径。

invalid_format

格式不是 "9:16" 或 "16:9"。

duplicate

条目重复。

invalid_size

尺寸超出 16 到 3840 像素范围,或 default 不在 min 和 max 之间。

unknown_permission

该权限不存在。

too_many_settings

设置超过 40 项。

invalid_setting_key

key 不符合格式要求(见上文)。

unknown_setting_type

该设置类型不存在。

invalid_default

default 与类型不符或超出范围。

invalid_bounds

min、max、step 或 maxLength 无效。

invalid_options

options 缺失、为空、超过 50 个,或某个选项没有 value。

invalid_media_kind

accept 不是 audio、image 或 video。

invalid_locale

该语言不存在。允许的值:en, de, tr, fr, es, it, ru, ar, zh-CN, ja, he, pt, nl, pl, uk, ko, hi, id, vi, th。

这篇文章对你有帮助吗?