npm - @ampless/plugin-gtm - Versions diffs - 0.1.1-alpha.0 - Mend

@ampless/plugin-gtm 0.1.1-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 ampless contributors
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md ADDED Viewed

@@ -0,0 +1,84 @@
+> English: [README.md](./README.md)
+>
+# @ampless/plugin-gtm
+[ampless](https://github.com/heavymoons/ampless) 向け Google Tag Manager プラグイン。
+> **プレリリース / アルファ版。** v1.0 まではマイナーバージョンでも破壊的変更が入る可能性があります。
+descriptor ベースのプラグイン head/body 注入 API を使って、公開ページに GTM 標準の 2 つのスニペットを挿入します。
+1. `<head>` 内に async ローダーのインライン `<script>`
+2. `<body>` 末尾に対応する `<noscript>` iframe（JavaScript 無効の訪問者でも GTM 経由でページビューを登録できる）
+コンテナ ID はデプロイ後 **`/admin/plugins` から編集可能** で、`cms.config.ts` の constructor 引数は初期デフォルトのシードに過ぎません。AWS のデータ権限は不要で、`trust_level` は `untrusted`、公開 Next.js プロセス内で描画時に動きます。
+## インストール
+```bash
+npm install @ampless/plugin-gtm@alpha
+```
+## 設定
+`cms.config.ts` に記述します:
+```ts
+import { defineConfig } from 'ampless'
+import gtmPlugin from '@ampless/plugin-gtm'
+export default defineConfig({
+  // ...
+  plugins: [
+    gtmPlugin({
+      // 初期コンテナ ID。デプロイ後は /admin/plugins から編集可能。
+      // 空にしておけば無効化したまま ship できる。
+      containerId: '',
+    }),
+  ],
+})
+```
+| オプション | デフォルト | 備考 |
+|---|---|---|
+| `containerId` | `''` | 初期 GTM コンテナ ID。例: `GTM-XXXXXXX`。マニフェストの default を seed するだけで、ライブ値はリクエスト時に `/admin/plugins` から読み出される。空文字でプラグインを無効化したまま ship できる。 |
+| `instanceId` | `'gtm'` | script / noscript 要素 id と設定保存キーの namespace。同サイトに複数の GTM コンテナを入れる場合に分ける。 |
+## 管理画面からコンテナ ID を編集する
+デプロイ後、コンテナ ID は `/admin/plugins` → **Google Tag Manager** で編集できます。空文字保存で `cms.config.ts` から削除せずに無効化、`GTM-XXXXXXX` を保存すれば有効化されます。変更内容は site-settings の S3 ミラーが反映された後（数秒）に公開サイトに反映されます。admin form は cache invalidation を少し遅延発火するので、processor の rebuild 完了前に公開側が古い snapshot を fetch する race を避けています。
+## コンテナ ID の取得
+1. [Google Tag Manager](https://tagmanager.google.com/) にサインインし、対象サイトのワークスペースを選択。
+2. 画面右上にコンテナ ID（`GTM-XXXXXXX` の形式）が表示されます。
+3. それを上の `containerId` に設定するか、管理画面のフォームに貼り付けます。
+`GTM-XXXXXXX` はコンテナ識別子であって書き込み認証には使われないため、ソースコードにコミットして問題ありません。
+### ID パターンについて
+admin form はコンテナ ID を `^$|^GTM-[A-Z0-9]+$` でバリデートします（空、または「`GTM-` で始まりその後英数字」の実用形）。Google の [公式インストールドキュメント](https://support.google.com/tagmanager/answer/14847097) は厳密フォーマットを明文化していないため、これは意図的に緩い sanity check です。Google が今後より広い文字集合を使い始めたら issue を立ててください、パターンを広げます。
+## 複数インスタンス
+各 `gtmPlugin(...)` 呼び出しは描画 DOM と admin 設定保存の両方で独立した `instanceId` namespace を持ちます:
+```ts
+plugins: [
+  gtmPlugin({ instanceId: 'marketing', containerId: 'GTM-AAA' }),
+  gtmPlugin({ instanceId: 'product',   containerId: 'GTM-BBB' }),
+]
+```
+admin form では各 instance が個別パネルとして表示されます。
+## トラストレベル
+`untrusted`。プラグインは `@ampless/runtime` が検証・描画する head / body descriptor を返すだけです。DynamoDB、S3、Lambda プロセッサーには一切触れません。
+## まだやらないこと
+- **CSP nonce 連携** — インラインローダー script は `nonce` 無しで emit されます。ampless サイトに CSP enforcement を入れる段で別 RFP として middleware → SSR → descriptor の通り道を設計します
+- **GTM コンテナのインポート** — このプラグインはローダーを注入するだけです。tags / triggers / variables は通常のサイトと同じく GTM の Web UI 内で設定してください

package/README.md ADDED Viewed

@@ -0,0 +1,84 @@
+> 日本語版: [README.ja.md](./README.ja.md)
+>
+# @ampless/plugin-gtm
+Google Tag Manager plugin for [ampless](https://github.com/heavymoons/ampless).
+> **Pre-release / alpha.** Breaking changes possible in any minor version until v1.0.
+Drops Google Tag Manager's standard two-part snippet onto every public page through the descriptor-based plugin head/body injection API:
+1. The async loader inline `<script>` in `<head>`.
+2. The matching `<noscript>` iframe at the end of `<body>`, so visitors with JavaScript disabled still register a pageview through GTM.
+The container ID is **editable from `/admin/plugins`** after deploy — the constructor argument in `cms.config.ts` just seeds the initial default. No AWS data permissions are required; the plugin's `trust_level` is `untrusted` and everything runs at request time inside the public Next.js process.
+## Install
+```bash
+npm install @ampless/plugin-gtm@alpha
+```
+## Configure
+In `cms.config.ts`:
+```ts
+import { defineConfig } from 'ampless'
+import gtmPlugin from '@ampless/plugin-gtm'
+export default defineConfig({
+  // ...
+  plugins: [
+    gtmPlugin({
+      // Initial container ID. Editable from /admin/plugins after deploy.
+      // Leave empty to ship the plugin disabled and turn it on later.
+      containerId: '',
+    }),
+  ],
+})
+```
+| Option | Default | Notes |
+|---|---|---|
+| `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. |
+## Editing the container ID from the admin UI
+After a deploy, the container ID lives at `/admin/plugins` → **Google Tag Manager**. Saving an empty value disables the plugin without removing it from `cms.config.ts`; saving `GTM-XXXXXXX` enables it. Changes are reflected on the public site after the site-settings S3 mirror finishes (a few seconds; the admin form delays the cache invalidation slightly so the rebuild has time to complete).
+## Getting your container ID
+1. Sign in to [Google Tag Manager](https://tagmanager.google.com/) and pick the workspace for the site.
+2. The container ID (`GTM-XXXXXXX`) is shown in the top-right of the workspace UI.
+3. Copy it into the `containerId` option above, or paste it into the admin form.
+`GTM-XXXXXXX` is safe to commit to source control — it identifies the container but does not authenticate writes.
+### A note on the ID pattern
+The admin form validates the container ID against `^$|^GTM-[A-Z0-9]+$` — empty or the practical "starts with `GTM-`, then alphanumeric" shape. Google's [official install docs](https://support.google.com/tagmanager/answer/14847097) don't publish a strict format, so this is intentionally a loose sanity-check rather than a tight schema. If Google starts issuing a wider character set, file an issue and we'll widen the pattern.
+## Multiple instances
+Each `gtmPlugin(...)` call gets its own `instanceId` namespace, both in the rendered DOM and in the admin settings storage:
+```ts
+plugins: [
+  gtmPlugin({ instanceId: 'marketing', containerId: 'GTM-AAA' }),
+  gtmPlugin({ instanceId: 'product',   containerId: 'GTM-BBB' }),
+]
+```
+The admin form lists each instance as its own panel.
+## Trust level
+`untrusted`. The plugin only contributes head and body descriptors that are validated and rendered by `@ampless/runtime`. It does not touch DynamoDB, S3, or any Lambda processor.
+## What it does not do
+- **CSP nonce propagation** — the inline loader script is emitted without a `nonce`. ampless sites don't enforce a CSP today; once that lands, a dedicated RFP will wire `nonce` end-to-end (middleware → SSR → descriptor).
+- **GTM container imports** — this plugin only injects the loader. Tags / triggers / variables are configured inside the GTM web UI like any other site.

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,39 @@
+import { AmplessPlugin } from 'ampless';
+interface GtmOptions {
+    /**
+     * Optional fallback Google Tag Manager container ID, e.g.
+     * `"GTM-XXXXXXX"`. Used only when no admin-stored value exists in
+     * `pk='siteconfig', sk='plugins.<instanceId>.containerId'`. An
+     * empty string disables the plugin (both `publicHead` and
+     * `publicBodyEnd` return `[]`), which is the recommended way to
+     * keep the dependency wired up while toggling GTM off — for
+     * example in staging or before consent is granted.
+     *
+     * New deployments should leave it empty and configure the value
+     * from `/admin/plugins`.
+     */
+    containerId?: string;
+    /**
+     * Optional namespace for this instance. Defaults to `'gtm'`. Set
+     * distinct values when registering the plugin twice (e.g. a
+     * marketing + a product container on the same site).
+     */
+    instanceId?: string;
+}
+/**
+ * Factory for the GTM plugin. Returns a plugin manifest that emits
+ * the GTM loader inline script in `<head>` and the matching
+ * `<noscript>` iframe at the end of `<body>`. The plugin is
+ * `untrusted` — it does not need any AWS data permissions because
+ * everything happens inside the public Next.js process at render
+ * time.
+ *
+ * The container ID is read at request time through
+ * `ctx.setting<string>('containerId')`, with the constructor
+ * argument seeding the manifest `default` for first-time installs
+ * before an admin has saved a value.
+ */
+declare function gtmPlugin(options?: GtmOptions): AmplessPlugin;
+export { type GtmOptions, gtmPlugin as default };

package/dist/index.js ADDED Viewed

@@ -0,0 +1,70 @@
+// src/index.ts
+import { definePlugin } from "ampless";
+function gtmPlugin(options = {}) {
+  const { containerId = "", instanceId = "gtm" } = options;
+  return definePlugin({
+    name: "gtm",
+    instanceId,
+    displayName: { en: "Google Tag Manager", ja: "Google Tag Manager" },
+    apiVersion: 1,
+    trust_level: "untrusted",
+    capabilities: ["publicHead", "publicBody", "adminSettings"],
+    settings: {
+      public: [
+        {
+          type: "text",
+          key: "containerId",
+          label: {
+            en: "Container ID",
+            ja: "\u30B3\u30F3\u30C6\u30CA ID"
+          },
+          description: {
+            en: "GTM container ID (e.g. GTM-XXXXXXX). Leave blank to disable the plugin without removing it from cms.config.",
+            ja: "GTM \u306E\u30B3\u30F3\u30C6\u30CA ID (\u4F8B: GTM-XXXXXXX)\u3002\u7A7A\u306B\u3059\u308B\u3068 cms.config \u304B\u3089\u524A\u9664\u305B\u305A\u306B\u30D7\u30E9\u30B0\u30A4\u30F3\u3092\u7121\u52B9\u5316\u3067\u304D\u307E\u3059\u3002"
+          },
+          // Accept either empty (disable) or a well-formed GTM
+          // container id. Google's install docs don't publish a
+          // strict format, so we keep this loose — empty + the
+          // common `GTM-XXXX...` shape is the practical check.
+          pattern: "^$|^GTM-[A-Z0-9]+$",
+          placeholder: "GTM-XXXXXXX",
+          default: containerId
+        }
+      ]
+    },
+    publicHead(ctx) {
+      const id = (ctx.setting("containerId") ?? "").trim();
+      if (!id) return [];
+      return [
+        {
+          type: "inlineScript",
+          id: `gtm-loader-${instanceId}`,
+          strategy: "afterInteractive",
+          // GTM's official "Add this code to the <head>" snippet,
+          // minified. JSON.stringify the container ID so any
+          // accidental quote/control char would stay quoted instead
+          // of breaking out of the literal.
+          body: `(function(w,d,s,l,i){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),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);})(window,document,'script','dataLayer',${JSON.stringify(id)});`
+        }
+      ];
+    },
+    publicBodyEnd(ctx) {
+      const id = (ctx.setting("containerId") ?? "").trim();
+      if (!id) return [];
+      return [
+        {
+          type: "noscript",
+          id: `gtm-noscript-${instanceId}`,
+          // The matching `<noscript>` iframe fallback. The runtime
+          // pipes `html` through `dangerouslySetInnerHTML`, which is
+          // safe here because we built the value from a
+          // validator-checked container ID + a fixed template.
+          html: `<iframe src="https://www.googletagmanager.com/ns.html?id=${encodeURIComponent(id)}" height="0" width="0" style="display:none;visibility:hidden"></iframe>`
+        }
+      ];
+    }
+  });
+}
+export {
+  gtmPlugin as default
+};

package/package.json ADDED Viewed

@@ -0,0 +1,43 @@
+{
+  "name": "@ampless/plugin-gtm",
+  "version": "0.1.1-alpha.0",
+  "description": "Google Tag Manager plugin for ampless",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heavymoons/ampless.git",
+    "directory": "packages/plugin-gtm"
+  },
+  "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.18"
+  },
+  "keywords": [
+    "ampless",
+    "plugin",
+    "gtm",
+    "google-tag-manager",
+    "analytics"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}