매니페스트와 권한
plugin.manifest.json은 플랫폼에 제작자와 경험 위치, 요청할 기능을 알려줘요. 버전, 시작 URL, 권한이 정확히 일치하는 조합 하나를 승인해요. 이 중 하나라도 바꾸면 새 릴리스를 다시 승인받아야 해요.
예시
{
"schema": "zenclub.plugin/v1",
"id": "my-garden",
"name": "My garden",
"description": "Tend a small garden at your own pace.",
"coverLabel": "A small garden",
"version": "1.0.0",
"sdkProtocol": "zenclub.rpc/1",
"hostApi": {"major": 1, "minMinor": 2},
"entry": "https://my-garden.example/v1.0.0/",
"permissions": ["lifecycle.report", "storage.read", "storage.write", "session.report"],
"optionalPermissions": ["moments.create", "header.setActions"],
"modes": ["watch", "manual"],
"tags": ["garden", "slow"]
}필드
| 필드 | 규칙 |
|---|---|
schema | 항상 zenclub.plugin/v1을 사용해요. |
id | 영문자, 숫자, 점, 밑줄 또는 하이픈으로 이루어진 1~80자이며 영문자나 숫자로 시작해요. 변경할 수 없어요. |
name, description, coverLabel | 각 항목은 일반 텍스트로 최대 2048자예요. coverLabel은 표지에 표시되는 짧은 설명이에요. |
version | 1.4.0 또는 1.5.0-beta.1 같은 시맨틱 버전이에요. connect()에 전달하는 version과 일치해야 해요. |
sdkProtocol | 항상 zenclub.rpc/1을 사용해요. |
hostApi | 필요한 최저 호스트 API를 {major, minMinor} 형식으로 적어요. 작동하는 가장 낮은 마이너 버전을 요청해요. |
entry | 사용자 이름, 비밀번호, 해시가 없는 페이지의 절대 HTTPS URL이에요. 일반 HTTP는 localhost에서만 허용돼요. 플랫폼과 출처를 공유할 수 없어요. |
permissions | 경험에 반드시 필요한 기능이에요. 중복 항목은 허용되지 않아요. |
optionalPermissions | 허용될 때 사용할 기능을 최대 32개까지 적어요. 필수 기능을 중복해서 적지 마세요. |
milestones | 선택 사항이에요. 고정 키 하나와 규칙 버전, 최대 단계를 지정하며 보고 기능과 함께 운영자의 별도 승인을 받아야 해요. |
modes | watch, manual, listen 중 하나 이상을 지정해요. 선언한 모드만 보고할 수 있어요. |
tags | 태그는 최대 10개이며 각각 32자 이하여야 해요. |
기능 권한
각 SDK 메서드는 하나의 기능 권한에 해당해요. 허용되지 않은 기능을 호출하면 프레임 밖으로 나가기 전에 FORBIDDEN 오류가 발생해요. 선택 기능은 먼저 sdk.supports(name)으로 확인해요.
| 기능 | 호스트 API | 용도 |
|---|---|---|
lifecycle.report | 1.0 | 로딩, 준비 완료 또는 실패 상태를 보고해요. |
storage.read | 1.0 | 저장 슬롯을 읽어요. |
storage.write | 1.0 | 리비전을 확인해 저장 슬롯에 기록해요. |
session.report | 1.0 | 시간 측정을 위해 실행, 일시 정지 또는 종료 상태를 보고해요. |
runs.finish | 1.0 | 최대 20개의 숫자 지표와 함께 완료 또는 다시 시작한 실행을 기록해요. |
moments.create | 1.0 | 방문자가 간직할 사진을 제안해요. 플랫폼에서 먼저 확인할 수 있어요. |
achievements.request | 1.0 | 플랫폼에 배지 확인과 수여를 요청해요. |
counters.add | 1.2 | 운영자가 정의한 공용 집계값에 수를 더해요. |
events.report | 1.2 | 챕터 완료처럼 짧은 이름의 이벤트를 보고해요. |
shares.request | 1.2 | 배지나 경험을 위한 플랫폼 공유 창을 열어요. |
navigation.exit | 1.2 | 경험 상세 페이지로 조용히 이동해요. |
display.immersive | 1.3 | 플랫폼 프레임을 숨기도록 요청해요. |
header.setActions | 1.4 | 플랫폼 헤더에 동작을 배치해요. |
milestones.report | 1.6 | 플레이어가 기록을 켠 상태에서 저장이 확인되면 승인된 비공개 도시 장식 하나를 보고해요. |
요청 전에 검증하기
명령줄 도구는 플랫폼과 같은 검사를 실행하고 요청한 호스트 API를 사용할 수 있는지 확인해요. 검증만으로 권한이 부여되지는 않아요. 승인을 받아야 해요.
npx zenclub-plugin validate plugin.manifest.json --host=https://zenclub.app호스트 API 버전
현재 호스트 인터페이스는 1.6이며, 1.0부터 1.6까지를 요청하는 플러그인을 받아들여요. 필요한 가장 낮은 부 버전을 요청하고 선택 기능은 sdk.supports()로 확인해요. 소리 설정을 받으려면 매니페스트와 connect()에서 모두 1.5 이상을 요구해야 해요. 이정표 선언이 없는 이전 플러그인은 이전과 같은 권한과 문맥을 받아요.
선택형 도시 이정표
milestones.report를 선택 사항으로 선언하고 milestones 항목을 정확히 하나 추가해요. 첫 배포에는 고정 키 여덟 개가 있어요: homestead, pond, clouds, bamboo, tea, stream, bell, lotus. 각 규칙 버전은 해당 키 뒤에 .1을 붙이며 최대 단계는 maxTier: 2예요. 승인되면 해당 조합과 버전, 항목, 권한이 그대로 고정돼요. 직접 작성한 선언만으로는 접근 권한을 얻을 수 없어요.
{
"hostApi": {"major": 1, "minMinor": 6},
"optionalPermissions": ["milestones.report"],
"milestones": [{"key": "tea", "ruleVersion": "tea.1", "maxTier": 2}]
}개발 도구 0.9로 만든 플러그인은 보고 기능이 선택 사항인 동안 더 낮은 최소 버전을 유지할 수 있어요. 1.0부터 1.5까지의 호스트를 사용하거나, 승인이 없거나, 기기 전용 저장 공간을 사용하는 경우에는 일반 플레이를 유지하고 보고를 건너뛰어요. 이전 호스트의 승인을 설정할 때는 새 권한을 제외해야 해요. 필수 이정표 보고에는 1.6이 필요해요. 기록 기능을 플레이나 로그인 조건으로 삼으면 안 돼요.