@ampless/plugin-plausible 0.1.1-alpha.8 → 0.2.0-alpha.11

package/README.ja.md

@@ -43,6 +43,49 @@ export default defineConfig({
 | `domain` | `''` | 初期 Plausible サイトドメイン。例: `example.com`。Plausible 管理画面に登録した値と完全一致させる必要がある — ミスマッチだとページビューが silently drop される。空文字でプラグインを無効化したまま ship できる。 |
 | `scriptUrl` | `'https://plausible.io/js/script.js'` | Plausible スクリプトの URL。self-hosted Plausible を使う場合に上書き（例: `'https://analytics.example.com/js/script.js'`）。admin field は **required** なので値を消すことはできない。plausible.io デフォルトに戻すには admin form の **デフォルトに戻す** を使う。 |
 | `instanceId` | `'plausible'` | script 要素 id と設定保存キーの namespace。同サイトに複数の Plausible site を入れる場合に分ける。 |
+| `consentCategory` | `''` | オプションの同意カテゴリ slug。設定すると `window.amplessConsent.has(<この値>)` が true になるまで Plausible loader を発火しない。詳細は[同意ゲーティング](#同意ゲーティング)を参照。 |
+
+## 同意ゲーティング
+
+Plausible はプライバシー重視・cookie 不使用の解析サービスであり、多くの導入では同意ゲーティングは不要です。ただし、サイトの法的要件やプライバシーポリシーで解析スクリプト読み込み前の明示的同意が必要な場合は gated mode を有効にできます:
+
+```ts
+import { defineConfig } from 'ampless'
+import cookieConsent from '@ampless/plugin-cookie-consent'
+import plausiblePlugin from '@ampless/plugin-plausible'
+
+export default defineConfig({
+  plugins: [
+    // cookie-consent は Plausible plugin より前に置く
+    cookieConsent({
+      categories: [{ id: 'analytics', label: 'アナリティクス', defaultEnabled: false }],
+    }),
+    plausiblePlugin({
+      domain: 'example.com',
+      consentCategory: 'analytics',
+    }),
+  ],
+})
+```
+
+`consentCategory` を設定すると plugin は **gated mode** に切り替わります: 標準の `<script>` descriptor の代わりに単一のインライン script を emit し、以下の動作をします:
+
+1. 直ちに `window.amplessConsent.has('analytics')` を確認（`localStorage` から復元した同意に対応）。
+2. false なら `window.amplessConsent.on('analytics', ...)` で同意イベントを購読して待機。
+3. Plausible plugin が cookie-consent plugin より先にロードされたケースに備え、`ampless:consent-ready` イベントも購読。
+
+**Fail-closed 契約:** `consentCategory` を設定したまま `@ampless/plugin-cookie-consent` を登録しなかった場合、`window.amplessConsent` は install されません。Plausible は**永久に発火しない**まま 5 秒後に `console.warn` が出力されます:
+
+```
+[ampless:plausible] consentCategory is set but window.amplessConsent never installed.
+Did you forget to register @ampless/plugin-cookie-consent?
+```
+
+この warning は本番環境でも発火します。設定ミスを早期に検出するためのものであり、抑制する仕組みはありません。
+
+**プラグインの順序:** `plugins` 配列内で `@ampless/plugin-cookie-consent` を Plausible plugin より前に置いてください。
+
+Consent Convention および `window.amplessConsent` API の詳細は [docs/architecture/08-plugin-architecture.md](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md) を参照してください。
 
 ## 管理画面から設定を編集する
 

package/README.md

@@ -43,6 +43,49 @@ export default defineConfig({
 | `domain` | `''` | Initial Plausible site domain, e.g. `example.com`. Must match the value registered in the Plausible dashboard exactly — a mismatch silently drops every pageview. Set to `''` to ship the plugin disabled. |
 | `scriptUrl` | `'https://plausible.io/js/script.js'` | URL of the Plausible script. Override for self-hosted Plausible (e.g. `'https://analytics.example.com/js/script.js'`). The admin field is **required**, so the value can't be cleared — to switch back to the hosted plausible.io URL, use **Reset to default** in the admin form. |
 | `instanceId` | `'plausible'` | Namespace used for the script element id and settings storage key. Set distinct values when registering multiple Plausible sites on the same deployment. |
+| `consentCategory` | `''` | Optional consent category slug. When set, the Plausible loader fires only after `window.amplessConsent.has(<this>)` returns true. See [Consent gating](#consent-gating) below. |
+
+## Consent gating
+
+Plausible is a privacy-focused, cookie-free analytics service — most deployments do not need consent gating at all. However, if your site's legal requirements or privacy policy demand explicit consent before any analytics script loads, you can enable gated mode:
+
+```ts
+import { defineConfig } from 'ampless'
+import cookieConsent from '@ampless/plugin-cookie-consent'
+import plausiblePlugin from '@ampless/plugin-plausible'
+
+export default defineConfig({
+  plugins: [
+    // cookie-consent must appear before the analytics plugin
+    cookieConsent({
+      categories: [{ id: 'analytics', label: 'Analytics', defaultEnabled: false }],
+    }),
+    plausiblePlugin({
+      domain: 'example.com',
+      consentCategory: 'analytics',
+    }),
+  ],
+})
+```
+
+When `consentCategory` is set the plugin switches to **gated mode**: instead of the standard `<script>` descriptor, it emits a single inline script that:
+
+1. Checks `window.amplessConsent.has('analytics')` immediately (covers consent restored from `localStorage`).
+2. Otherwise subscribes to the consent event via `window.amplessConsent.on('analytics', ...)` and waits.
+3. Also listens for `ampless:consent-ready` in case the Plausible plugin loads before the cookie-consent plugin has installed its global API.
+
+**Fail-closed contract:** if `consentCategory` is set but `@ampless/plugin-cookie-consent` is never registered, `window.amplessConsent` is never installed. Plausible will **never fire**, and after 5 seconds a `console.warn` appears:
+
+```
+[ampless:plausible] consentCategory is set but window.amplessConsent never installed.
+Did you forget to register @ampless/plugin-cookie-consent?
+```
+
+This warning fires in production too — it is intended to help operators catch misconfiguration quickly. There is no mechanism to suppress it.
+
+**Plugin ordering:** register `@ampless/plugin-cookie-consent` before the Plausible plugin in the `plugins` array.
+
+For full details on the Consent Convention and the `window.amplessConsent` API see [docs/architecture/08-plugin-architecture.md](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md).
 
 ## Editing settings from the admin UI
 

package/dist/index.d.ts

@@ -33,6 +33,13 @@ interface PlausibleOptions {
      * deployment).
      */
     instanceId?: string;
+    /**
+     * Optional consent category. When set, the analytics loader does
+     * not run until window.amplessConsent.has(consentCategory) returns
+     * true. See @ampless/plugin-cookie-consent and the Consent
+     * Convention in docs/architecture/08-plugin-architecture.md.
+     */
+    consentCategory?: string;
 }
 /**
  * Factory for the Plausible plugin. Emits a single `<script>`

package/dist/index.js

@@ -5,7 +5,8 @@ function plausiblePlugin(options = {}) {
   const {
     domain = "",
     scriptUrl = DEFAULT_SCRIPT_URL,
-    instanceId = "plausible"
+    instanceId = "plausible",
+    consentCategory = ""
   } = options;
   return definePlugin({
     name: "plausible",
@@ -56,6 +57,19 @@ function plausiblePlugin(options = {}) {
           allowRelative: false,
           placeholder: DEFAULT_SCRIPT_URL,
           default: scriptUrl
+        },
+        {
+          type: "text",
+          key: "consentCategory",
+          label: { en: "Consent category", ja: "\u540C\u610F\u30AB\u30C6\u30B4\u30EA" },
+          description: {
+            en: "Optional. When set, the analytics loader fires only after `window.amplessConsent.has(<this>)` returns true. Requires `@ampless/plugin-cookie-consent` to also be registered \u2014 fail-closed otherwise (no tracking, console warning after 5s). See the Consent Convention in the plugin author guide.",
+            ja: "\u30AA\u30D7\u30B7\u30E7\u30F3\u3002\u8A2D\u5B9A\u3059\u308B\u3068 `window.amplessConsent.has(<value>)` \u304C true \u306B\u306A\u308B\u307E\u3067 analytics loader \u3092\u767A\u706B\u3057\u307E\u305B\u3093\u3002`@ampless/plugin-cookie-consent` \u306E\u4F75\u7528\u304C\u5FC5\u9808 \u2014 \u672A\u5C0E\u5165\u6642\u306F\u5B8C\u5168\u306B\u767A\u706B\u305B\u305A 5 \u79D2\u5F8C\u306B console warning (fail-closed)\u3002\u8A73\u7D30\u306F plugin author guide \u306E Consent Convention \u7BC0\u3092\u53C2\u7167\u3002"
+          },
+          pattern: "^$|^[a-z][a-z0-9_-]*$",
+          maxLength: 32,
+          placeholder: "analytics",
+          default: consentCategory
         }
       ]
     },
@@ -63,6 +77,44 @@ function plausiblePlugin(options = {}) {
       const resolvedDomain = (ctx.setting("domain") ?? "").trim();
       const resolvedScriptUrl = (ctx.setting("scriptUrl") ?? "").trim();
       if (!resolvedDomain || !resolvedScriptUrl) return [];
+      const category = (ctx.setting("consentCategory") ?? "").trim();
+      if (category) {
+        return [
+          {
+            type: "inlineScript",
+            id: `plausible-gated-${instanceId}`,
+            strategy: "afterInteractive",
+            body: [
+              "(function () {",
+              "  var initialized = false",
+              "  function init() {",
+              "    if (initialized) return",
+              "    initialized = true",
+              "    var s = document.createElement('script')",
+              `    s.src = ${JSON.stringify(resolvedScriptUrl)}`,
+              "    s.defer = true",
+              `    s.setAttribute('data-domain', ${JSON.stringify(resolvedDomain)})`,
+              "    document.head.appendChild(s)",
+              "  }",
+              "  function wait() {",
+              `    if (window.amplessConsent.has(${JSON.stringify(category)})) init()`,
+              `    else window.amplessConsent.on(${JSON.stringify(category)}, init)`,
+              "  }",
+              "  if (window.amplessConsent) {",
+              "    wait()",
+              "  } else {",
+              "    window.addEventListener('ampless:consent-ready', wait, { once: true })",
+              "    setTimeout(function () {",
+              "      if (!window.amplessConsent) {",
+              "        console.warn('[ampless:plausible] consentCategory is set but window.amplessConsent never installed. Did you forget to register @ampless/plugin-cookie-consent?')",
+              "      }",
+              "    }, 5000)",
+              "  }",
+              "})()"
+            ].join("\n")
+          }
+        ];
+      }
       return [
         {
           type: "script",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/plugin-plausible",
-  "version": "0.1.1-alpha.8",
+  "version": "0.2.0-alpha.11",
   "description": "Plausible Analytics plugin for ampless",
   "license": "MIT",
   "type": "module",
@@ -26,7 +26,7 @@
   "homepage": "https://github.com/heavymoons/ampless/tree/main/packages/plugin-plausible#readme",
   "bugs": "https://github.com/heavymoons/ampless/issues",
   "dependencies": {
-    "ampless": "1.0.0-alpha.26"
+    "ampless": "1.0.0-alpha.28"
   },
   "keywords": [
     "ampless",