資訊清單與權限

plugin.manifest.json 會告訴覺城你是誰、體驗託管在哪裡，以及可以要求哪些權限。我們會核准特定版本、入口與權限的確切組合；任一項變更，新版本都必須重新核准。

範例

plugin.manifest.json

{
  "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 網址，不可包含使用者名稱、密碼或片段。只有 localhost 可使用純 HTTP。不可與平台共用來源網域。
`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 可供使用。驗證不會授予任何權限，只有核准才會。

shell

npx zenclub-plugin validate plugin.manifest.json --host=https://zenclub.app

主機 API 版本

目前的主機 API 為 1.5，並接受要求 1.0 至 1.5 的外掛。請要求你所需的最低次版本，並用 sdk.supports() 檢查選用方法。若要接收聲音偏好，清單和 connect() 都必須要求 1.5。無須新增權限；要求 1.0 至 1.4 的外掛收到的情境資訊和事件與以往相同。

選用的城市里程碑

將 milestones.report 宣告為選填，並且只加入一個 milestones 項目。首個版本有八個固定鍵：homestead、pond、clouds、bamboo、tea、stream、bell 和 lotus。每條規則的版本都是其鍵名後接 .1，並設為 maxTier: 2。核准會固定該組合、版本、入口與功能。自行撰寫宣告不會取得存取權。

plugin.manifest.json

{
  "hostApi": {"major": 1, "minMinor": 6},
  "optionalPermissions": ["milestones.report"],
  "milestones": [{"key": "tea", "ruleVersion": "tea.1", "maxTier": 2}]
}

使用 SDK 0.9 建置的外掛程式，在回報功能為選填時可以沿用較舊的最低需求版本。在 1.0–1.5 主機上、尚未取得核准，或使用僅限裝置的儲存空間時，請維持正常遊玩並略過回報。較舊主機的核准不得包含新授權。必要的里程碑回報需要 1.6；記錄功能絕不可成為遊玩或登入的先決條件。