@ampless/plugin-analytics-ga4 0.2.0-alpha.1 → 0.2.0-alpha.10

package/README.ja.md

@@ -40,6 +40,49 @@ export default defineConfig({
 |---|---|---|
 | `measurementId` | 必須 | GA4 の計測 ID。例: `G-XXXXXXXX`。空文字 `''` を渡すとプラグインを残したまま注入だけ無効化できる。 |
 | `instanceId` | `'analytics-ga4'` | 生成される `<script>` 要素 id の namespace。同じサイトに複数の GA4 プロパティを入れる場合に分ける。 |
+| `consentCategory` | `''` | オプションの同意カテゴリ slug。設定すると `window.amplessConsent.has(<この値>)` が true になるまで GA4 loader を発火しない。詳細は[同意ゲーティング](#同意ゲーティング)を参照。 |
+
+## 同意ゲーティング
+
+デフォルトでは GA4 loader は訪問者の同意有無にかかわらずページロードごとに発火します。訪問者が同意を付与するまで発火を遅延させるには、`consentCategory` に同意カテゴリ slug を設定し、同じ `cms.config.ts` に `@ampless/plugin-cookie-consent` を登録します:
+
+```ts
+import { defineConfig } from 'ampless'
+import cookieConsent from '@ampless/plugin-cookie-consent'
+import analyticsGa4Plugin from '@ampless/plugin-analytics-ga4'
+
+export default defineConfig({
+  plugins: [
+    // cookie-consent は analytics plugin より前に置く
+    cookieConsent({
+      categories: [{ id: 'analytics', label: 'アナリティクス', defaultEnabled: false }],
+    }),
+    analyticsGa4Plugin({
+      measurementId: 'G-XXXXXXXX',
+      consentCategory: 'analytics',
+    }),
+  ],
+})
+```
+
+`consentCategory` を設定すると plugin は **gated mode** に切り替わります: 標準 GA4 の 2 descriptor の代わりに単一のインライン script を emit し、以下の動作をします:
+
+1. 直ちに `window.amplessConsent.has('analytics')` を確認（前回の訪問で同意が付与されて `localStorage` から復元されているケースに対応）。
+2. false なら `window.amplessConsent.on('analytics', ...)` で同意イベントを購読して待機。
+3. analytics plugin が cookie-consent plugin の API install より先にロードされたケースに備え、`ampless:consent-ready` イベントも購読。
+
+**Fail-closed 契約:** `consentCategory` を設定したまま `@ampless/plugin-cookie-consent` を登録しなかった場合、`window.amplessConsent` は install されません。GA4 は**永久に発火しない**まま 5 秒後に `console.warn` が出力されます:
+
+```
+[ampless:analytics-ga4] consentCategory is set but window.amplessConsent never installed.
+Did you forget to register @ampless/plugin-cookie-consent?
+```
+
+この warning は本番環境でも発火します。設定ミスを早期に検出するためのものであり、抑制する仕組みはありません。
+
+**プラグインの順序:** `plugins` 配列内で `@ampless/plugin-cookie-consent` を analytics plugin より前に置いてください。runtime はプラグインを順番に処理するため、cookie-consent を先に置くことで analytics の gating ロジック実行時に `window.amplessConsent` が確実に install されます。
+
+Consent Convention および `window.amplessConsent` API の詳細は [docs/architecture/08-plugin-architecture.md](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md) を参照してください。
 
 ## measurement ID の取得
 

package/README.md

@@ -40,6 +40,49 @@ export default defineConfig({
 |---|---|---|
 | `measurementId` | required | Your GA4 measurement ID, e.g. `G-XXXXXXXX`. Set to `''` to disable the plugin without removing it from `cms.config.ts`. |
 | `instanceId` | `'analytics-ga4'` | Namespace used for the script element ids. Set distinct values when registering multiple GA4 properties on the same site. |
+| `consentCategory` | `''` | Optional consent category slug. When set, the GA4 loader fires only after `window.amplessConsent.has(<this>)` returns true. See [Consent gating](#consent-gating) below. |
+
+## Consent gating
+
+By default the GA4 loader fires on every page load regardless of visitor consent. To make it fire only after the visitor has granted consent, set `consentCategory` to a category slug and register `@ampless/plugin-cookie-consent` in the same `cms.config.ts`:
+
+```ts
+import { defineConfig } from 'ampless'
+import cookieConsent from '@ampless/plugin-cookie-consent'
+import analyticsGa4Plugin from '@ampless/plugin-analytics-ga4'
+
+export default defineConfig({
+  plugins: [
+    // cookie-consent must appear before the analytics plugin
+    cookieConsent({
+      categories: [{ id: 'analytics', label: 'Analytics', defaultEnabled: false }],
+    }),
+    analyticsGa4Plugin({
+      measurementId: 'G-XXXXXXXX',
+      consentCategory: 'analytics',
+    }),
+  ],
+})
+```
+
+When `consentCategory` is set the plugin switches to **gated mode**: instead of the two standard GA4 descriptors, it emits a single inline script that:
+
+1. Checks `window.amplessConsent.has('analytics')` immediately (covers the case where consent was granted in a previous visit and 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 analytics 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. GA4 will **never fire**, and after 5 seconds a `console.warn` appears:
+
+```
+[ampless:analytics-ga4] 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 analytics plugin in the `plugins` array. The runtime processes plugins in order; placing cookie-consent first ensures `window.amplessConsent` is installed before the analytics gating logic runs.
+
+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).
 
 ## Getting your measurement ID
 

package/dist/index.d.ts

@@ -22,6 +22,13 @@ interface AnalyticsGa4Options {
      * site).
      */
     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 GA4 plugin. Returns a plugin manifest that emits

package/dist/index.js

@@ -1,9 +1,14 @@
 // src/index.ts
 import { definePlugin } from "ampless";
 function analyticsGa4Plugin(options = {}) {
-  const { measurementId = "", instanceId = "analytics-ga4" } = options;
+  const {
+    measurementId = "",
+    instanceId = "analytics-ga4",
+    consentCategory = ""
+  } = options;
   return definePlugin({
     name: "analytics-ga4",
+    packageName: "@ampless/plugin-analytics-ga4",
     instanceId,
     displayName: { en: "Google Analytics 4", ja: "Google Analytics 4" },
     apiVersion: 1,
@@ -29,12 +34,74 @@ function analyticsGa4Plugin(options = {}) {
           pattern: "^$|^G-[A-Z0-9]+$",
           placeholder: "G-XXXXXXXX",
           default: measurementId
+        },
+        {
+          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
         }
       ]
     },
     publicHead(ctx) {
       const id = (ctx.setting("measurementId") ?? "").trim();
       if (!id) return [];
+      const category = (ctx.setting("consentCategory") ?? "").trim();
+      if (category) {
+        const loaderSrc = `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(id)}`;
+        return [
+          {
+            type: "inlineScript",
+            id: `ga4-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(loaderSrc)}`,
+              "    s.async = true",
+              "    document.head.appendChild(s)",
+              "    // Bind dataLayer + gtag to `window` so later page code",
+              "    // (e.g. window.gtag('event', ...) in custom handlers)",
+              "    // can find them. The non-gated snippet relies on a",
+              "    // top-level `function gtag(){}` hoisting to global,",
+              "    // which inside this IIFE would only be a local \u2014 so",
+              "    // we assign explicitly and preserve any gtag that a",
+              "    // user script may have installed first.",
+              "    window.dataLayer = window.dataLayer || []",
+              "    window.gtag = window.gtag || function () { window.dataLayer.push(arguments) }",
+              "    window.gtag('js', new Date())",
+              `    window.gtag('config', ${JSON.stringify(id)})`,
+              "  }",
+              "  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:analytics-ga4] 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-analytics-ga4",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.10",
   "description": "Google Analytics 4 plugin for ampless",
   "license": "MIT",
   "type": "module",
@@ -8,7 +8,8 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -25,15 +26,29 @@
   "homepage": "https://github.com/heavymoons/ampless/tree/main/packages/plugin-analytics-ga4#readme",
   "bugs": "https://github.com/heavymoons/ampless/issues",
   "dependencies": {
-    "ampless": "1.0.0-alpha.18"
+    "ampless": "1.0.0-alpha.26"
   },
   "keywords": [
     "ampless",
     "plugin",
+    "ampless-plugin",
     "analytics",
     "ga4",
     "google-analytics"
   ],
+  "amplessPlugin": {
+    "apiVersion": 1,
+    "name": "analytics-ga4",
+    "trustLevel": "untrusted",
+    "capabilities": [
+      "publicHead",
+      "adminSettings"
+    ],
+    "displayName": {
+      "en": "Google Analytics 4",
+      "ja": "Google Analytics 4"
+    }
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",