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.
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.
{
"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"]
| Trường | Bắt buộc | Ý nghĩa |
|---|---|---|
| manifestVersion | có | Luôn là 1 |
| name | có | Tên widget, tối đa 60 ký tự |
| version | có | Số phiên bản x.y.z, ví dụ 1.2.0 |
| sdk | có | Phiên bản SDK, hiện tại là "1" |
| entry | không | File khởi động, mặc định là index.html. Phải kết thúc bằng .html. |
| description | không | Mô tả ngắn, tối đa 300 ký tự |
| formats | không | ["9:16"], ["16:9"] hoặc cả hai (mặc định: cả hai) |
| size | có | Kích thước tính bằng pixel trên canvas overlay: default, min và max dạng [rộng, cao] |
| permissions | không | Dữ liệu widget nhận được (xem bên dưới) |
| settings | không | Cài đặt người dùng thay đổi trong editor (tối đa 40) |
| locales | không | 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)
| Quyền | Widget nhận được gì |
|---|---|
| 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
| Loại | Các trường | Giá trị trong widget |
|---|---|---|
| text | default, maxLength (tối đa 200) | Văn bản |
| number | default, min, max, step (đều không bắt buộc) | Số |
| range | default, min và max (bắt buộc), step | Số, hiển thị dạng thanh trượt trong editor |
| boolean | default | true hoặc false |
| color | default dạng #rrggbb | Màu dạng #rrggbb |
| select | options (1 đến 50, mỗi mục có value và label), default | value của tùy chọn được chọn |
| gift | default (ID quà hoặc null) | ID quà dạng số, hoặc null |
| media | accept: audio, image hoặc video. Không có default. | true khi người dùng chọn file của riêng họ, nếu không thì false |
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.
| Mã | Ý nghĩa |
|---|---|
| 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?