@ampless/plugin-gtm 0.1.1-alpha.8 → 0.2.0-alpha.10

package/README.ja.md

@@ -44,6 +44,51 @@ export default defineConfig({
 |---|---|---|
 | `containerId` | `''` | 初期 GTM コンテナ ID。例: `GTM-XXXXXXX`。マニフェストの default を seed するだけで、ライブ値はリクエスト時に `/admin/plugins` から読み出される。空文字でプラグインを無効化したまま ship できる。 |
 | `instanceId` | `'gtm'` | script / noscript 要素 id と設定保存キーの namespace。同サイトに複数の GTM コンテナを入れる場合に分ける。 |
+| `consentCategory` | `''` | オプションの同意カテゴリ slug。設定すると `window.amplessConsent.has(<この値>)` が true になるまで GTM loader を発火しない。gated mode では `<noscript>` fallback は出力されない。詳細は[同意ゲーティング](#同意ゲーティング)を参照。 |
+
+## 同意ゲーティング
+
+デフォルトでは GTM loader は訪問者の同意有無にかかわらずページロードごとに発火します。同意を付与するまで発火を遅延させるには、`consentCategory` に同意カテゴリ slug を設定し、同じ `cms.config.ts` に `@ampless/plugin-cookie-consent` を登録します:
+
+```ts
+import { defineConfig } from 'ampless'
+import cookieConsent from '@ampless/plugin-cookie-consent'
+import gtmPlugin from '@ampless/plugin-gtm'
+
+export default defineConfig({
+  plugins: [
+    // cookie-consent は GTM plugin より前に置く
+    cookieConsent({
+      categories: [{ id: 'analytics', label: 'アナリティクス', defaultEnabled: false }],
+    }),
+    gtmPlugin({
+      containerId: 'GTM-XXXXXXX',
+      consentCategory: 'analytics',
+    }),
+  ],
+})
+```
+
+`consentCategory` を設定すると plugin は **gated mode** に切り替わります: 標準のインライン loader script の代わりに単一のインライン script を emit し、以下の動作をします:
+
+1. 直ちに `window.amplessConsent.has('analytics')` を確認（`localStorage` から復元した同意に対応）。
+2. false なら `window.amplessConsent.on('analytics', ...)` で同意イベントを購読して待機。
+3. GTM plugin が cookie-consent plugin より先にロードされたケースに備え、`ampless:consent-ready` イベントも購読。
+
+**gated mode では `<noscript>` fallback を出力しません。** `consentCategory` が設定されている場合、通常 `publicBodyEnd` から出力される GTM の fallback iframe は省略されます。理由: JavaScript を無効にした環境では同意バナーを動かせないため、ゲーティング自体が不能です。fallback を抑制することでトラッキングを出さないのが正しいトレードオフです。これは意図した仕様変更であり、必要に応じてサイトのプライバシーポリシーに記載してください。
+
+**Fail-closed 契約:** `consentCategory` を設定したまま `@ampless/plugin-cookie-consent` を登録しなかった場合、`window.amplessConsent` は install されません。GTM は**永久に発火しない**まま 5 秒後に `console.warn` が出力されます:
+
+```
+[ampless:gtm] consentCategory is set but window.amplessConsent never installed.
+Did you forget to register @ampless/plugin-cookie-consent?
+```
+
+この warning は本番環境でも発火します。設定ミスを早期に検出するためのものであり、抑制する仕組みはありません。
+
+**プラグインの順序:** `plugins` 配列内で `@ampless/plugin-cookie-consent` を GTM 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) を参照してください。
 
 ## 管理画面からコンテナ ID を編集する
 

package/README.md

@@ -44,6 +44,51 @@ export default defineConfig({
 |---|---|---|
 | `containerId` | `''` | Initial GTM container ID, e.g. `GTM-XXXXXXX`. Seeds the manifest default — the live value is read from `/admin/plugins` at request time. Set to `''` to ship the plugin disabled. |
 | `instanceId` | `'gtm'` | Namespace used for the script / noscript element ids and the settings storage key. Set distinct values when registering multiple GTM containers on the same site. |
+| `consentCategory` | `''` | Optional consent category slug. When set, the GTM loader fires only after `window.amplessConsent.has(<this>)` returns true. The `<noscript>` fallback is suppressed in this mode. See [Consent gating](#consent-gating) below. |
+
+## Consent gating
+
+By default the GTM 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 gtmPlugin from '@ampless/plugin-gtm'
+
+export default defineConfig({
+  plugins: [
+    // cookie-consent must appear before the analytics plugin
+    cookieConsent({
+      categories: [{ id: 'analytics', label: 'Analytics', defaultEnabled: false }],
+    }),
+    gtmPlugin({
+      containerId: 'GTM-XXXXXXX',
+      consentCategory: 'analytics',
+    }),
+  ],
+})
+```
+
+When `consentCategory` is set the plugin switches to **gated mode**: the standard inline loader script is replaced by 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 GTM plugin loads before the cookie-consent plugin has installed its global API.
+
+**`<noscript>` fallback is suppressed in gated mode.** The standard GTM fallback iframe (emitted by `publicBodyEnd`) is omitted when `consentCategory` is set. Rationale: JavaScript-less environments cannot run the consent banner UI, so there is no meaningful way to gate tracking. Suppressing the fallback is the correct trade-off — it avoids tracking visitors who have not consented. This is an intentional behavior change. Document it in your site's privacy policy if needed.
+
+**Fail-closed contract:** if `consentCategory` is set but `@ampless/plugin-cookie-consent` is never registered, `window.amplessConsent` is never installed. GTM will **never fire**, and after 5 seconds a `console.warn` appears:
+
+```
+[ampless:gtm] 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 GTM 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 the container ID from the admin UI
 

package/dist/index.d.ts

@@ -20,6 +20,17 @@ interface GtmOptions {
      * marketing + a product container on the same 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.
+     *
+     * Note: in gated mode the `<noscript>` fallback in publicBodyEnd
+     * is suppressed — JavaScript-less environments cannot run the
+     * consent UI so there is no meaningful way to gate.
+     */
+    consentCategory?: string;
 }
 /**
  * Factory for the GTM plugin. Returns a plugin manifest that emits

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/index.ts
 import { definePlugin } from "ampless";
 function gtmPlugin(options = {}) {
-  const { containerId = "", instanceId = "gtm" } = options;
+  const { containerId = "", instanceId = "gtm", consentCategory = "" } = options;
   return definePlugin({
     name: "gtm",
     packageName: "@ampless/plugin-gtm",
@@ -30,12 +30,60 @@ function gtmPlugin(options = {}) {
           pattern: "^$|^GTM-[A-Z0-9]+$",
           placeholder: "GTM-XXXXXXX",
           default: containerId
+        },
+        {
+          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). Note: in gated mode the <noscript> fallback is suppressed. 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\u6CE8\u610F: gated mode \u3067\u306F <noscript> fallback \u306F\u51FA\u529B\u3055\u308C\u307E\u305B\u3093\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("containerId") ?? "").trim();
       if (!id) return [];
+      const category = (ctx.setting("consentCategory") ?? "").trim();
+      if (category) {
+        return [
+          {
+            type: "inlineScript",
+            id: `gtm-gated-${instanceId}`,
+            strategy: "afterInteractive",
+            body: [
+              "(function () {",
+              "  var initialized = false",
+              "  function init() {",
+              "    if (initialized) return",
+              "    initialized = true",
+              `    var gtmSrc = 'https://www.googletagmanager.com/gtm.js?id=' + ${JSON.stringify(id)}`,
+              "    ;(function(w,d,s,l){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],j=d.createElement(s);j.async=true;j.src=gtmSrc;f.parentNode.insertBefore(j,f);})(window,document,'script','dataLayer')",
+              "  }",
+              "  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:gtm] consentCategory is set but window.amplessConsent never installed. Did you forget to register @ampless/plugin-cookie-consent?')",
+              "      }",
+              "    }, 5000)",
+              "  }",
+              "})()"
+            ].join("\n")
+          }
+        ];
+      }
       return [
         {
           type: "inlineScript",
@@ -52,6 +100,8 @@ function gtmPlugin(options = {}) {
     publicBodyEnd(ctx) {
       const id = (ctx.setting("containerId") ?? "").trim();
       if (!id) return [];
+      const category = (ctx.setting("consentCategory") ?? "").trim();
+      if (category) return [];
       return [
         {
           type: "noscript",

package/package.json

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