Livedeck 위젯용 manifest.json: 필드, 권한, 오류 코드

manifest.json의 모든 필드, 권한, 설정 유형과 각 오류 코드의 의미를 알려드려요.

8분 분량 2026년 11월 4일 업데이트

manifest.json은 위젯을 설명하는 파일이에요. 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

필수 항목: 예

의미: 위젯 이름, 최대 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)

설정

모든 설정에는 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

참고: 미디어 설정은 위젯에 파일 주소를 절대 넘겨주지 않아요. 사운드는 livedeck.media.play(key)로 재생하고, 이미지와 클립은 livedeck.media.url(key)로 가져오세요.

값이 없거나 올바르지 않으면 위젯은 기본값을 받아요. 그래서 새 설정이 추가된 업데이트도 이미 위젯을 쓰고 있는 모든 사용자에게 문제없이 적용돼요.

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.

이 글이 도움이 되었나요?