@riebeckite/plugin-analytics 0.0.31 → 0.0.33

package/README.md

@@ -60,8 +60,8 @@ In a browser, the initializer sends exactly one event per document:
 
 `path` and `lang` are contextual metadata, not identity. Content without a
 stable ID is not tracked. The initializer is a no-op during builds/SSR and is
-idempotent in a document. Riebeckite's current static document navigation needs
-no SPA route hooks; SPA navigation is not tracked automatically.
+idempotent in a document. With SPA navigation enabled, the plugin sends another
+event after each successful route transition.
 
 Content IDs are an authoring responsibility. Duplicate `id` declarations across
 published notes are reported by
@@ -92,7 +92,7 @@ diagnostics.
 
 ## Exports
 
-- `analytics()` / `analyticsPlugin()`
+- `analytics()` / `analytics()`
 - `initAnalytics` (`@riebeckite/plugin-analytics/client`)
 - `MemoryAnalyticsProvider`
 - Event, query/result, provider/capability, and public-config types

package/README_ja.md

@@ -8,10 +8,10 @@ Riebeckite 向けの、ストレージや実行環境に依存しないアクセ
 
 ## 設計
 
-- `AnalyticsEvent` は型付きの `page_view` を持ち、プロバイダ固有イベントの union に拡張できます。
-- `AnalyticsProvider` は対応機能を明示し、`capture` と `query` を提供します。コンテンツ別 PV、人気コンテンツ、任意の ISO 8601 期間を扱えます。
-- 未対応クエリは `UnsupportedAnalyticsQueryError` で明示されます。テスト・ローカル用途には `MemoryAnalyticsProvider` を用意しています。
-- 認証情報・ストレージ・ランタイムバインディングはプロバイダ内部の非公開設定です。ブラウザへ渡すのは `AnalyticsPublicConfig` だけです。
+- `AnalyticsEvent` は型付きの `page_view` を持ち、プロバイダ固有のイベント型を加えた union 型へ拡張できます。
+- `AnalyticsProvider` は対応する機能（capability）を明示し、`capture` と `query` を提供します。クエリはコンテンツ別のページビューと人気コンテンツを対象にし、ISO 8601 形式の期間を任意で指定できます。
+- 未対応のクエリは `UnsupportedAnalyticsQueryError` で明示されます。テストやローカル用途には `MemoryAnalyticsProvider` を用意しています。
+- 認証情報・ストレージ・ランタイムバインディングなどのプロバイダ設定は、プロバイダの内部に留まります。ブラウザへ渡すのは `AnalyticsPublicConfig` だけです。
 
 ## 使い方
 
