マニフェストと権限

plugin.manifest.jsonは、あなたが何者か、体験がどこにあるか、何を要求できるかをZenClubに伝えます。バージョン、エントリー、権限の組み合わせを特定して承認します。いずれかを変更すると、新しいリリースには再承認が必要です。

例

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 URLを指定します。ユーザー名、パスワード、ハッシュは含めません。通常のHTTPはlocalhostでのみ使用できます。プラットフォームと同じオリジンは使えません。
`permissions`	体験の動作に必須の機能を指定します。重複はできません。
`optionalPermissions`	許可された場合に使う機能を最大32個まで指定できます。必須の機能を重ねて指定しないでください。
`milestones`	任意項目です。固定キー、ルールのバージョン、最大段階を1組だけ指定し、報告機能とともに運営者の個別承認を受けます。
`modes`	`watch`、`manual`、`listen`から1つ以上を指定します。宣言したモードだけを報告できます。
`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	プレイヤーが記録を有効にしているとき、確認済みのセーブデータから承認済みの街の飾りを1件報告します。

申請前に検証する

コマンドラインツールはプラットフォームと同じ検査を行い、要求したホストAPIが利用できることを確認します。検証で権限が付与されることはありません。付与するのは承認だけです。

shell

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の項目をちょうど1つ追加します。最初のリリースで使う固定キーは8つです。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}]
}

開発キット0.9で作成したプラグインは、報告機能が任意なら古い最低対応バージョンを維持できます。ホストが1.0〜1.5の場合、承認がない場合、または端末内だけに保存する場合は、通常どおりゲームを動かし、報告を省略してください。旧ホスト向けの承認には新しい権限を含めないでください。節目の報告を必須にするには1.6が必要です。記録をプレイやログインの前提条件にしてはいけません。