Livedeck 위젯용 manifest.json: 필드, 권한, 오류 코드
manifest.json의 모든 필드, 권한, 설정 유형과 각 오류 코드의 의미를 알려드려요.
manifest.json은 위젯을 설명하는 파일이에요. Livedeck은 업로드 시 이 파일을 읽고, 이를 바탕으로 에디터 설정을 만들며, 여기에 적힌 권한만 위젯에 부여해요. 오타가 묻히지 않도록 알 수 없는 필드는 오류로 처리돼요.
{
"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
필수 항목: 예
의미: 위젯 이름, 최대 60자
version
필수 항목: 예
의미: 버전 번호 x.y.z, 예: 1.2.0
sdk
필수 항목: 예
의미: SDK 버전, 현재는 "1"
entry
필수 항목: 아니요
의미: 시작 파일, 기본값은 index.html. .html로 끝나야 해요.
description
필수 항목: 아니요
의미: 짧은 설명, 최대 300자
formats
필수 항목: 아니요
의미: ["9:16"], ["16:9"] 또는 둘 다(기본값: 둘 다)
size
필수 항목: 예
의미: 오버레이 캔버스에서의 픽셀 크기: default, min, max를 [너비, 높이]로 지정
permissions
필수 항목: 아니요
의미: 위젯이 받는 데이터(아래 참고)
settings
필수 항목: 아니요
의미: 사용자가 에디터에서 바꾸는 설정(최대 40개)
locales
필수 항목: 아니요
의미: 위젯이 지원하는 언어, 예: ["de", "en"]
| 필드 | 필수 항목 | 의미 |
|---|---|---|
| manifestVersion | 예 | 항상 1 |
| name | 예 | 위젯 이름, 최대 60자 |
| version | 예 | 버전 번호 x.y.z, 예: 1.2.0 |
| sdk | 예 | SDK 버전, 현재는 "1" |
| entry | 아니요 | 시작 파일, 기본값은 index.html. .html로 끝나야 해요. |
| description | 아니요 | 짧은 설명, 최대 300자 |
| formats | 아니요 | ["9:16"], ["16:9"] 또는 둘 다(기본값: 둘 다) |
| size | 예 | 오버레이 캔버스에서의 픽셀 크기: default, min, max를 [너비, 높이]로 지정 |
| permissions | 아니요 | 위젯이 받는 데이터(아래 참고) |
| settings | 아니요 | 사용자가 에디터에서 바꾸는 설정(최대 40개) |
| locales | 아니요 | 위젯이 지원하는 언어, 예: ["de", "en"] |
캔버스는 9:16에서 1080 × 1920픽셀, 16:9에서 1920 × 1080픽셀이에요. 크기는 16~3840픽셀까지 가능해요. min과 max는 사용자가 에디터에서 위젯 크기를 조절할 때의 한계값이에요. 지정하지 않으면 default가 적용돼요. 위젯은 default 기준의 고정 픽셀로 만드세요. 사용자가 크기를 조절하면 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)
| 권한 | 위젯이 받는 것 |
|---|---|
| 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자예요. 위젯은 livedeck.settings에서 값을 읽어요.
text
필드: default, maxLength(최대 200)
위젯에서의 값: 텍스트
number
필드: default, min, max, step(모두 선택)
위젯에서의 값: 숫자
range
필드: default, min, max(필수), step
위젯에서의 값: 숫자, 에디터에서 슬라이더로 표시
boolean
필드: default
위젯에서의 값: true 또는 false
color
필드: default(#rrggbb 형식)
위젯에서의 값: #rrggbb 형식의 색상
select
필드: options(1~50개, 각각 value와 label 포함), default
위젯에서의 값: 선택한 옵션의 value
gift
필드: default(선물 ID 또는 null)
위젯에서의 값: 숫자 형식의 선물 ID 또는 null
media
필드: accept: audio, image 또는 video. default 없음.
위젯에서의 값: 사용자가 직접 파일을 선택했으면 true, 아니면 false
| 유형 | 필드 | 위젯에서의 값 |
|---|---|---|
| text | default, maxLength(최대 200) | 텍스트 |
| number | default, min, max, step(모두 선택) | 숫자 |
| range | default, min, max(필수), step | 숫자, 에디터에서 슬라이더로 표시 |
| boolean | default | true 또는 false |
| color | default(#rrggbb 형식) | #rrggbb 형식의 색상 |
| select | options(1~50개, 각각 value와 label 포함), default | 선택한 옵션의 value |
| gift | default(선물 ID 또는 null) | 숫자 형식의 선물 ID 또는 null |
| media | accept: audio, image 또는 video. default 없음. | 사용자가 직접 파일을 선택했으면 true, 아니면 false |
값이 없거나 올바르지 않으면 위젯은 기본값을 받아요. 그래서 새 설정이 추가된 업데이트도 이미 위젯을 쓰고 있는 모든 사용자에게 문제없이 적용돼요.
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.
| 코드 | 의미 |
|---|---|
| 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. |
이 글이 도움이 되었나요?