@@ -28,11 +28,11 @@ export default {
 };
 ```
 
-`collectorUrl` は公開してよい収集先 URL です。相対パスまたは HTTP(S) URL を指定し、JSON の `POST` を受け付ける収集側を用意します。将来のプロバイダパッケージは、非公開ランタイム設定を使ってその収集側を提供できます。
+`collectorUrl` は公開してよい収集先 URL です。相対パスまたは HTTP(S) URL を指定し、JSON の `POST` を受け付けるコレクターを用意します。将来のプロバイダパッケージは、非公開のランタイム設定を使ってこのコレクターを提供できます。
 
-## ブラウザでの動作
+## ブラウザでの計測
 
-Core の安定コンテンツ ID（frontmatter の `id`）がある公開コンテンツにだけ識別子マーカーを出力します。汎用 `publicConfig` 経由で登録された `initAnalytics` は、ブラウザでドキュメントごとに一度だけ次のようなイベントを送ります。
+Core の安定コンテンツ ID（frontmatter の `id`）を持つ公開コンテンツにだけ、コンテンツ ID を示すマーカーを出力します。汎用の `publicConfig` 経由で登録された `initAnalytics` は、ブラウザでドキュメントごとに一度だけ次のようなイベントを送ります。
 
 ```json
 {
@@ -44,9 +44,9 @@ Core の安定コンテンツ ID（frontmatter の `id`）がある公開コン
 }
 ```
 
-`path` と `lang` は補助情報であり、ID ではありません。安定 ID のないコンテンツは誤って計測しません。ビルド時・SSR 時は何もせず、同じドキュメント内での初期化も冪等です。現行リポジトリは静的なドキュメント遷移のため SPA フックは追加しておらず、SPA 遷移は自動計測しません。
+`path` と `lang` は補助的なメタデータであり、ID ではありません。安定 ID を持たないコンテンツは計測しません。ビルド時と SSR 時は何もせず、同じドキュメント内での初期化も冪等です。SPA ナビゲーションを有効にすると、ルート遷移が成功するたびに追加のイベントを送信します。
 
-コンテンツ ID は執筆側の責務です。公開ノート間での `id` の重複は [`@riebeckite/plugin-diagnostics`](../diagnostics/README_ja.md) が報告し（`duplicate-content-id` / `invalid-content-id`）、プラグイン自身の `validateAnalyticsOptions` が `check` 時に検証します。
+コンテンツ ID は執筆側の責務です。公開ノート間で `id` が重複している場合は [`@riebeckite/plugin-diagnostics`](../diagnostics/README_ja.md) が報告し（`duplicate-content-id` / `invalid-content-id`）、プラグイン自身の `validateAnalyticsOptions` が `check` 時に検証します。
 
 ## プロバイダの取り決め
 
@@ -62,11 +62,11 @@ const result = await provider.query({
 
 ## 診断
 
-`@riebeckite/plugin-diagnostics` は、サイトで本プラグインが有効なとき、安定 content ID を持たない公開コンテンツを `analytics-untracked` として報告します。計測の抜けを `check` / `doctor` / build の診断で確認できます。
+`@riebeckite/plugin-diagnostics` は、サイトで本プラグインが有効なとき、安定コンテンツ ID を持たない公開コンテンツを `analytics-untracked` として報告します。計測の抜けは `check` / `doctor` / ビルドの診断で確認できます。
 
 ## 主なエクスポート
 
-- `analytics()` / `analyticsPlugin()`
+- `analytics()` / `analytics()`
 - `initAnalytics`（`@riebeckite/plugin-analytics/client`）
 - `MemoryAnalyticsProvider`
 - イベント、クエリ／結果、プロバイダ／機能、公開設定の型

package/dist/client.js

@@ -1,20 +1,28 @@
 // src/init.ts
 var ANALYTICS_CONTENT_ID_ATTRIBUTE = "data-riebeckite-content-id";
 var INITIALIZED_ATTRIBUTE = "data-riebeckite-analytics-initialized";
-function initAnalytics(config) {
+function initAnalytics({
+  config
+}) {
   if (typeof window === "undefined" || typeof document === "undefined") return;
   if (document.documentElement.hasAttribute(INITIALIZED_ATTRIBUTE)) return;
   document.documentElement.setAttribute(INITIALIZED_ATTRIBUTE, "");
-  const contentId = document.querySelector(`[${ANALYTICS_CONTENT_ID_ATTRIBUTE}]`)?.getAttribute(ANALYTICS_CONTENT_ID_ATTRIBUTE);
-  if (!contentId) return;
-  const event = {
-    type: "page_view",
-    contentId,
-    occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
-    path: window.location.pathname,
-    ...document.documentElement.lang ? { lang: document.documentElement.lang } : {}
+  const sendPageView = () => {
+    const contentId = document.querySelector(`[${ANALYTICS_CONTENT_ID_ATTRIBUTE}]`)?.getAttribute(ANALYTICS_CONTENT_ID_ATTRIBUTE);
+    if (!contentId) return;
+    const event = {
+      type: "page_view",
+      contentId,
+      occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+      path: window.location.pathname,
+      ...document.documentElement.lang ? { lang: document.documentElement.lang } : {}
+    };
+    void sendAnalyticsEvent(config.collectorUrl, event);
   };
-  void sendAnalyticsEvent(config.collectorUrl, event);
+  sendPageView();
+  if (typeof document.addEventListener !== "function") return;
+  document.addEventListener("riebeckite:navigation", sendPageView);
+  return () => document.removeEventListener("riebeckite:navigation", sendPageView);
 }
 async function sendAnalyticsEvent(collectorUrl, event) {
   await fetch(collectorUrl, {

package/dist/index.d.ts

@@ -16,4 +16,3 @@ export declare function analytics(options: AnalyticsOptions): import("@riebeckit
     provider: import("./index.js").AnalyticsProvider;
     publicConfig: import("./client.js").AnalyticsPublicConfig;
 }>>;
-export declare const analyticsPlugin: typeof analytics;

package/dist/index.js

@@ -8,20 +8,28 @@ import {
 // src/init.ts
 var ANALYTICS_CONTENT_ID_ATTRIBUTE = "data-riebeckite-content-id";
 var INITIALIZED_ATTRIBUTE = "data-riebeckite-analytics-initialized";
-function initAnalytics(config) {
+function initAnalytics({
+  config
+}) {
   if (typeof window === "undefined" || typeof document === "undefined") return;
   if (document.documentElement.hasAttribute(INITIALIZED_ATTRIBUTE)) return;
   document.documentElement.setAttribute(INITIALIZED_ATTRIBUTE, "");
-  const contentId = document.querySelector(`[${ANALYTICS_CONTENT_ID_ATTRIBUTE}]`)?.getAttribute(ANALYTICS_CONTENT_ID_ATTRIBUTE);
-  if (!contentId) return;
-  const event = {
-    type: "page_view",
-    contentId,
-    occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
-    path: window.location.pathname,
-    ...document.documentElement.lang ? { lang: document.documentElement.lang } : {}
+  const sendPageView = () => {
+    const contentId = document.querySelector(`[${ANALYTICS_CONTENT_ID_ATTRIBUTE}]`)?.getAttribute(ANALYTICS_CONTENT_ID_ATTRIBUTE);
+    if (!contentId) return;
+    const event = {
+      type: "page_view",
+      contentId,
+      occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+      path: window.location.pathname,
+      ...document.documentElement.lang ? { lang: document.documentElement.lang } : {}
+    };
+    void sendAnalyticsEvent(config.collectorUrl, event);
   };
-  void sendAnalyticsEvent(config.collectorUrl, event);
+  sendPageView();
+  if (typeof document.addEventListener !== "function") return;
+  document.addEventListener("riebeckite:navigation", sendPageView);
+  return () => document.removeEventListener("riebeckite:navigation", sendPageView);
 }
 async function sendAnalyticsEvent(collectorUrl, event) {
   await fetch(collectorUrl, {
@@ -146,7 +154,9 @@ function analytics(options) {
         "analytics",
         "@riebeckite/plugin-analytics/client",
         "initAnalytics",
-        options.publicConfig
+        options.publicConfig,
+        "app",
+        "context"
       )
     ],
     onManifestCreated: ({ manifest }) => {
@@ -156,7 +166,6 @@ function analytics(options) {
     }
   });
 }
-var analyticsPlugin = analytics;
 function appendContentIdentity(entry) {
   if (!entry.contentId) return;
   const marker = `<span hidden ${ANALYTICS_CONTENT_ID_ATTRIBUTE}="${escapeHtmlAttribute(entry.contentId)}"></span>`;
@@ -171,7 +180,6 @@ export {
   MemoryAnalyticsProvider,
   UnsupportedAnalyticsQueryError,
   analytics,
-  analyticsPlugin,
   assertAnalyticsQuerySupported,
   initAnalytics,
   requiredCapabilityForQuery,

package/dist/src/init.d.ts

@@ -4,4 +4,8 @@ export declare const ANALYTICS_CONTENT_ID_ATTRIBUTE = "data-riebeckite-content-i
  * Sends one document-level page view. Static Riebeckite sites reload documents
  * on navigation; SPA history hooks are intentionally not installed.
  */
-export declare function initAnalytics(config: AnalyticsPublicConfig): void;
+type ClientContext = {
+    config: AnalyticsPublicConfig;
+};
+export declare function initAnalytics({ config, }: ClientContext): (() => void) | undefined;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riebeckite/plugin-analytics",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,7 +20,7 @@
     }
   },
   "dependencies": {
-    "@riebeckite/core": "0.0.31"
+    "@riebeckite/core": "0.0.33"
   },
   "devDependencies": {
     "tsx": "^4.22.4"