manifest.json cho widget Livedeck: trường, quyền và mã lỗi

Mọi trường, quyền và loại cài đặt của manifest.json, cùng ý nghĩa của từng mã lỗi.

8 phút đọc Cập nhật 4 thg 11, 2026

manifest.json mô tả widget của bạn. Livedeck đọc file này khi tải lên, tạo phần cài đặt trong editor từ nó và chỉ cấp cho widget những quyền được liệt kê trong đó. Trường không xác định sẽ bị báo lỗi để lỗi chính tả không bao giờ bị bỏ sót.

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"]
}

Các trường

manifestVersion

Bắt buộc: có

Ý nghĩa: Luôn là 1

name

Bắt buộc: có

Ý nghĩa: Tên widget, tối đa 60 ký tự

version

Bắt buộc: có

Ý nghĩa: Số phiên bản x.y.z, ví dụ 1.2.0

sdk

Bắt buộc: có

Ý nghĩa: Phiên bản SDK, hiện tại là "1"

entry

Bắt buộc: không

Ý nghĩa: File khởi động, mặc định là index.html. Phải kết thúc bằng .html.

description

Bắt buộc: không

Ý nghĩa: Mô tả ngắn, tối đa 300 ký tự

formats

Bắt buộc: không

Ý nghĩa: ["9:16"], ["16:9"] hoặc cả hai (mặc định: cả hai)

size

Bắt buộc: có

Ý nghĩa: Kích thước tính bằng pixel trên canvas overlay: default, min và max dạng [rộng, cao]

permissions

Bắt buộc: không

Ý nghĩa: Dữ liệu widget nhận được (xem bên dưới)

settings

Bắt buộc: không

Ý nghĩa: Cài đặt người dùng thay đổi trong editor (tối đa 40)

locales

Bắt buộc: không

Ý nghĩa: Ngôn ngữ widget hỗ trợ, ví dụ ["de", "en"]

Canvas có kích thước 1080 × 1920 pixel ở 9:16 và 1920 × 1080 ở 16:9. Kích thước từ 16 đến 3840 pixel. min và max là giới hạn khi người dùng thay đổi kích thước widget trong editor. Nếu không có, default sẽ được áp dụng. Hãy dựng widget bằng pixel cố định theo default: khi người dùng thay đổi kích thước, Livedeck sẽ phóng to/thu nhỏ toàn bộ trang theo khung (chữ, hình ảnh và khoảng cách cùng thay đổi). Nếu khung có tỷ lệ khác với default, trang sẽ được thêm không gian theo hướng đó, vì vậy hãy dùng chiều rộng/cao 100%, flexbox hoặc grid ở những chỗ cần lấp đầy. livedeck.context.size là kích thước trang tính bằng pixel CSS và livedeck.context.scale là mức zoom.

Quyền

Người mua thấy danh sách này trước khi mua, và editor hiển thị nó trong mục “Được truy cập”. Chỉ yêu cầu những gì bạn thật sự cần.

events.gift

Quà tặng (sự kiện gift)

events.chat

Tin nhắn chat (chat)

events.like

Lượt thích, gộp lại (like)

events.follow

Follower mới (follow)

events.share

Lượt chia sẻ LIVE (share)

events.join

Người xem vào LIVE (join)

events.fanclub

Tham gia fan club (fanclub)

events.viewers

Số người xem (viewers)

stream.status

Đang live, offline hoặc đang kiểm tra (stream)

media.play

Được phát âm thanh từ cài đặt media qua Livedeck

host.profile

Tên và ảnh đại diện của streamer (livedeck.host)

Cài đặt

Mỗi cài đặt có một key, một type và một label. Key bắt đầu bằng chữ thường, theo sau là chữ cái, chữ số hoặc _ (tối đa 32 ký tự). Label là văn bản hoặc một object theo ngôn ngữ như {"de": "Farbe", "en": "Colour"}, tối đa 80 ký tự. Widget đọc các giá trị từ livedeck.settings.

text

Các trường: default, maxLength (tối đa 200)

Giá trị trong widget: Văn bản

number

Các trường: default, min, max, step (đều không bắt buộc)

Giá trị trong widget: Số

range

Các trường: default, min và max (bắt buộc), step

Giá trị trong widget: Số, hiển thị dạng thanh trượt trong editor

boolean

Các trường: default

Giá trị trong widget: true hoặc false

color

Các trường: default dạng #rrggbb

Giá trị trong widget: Màu dạng #rrggbb

select

Các trường: options (1 đến 50, mỗi mục có value và label), default

Giá trị trong widget: value của tùy chọn được chọn

gift

Các trường: default (ID quà hoặc null)

Giá trị trong widget: ID quà dạng số, hoặc null

media

Các trường: accept: audio, image hoặc video. Không có default.

Giá trị trong widget: true khi người dùng chọn file của riêng họ, nếu không thì false

Lưu ý: Cài đặt media không bao giờ cung cấp địa chỉ của file cho widget. Phát âm thanh bằng livedeck.media.play(key); lấy hình ảnh và clip bằng livedeck.media.url(key).

Khi một giá trị bị thiếu hoặc không hợp lệ, widget sẽ nhận giá trị mặc định. Nhờ vậy, các bản cập nhật có cài đặt mới vẫn hoạt động với tất cả những ai đang dùng widget của bạn.

Lỗi trong manifest.json

Khi kiểm tra thất bại với thông báo "manifest.json is invalid", mã lỗi và vị trí sẽ được liệt kê bên dưới, ví dụ settings[2].default.

manifest_not_object

File không phải là một đối tượng JSON.

manifest_too_large

File lớn hơn 64 KB.

manifest_invalid_json

JSON không hợp lệ (thường do thừa hoặc thiếu một dấu phẩy).

unknown_field

Trường này không tồn tại. Thường là do gõ sai.

required

Thiếu một trường bắt buộc.

wrong_type

Sai kiểu dữ liệu, ví dụ là văn bản thay vì danh sách.

unsupported_manifest_version

manifestVersion không phải là 1.

unsupported_sdk

sdk không phải là "1".

invalid_name

Tên bị trống, dài hơn 60 ký tự hoặc chứa ký tự điều khiển ẩn.

invalid_text

Văn bản bị trống, quá dài hoặc chứa ký tự điều khiển ẩn.

invalid_version

Phiên bản không theo dạng x.y.z (ví dụ 1.0.0).

invalid_entry

entry không phải là đường dẫn tương đối đến một file .html.

invalid_format

Định dạng không phải là "9:16" hoặc "16:9".

duplicate

Mục bị trùng lặp.

invalid_size

Kích thước nằm ngoài khoảng 16 đến 3840 pixel, hoặc default không nằm giữa min và max.

unknown_permission

Quyền này không tồn tại.

too_many_settings

Nhiều hơn 40 cài đặt.

invalid_setting_key

key không khớp với mẫu (xem ở trên).

unknown_setting_type

Loại cài đặt này không tồn tại.

invalid_default

default không phù hợp với kiểu hoặc nằm ngoài giới hạn.

invalid_bounds

min, max, step hoặc maxLength không hợp lệ.

invalid_options

options bị thiếu, trống, nhiều hơn 50, hoặc có một tùy chọn không có value.

invalid_media_kind

accept không phải là audio, image hoặc video.

invalid_locale

Ngôn ngữ này không tồn tại. Được phép: en, de, tr, fr, es, it, ru, ar, zh-CN, ja, he, pt, nl, pl, uk, ko, hi, id, vi, th.

Bài viết này có hữu ích không?