@riebeckite/plugin-analytics 0.0.11 → 0.0.13
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.
- package/README.md +101 -101
- package/README_ja.md +63 -63
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,101 +1,101 @@
|
|
|
1
|
-
# @riebeckite/plugin-analytics
|
|
2
|
-
|
|
3
|
-
Storage-independent analytics primitives and browser page-view tracking for
|
|
4
|
-
Riebeckite. It contains no Cloudflare, Worker, database, or vendor code.
|
|
5
|
-
|
|
6
|
-
[日本語](./README_ja.md)
|
|
7
|
-
|
|
8
|
-
## Design
|
|
9
|
-
|
|
10
|
-
- `AnalyticsEvent` includes a typed `page_view` event and can be extended with
|
|
11
|
-
provider-specific event unions.
|
|
12
|
-
- `AnalyticsProvider` declares discoverable capabilities and exposes `capture`
|
|
13
|
-
and `query`. Queries cover per-content page views and popular content, with
|
|
14
|
-
optional ISO-8601 time ranges.
|
|
15
|
-
- `UnsupportedAnalyticsQueryError` makes unsupported query capabilities
|
|
16
|
-
explicit. `MemoryAnalyticsProvider` is included for tests and local examples.
|
|
17
|
-
- Provider runtime configuration (credentials, storage, bindings) stays inside
|
|
18
|
-
the provider. The browser receives only `AnalyticsPublicConfig`.
|
|
19
|
-
|
|
20
|
-
## Usage
|
|
21
|
-
|
|
22
|
-
```ts
|
|
23
|
-
import { analytics, MemoryAnalyticsProvider } from "@riebeckite/plugin-analytics";
|
|
24
|
-
|
|
25
|
-
const provider = new MemoryAnalyticsProvider();
|
|
26
|
-
|
|
27
|
-
export default {
|
|
28
|
-
plugins: [
|
|
29
|
-
analytics({
|
|
30
|
-
provider,
|
|
31
|
-
publicConfig: { collectorUrl: "/analytics/events" },
|
|
32
|
-
}),
|
|
33
|
-
],
|
|
34
|
-
};
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
`collectorUrl` is intentionally public. It is a relative path or an HTTP(S)
|
|
38
|
-
URL for a collector that accepts a JSON `POST` body. A future provider package
|
|
39
|
-
can expose a collector backed by its own private runtime configuration.
|
|
40
|
-
|
|
41
|
-
## Browser behavior
|
|
42
|
-
|
|
43
|
-
For every published content entry with Core's source-authored stable `id` (or
|
|
44
|
-
legacy `uid`), the plugin places a small content-ID marker in rendered HTML and
|
|
45
|
-
registers `initAnalytics` with the generic public-config client mechanism.
|
|
46
|
-
|
|
47
|
-
In a browser, the initializer sends exactly one event per document:
|
|
48
|
-
|
|
49
|
-
```json
|
|
50
|
-
{
|
|
51
|
-
"type": "page_view",
|
|
52
|
-
"contentId": "guide-1",
|
|
53
|
-
"occurredAt": "2026-01-01T00:00:00.000Z",
|
|
54
|
-
"path": "/guide",
|
|
55
|
-
"lang": "en"
|
|
56
|
-
}
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
`path` and `lang` are contextual metadata, not identity. Content without a
|
|
60
|
-
stable ID is not tracked. The initializer is a no-op during builds/SSR and is
|
|
61
|
-
idempotent in a document. Riebeckite's current static document navigation needs
|
|
62
|
-
no SPA route hooks; SPA navigation is not tracked automatically.
|
|
63
|
-
|
|
64
|
-
Content IDs are an authoring responsibility. Duplicate or conflicting `id`/`uid`
|
|
65
|
-
declarations across published notes are reported by
|
|
66
|
-
[`@riebeckite/plugin-diagnostics`](../diagnostics/README.md)
|
|
67
|
-
(`duplicate-content-id` / `invalid-content-id`) and validated by the plugin's own
|
|
68
|
-
`validateAnalyticsOptions` at `check` time.
|
|
69
|
-
|
|
70
|
-
## Provider contract
|
|
71
|
-
|
|
72
|
-
```ts
|
|
73
|
-
const result = await provider.query({
|
|
74
|
-
type: "popular_content",
|
|
75
|
-
limit: 10,
|
|
76
|
-
timeRange: { from: "2026-01-01T00:00:00.000Z" },
|
|
77
|
-
});
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
Capabilities are `capture`, `content_page_views`, and `popular_content`. Call
|
|
81
|
-
`assertAnalyticsQuerySupported(provider, query)` when implementing a provider
|
|
82
|
-
that may not support all queries.
|
|
83
|
-
|
|
84
|
-
## Diagnostics
|
|
85
|
-
|
|
86
|
-
`@riebeckite/plugin-diagnostics` reports an `analytics-untracked` finding for
|
|
87
|
-
published content without a stable content ID when the site enables this
|
|
88
|
-
plugin, so tracking gaps are visible in `check`, `doctor`, and build
|
|
89
|
-
diagnostics.
|
|
90
|
-
|
|
91
|
-
## Exports
|
|
92
|
-
|
|
93
|
-
- `analytics()` / `analyticsPlugin()`
|
|
94
|
-
- `initAnalytics` (`@riebeckite/plugin-analytics/client`)
|
|
95
|
-
- `MemoryAnalyticsProvider`
|
|
96
|
-
- Event, query/result, provider/capability, and public-config types
|
|
97
|
-
- `UnsupportedAnalyticsQueryError` and capability helpers
|
|
98
|
-
|
|
99
|
-
## See also
|
|
100
|
-
|
|
101
|
-
- [Plugin guide](../../../docs/en/plugin-
|
|
1
|
+
# @riebeckite/plugin-analytics
|
|
2
|
+
|
|
3
|
+
Storage-independent analytics primitives and browser page-view tracking for
|
|
4
|
+
Riebeckite. It contains no Cloudflare, Worker, database, or vendor code.
|
|
5
|
+
|
|
6
|
+
[日本語](./README_ja.md)
|
|
7
|
+
|
|
8
|
+
## Design
|
|
9
|
+
|
|
10
|
+
- `AnalyticsEvent` includes a typed `page_view` event and can be extended with
|
|
11
|
+
provider-specific event unions.
|
|
12
|
+
- `AnalyticsProvider` declares discoverable capabilities and exposes `capture`
|
|
13
|
+
and `query`. Queries cover per-content page views and popular content, with
|
|
14
|
+
optional ISO-8601 time ranges.
|
|
15
|
+
- `UnsupportedAnalyticsQueryError` makes unsupported query capabilities
|
|
16
|
+
explicit. `MemoryAnalyticsProvider` is included for tests and local examples.
|
|
17
|
+
- Provider runtime configuration (credentials, storage, bindings) stays inside
|
|
18
|
+
the provider. The browser receives only `AnalyticsPublicConfig`.
|
|
19
|
+
|
|
20
|
+
## Usage
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
import { analytics, MemoryAnalyticsProvider } from "@riebeckite/plugin-analytics";
|
|
24
|
+
|
|
25
|
+
const provider = new MemoryAnalyticsProvider();
|
|
26
|
+
|
|
27
|
+
export default {
|
|
28
|
+
plugins: [
|
|
29
|
+
analytics({
|
|
30
|
+
provider,
|
|
31
|
+
publicConfig: { collectorUrl: "/analytics/events" },
|
|
32
|
+
}),
|
|
33
|
+
],
|
|
34
|
+
};
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`collectorUrl` is intentionally public. It is a relative path or an HTTP(S)
|
|
38
|
+
URL for a collector that accepts a JSON `POST` body. A future provider package
|
|
39
|
+
can expose a collector backed by its own private runtime configuration.
|
|
40
|
+
|
|
41
|
+
## Browser behavior
|
|
42
|
+
|
|
43
|
+
For every published content entry with Core's source-authored stable `id` (or
|
|
44
|
+
legacy `uid`), the plugin places a small content-ID marker in rendered HTML and
|
|
45
|
+
registers `initAnalytics` with the generic public-config client mechanism.
|
|
46
|
+
|
|
47
|
+
In a browser, the initializer sends exactly one event per document:
|
|
48
|
+
|
|
49
|
+
```json
|
|
50
|
+
{
|
|
51
|
+
"type": "page_view",
|
|
52
|
+
"contentId": "guide-1",
|
|
53
|
+
"occurredAt": "2026-01-01T00:00:00.000Z",
|
|
54
|
+
"path": "/guide",
|
|
55
|
+
"lang": "en"
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`path` and `lang` are contextual metadata, not identity. Content without a
|
|
60
|
+
stable ID is not tracked. The initializer is a no-op during builds/SSR and is
|
|
61
|
+
idempotent in a document. Riebeckite's current static document navigation needs
|
|
62
|
+
no SPA route hooks; SPA navigation is not tracked automatically.
|
|
63
|
+
|
|
64
|
+
Content IDs are an authoring responsibility. Duplicate or conflicting `id`/`uid`
|
|
65
|
+
declarations across published notes are reported by
|
|
66
|
+
[`@riebeckite/plugin-diagnostics`](../diagnostics/README.md)
|
|
67
|
+
(`duplicate-content-id` / `invalid-content-id`) and validated by the plugin's own
|
|
68
|
+
`validateAnalyticsOptions` at `check` time.
|
|
69
|
+
|
|
70
|
+
## Provider contract
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
const result = await provider.query({
|
|
74
|
+
type: "popular_content",
|
|
75
|
+
limit: 10,
|
|
76
|
+
timeRange: { from: "2026-01-01T00:00:00.000Z" },
|
|
77
|
+
});
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Capabilities are `capture`, `content_page_views`, and `popular_content`. Call
|
|
81
|
+
`assertAnalyticsQuerySupported(provider, query)` when implementing a provider
|
|
82
|
+
that may not support all queries.
|
|
83
|
+
|
|
84
|
+
## Diagnostics
|
|
85
|
+
|
|
86
|
+
`@riebeckite/plugin-diagnostics` reports an `analytics-untracked` finding for
|
|
87
|
+
published content without a stable content ID when the site enables this
|
|
88
|
+
plugin, so tracking gaps are visible in `check`, `doctor`, and build
|
|
89
|
+
diagnostics.
|
|
90
|
+
|
|
91
|
+
## Exports
|
|
92
|
+
|
|
93
|
+
- `analytics()` / `analyticsPlugin()`
|
|
94
|
+
- `initAnalytics` (`@riebeckite/plugin-analytics/client`)
|
|
95
|
+
- `MemoryAnalyticsProvider`
|
|
96
|
+
- Event, query/result, provider/capability, and public-config types
|
|
97
|
+
- `UnsupportedAnalyticsQueryError` and capability helpers
|
|
98
|
+
|
|
99
|
+
## See also
|
|
100
|
+
|
|
101
|
+
- [Plugin guide](../../../docs/en/reference/plugin-api.md)
|
package/README_ja.md
CHANGED
|
@@ -1,63 +1,63 @@
|
|
|
1
|
-
# @riebeckite/plugin-analytics
|
|
2
|
-
|
|
3
|
-
Riebeckite 向けの、ストレージや実行環境に依存しないアクセス解析の基盤です。Cloudflare、Worker、データベース、特定ベンダーの実装は含みません。
|
|
4
|
-
|
|
5
|
-
[English](./README.md)
|
|
6
|
-
|
|
7
|
-
## 設計
|
|
8
|
-
|
|
9
|
-
- `AnalyticsEvent` は型付きの `page_view` を持ち、プロバイダ固有イベントの union に拡張できます。
|
|
10
|
-
- `AnalyticsProvider` は対応機能を明示し、`capture` と `query` を提供します。コンテンツ別 PV、人気コンテンツ、任意の ISO 8601 期間を扱えます。
|
|
11
|
-
- 未対応クエリは `UnsupportedAnalyticsQueryError` で明示されます。テスト・ローカル用途には `MemoryAnalyticsProvider` を用意しています。
|
|
12
|
-
- 認証情報・ストレージ・ランタイムバインディングはプロバイダ内部の非公開設定です。ブラウザへ渡すのは `AnalyticsPublicConfig` だけです。
|
|
13
|
-
|
|
14
|
-
## 使い方
|
|
15
|
-
|
|
16
|
-
```ts
|
|
17
|
-
import { analytics, MemoryAnalyticsProvider } from "@riebeckite/plugin-analytics";
|
|
18
|
-
|
|
19
|
-
export default {
|
|
20
|
-
plugins: [
|
|
21
|
-
analytics({
|
|
22
|
-
provider: new MemoryAnalyticsProvider(),
|
|
23
|
-
publicConfig: { collectorUrl: "/analytics/events" },
|
|
24
|
-
}),
|
|
25
|
-
],
|
|
26
|
-
};
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
`collectorUrl` は公開してよい収集先 URL です。相対パスまたは HTTP(S) URL を指定し、JSON の `POST` を受け付ける収集側を用意します。将来のプロバイダパッケージは、非公開ランタイム設定を使ってその収集側を提供できます。
|
|
30
|
-
|
|
31
|
-
## ブラウザでの動作
|
|
32
|
-
|
|
33
|
-
Core の安定コンテンツ ID（フロントマターの `id`、互換用の `uid`）がある公開コンテンツにだけ識別子マーカーを出力します。汎用 `publicConfig` 経由で登録された `initAnalytics` は、ブラウザでドキュメントごとに一度だけ次のようなイベントを送ります。
|
|
34
|
-
|
|
35
|
-
```json
|
|
36
|
-
{
|
|
37
|
-
"type": "page_view",
|
|
38
|
-
"contentId": "guide-1",
|
|
39
|
-
"occurredAt": "2026-01-01T00:00:00.000Z",
|
|
40
|
-
"path": "/guide",
|
|
41
|
-
"lang": "ja"
|
|
42
|
-
}
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
`path` と `lang` は補助情報であり、ID ではありません。安定 ID のないコンテンツは誤って計測しません。ビルド時・SSR 時は何もせず、同じドキュメント内での初期化も冪等です。現行リポジトリは静的なドキュメント遷移のため SPA フックは追加しておらず、SPA 遷移は自動計測しません。
|
|
46
|
-
|
|
47
|
-
コンテンツ ID は執筆側の責務です。公開ノート間での `id`/`uid` の重複・抵触は [`@riebeckite/plugin-diagnostics`](../diagnostics/README_ja.md) が報告し（`duplicate-content-id` / `invalid-content-id`）、プラグイン自身の `validateAnalyticsOptions` が `check` 時に検証します。
|
|
48
|
-
|
|
49
|
-
## 診断
|
|
50
|
-
|
|
51
|
-
`@riebeckite/plugin-diagnostics` は、サイトで本プラグインが有効なとき、安定 content ID を持たない公開コンテンツを `analytics-untracked` として報告します。計測の抜けを `check` / `doctor` / build の診断で確認できます。
|
|
52
|
-
|
|
53
|
-
## 主なエクスポート
|
|
54
|
-
|
|
55
|
-
- `analytics()` / `analyticsPlugin()`
|
|
56
|
-
- `initAnalytics`（`@riebeckite/plugin-analytics/client`）
|
|
57
|
-
- `MemoryAnalyticsProvider`
|
|
58
|
-
- イベント、クエリ／結果、プロバイダ／機能、公開設定の型
|
|
59
|
-
- `UnsupportedAnalyticsQueryError` と機能確認ヘルパー
|
|
60
|
-
|
|
61
|
-
## ????
|
|
62
|
-
|
|
63
|
-
- [?????????](../../../docs/ja/plugin-
|
|
1
|
+
# @riebeckite/plugin-analytics
|
|
2
|
+
|
|
3
|
+
Riebeckite 向けの、ストレージや実行環境に依存しないアクセス解析の基盤です。Cloudflare、Worker、データベース、特定ベンダーの実装は含みません。
|
|
4
|
+
|
|
5
|
+
[English](./README.md)
|
|
6
|
+
|
|
7
|
+
## 設計
|
|
8
|
+
|
|
9
|
+
- `AnalyticsEvent` は型付きの `page_view` を持ち、プロバイダ固有イベントの union に拡張できます。
|
|
10
|
+
- `AnalyticsProvider` は対応機能を明示し、`capture` と `query` を提供します。コンテンツ別 PV、人気コンテンツ、任意の ISO 8601 期間を扱えます。
|
|
11
|
+
- 未対応クエリは `UnsupportedAnalyticsQueryError` で明示されます。テスト・ローカル用途には `MemoryAnalyticsProvider` を用意しています。
|
|
12
|
+
- 認証情報・ストレージ・ランタイムバインディングはプロバイダ内部の非公開設定です。ブラウザへ渡すのは `AnalyticsPublicConfig` だけです。
|
|
13
|
+
|
|
14
|
+
## 使い方
|
|
15
|
+
|
|
16
|
+
```ts
|
|
17
|
+
import { analytics, MemoryAnalyticsProvider } from "@riebeckite/plugin-analytics";
|
|
18
|
+
|
|
19
|
+
export default {
|
|
20
|
+
plugins: [
|
|
21
|
+
analytics({
|
|
22
|
+
provider: new MemoryAnalyticsProvider(),
|
|
23
|
+
publicConfig: { collectorUrl: "/analytics/events" },
|
|
24
|
+
}),
|
|
25
|
+
],
|
|
26
|
+
};
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
`collectorUrl` は公開してよい収集先 URL です。相対パスまたは HTTP(S) URL を指定し、JSON の `POST` を受け付ける収集側を用意します。将来のプロバイダパッケージは、非公開ランタイム設定を使ってその収集側を提供できます。
|
|
30
|
+
|
|
31
|
+
## ブラウザでの動作
|
|
32
|
+
|
|
33
|
+
Core の安定コンテンツ ID（フロントマターの `id`、互換用の `uid`）がある公開コンテンツにだけ識別子マーカーを出力します。汎用 `publicConfig` 経由で登録された `initAnalytics` は、ブラウザでドキュメントごとに一度だけ次のようなイベントを送ります。
|
|
34
|
+
|
|
35
|
+
```json
|
|
36
|
+
{
|
|
37
|
+
"type": "page_view",
|
|
38
|
+
"contentId": "guide-1",
|
|
39
|
+
"occurredAt": "2026-01-01T00:00:00.000Z",
|
|
40
|
+
"path": "/guide",
|
|
41
|
+
"lang": "ja"
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
`path` と `lang` は補助情報であり、ID ではありません。安定 ID のないコンテンツは誤って計測しません。ビルド時・SSR 時は何もせず、同じドキュメント内での初期化も冪等です。現行リポジトリは静的なドキュメント遷移のため SPA フックは追加しておらず、SPA 遷移は自動計測しません。
|
|
46
|
+
|
|
47
|
+
コンテンツ ID は執筆側の責務です。公開ノート間での `id`/`uid` の重複・抵触は [`@riebeckite/plugin-diagnostics`](../diagnostics/README_ja.md) が報告し（`duplicate-content-id` / `invalid-content-id`）、プラグイン自身の `validateAnalyticsOptions` が `check` 時に検証します。
|
|
48
|
+
|
|
49
|
+
## 診断
|
|
50
|
+
|
|
51
|
+
`@riebeckite/plugin-diagnostics` は、サイトで本プラグインが有効なとき、安定 content ID を持たない公開コンテンツを `analytics-untracked` として報告します。計測の抜けを `check` / `doctor` / build の診断で確認できます。
|
|
52
|
+
|
|
53
|
+
## 主なエクスポート
|
|
54
|
+
|
|
55
|
+
- `analytics()` / `analyticsPlugin()`
|
|
56
|
+
- `initAnalytics`（`@riebeckite/plugin-analytics/client`）
|
|
57
|
+
- `MemoryAnalyticsProvider`
|
|
58
|
+
- イベント、クエリ／結果、プロバイダ／機能、公開設定の型
|
|
59
|
+
- `UnsupportedAnalyticsQueryError` と機能確認ヘルパー
|
|
60
|
+
|
|
61
|
+
## ????
|
|
62
|
+
|
|
63
|
+
- [?????????](../../../docs/ja/reference/plugin-api.md)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@riebeckite/plugin-analytics",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.13",
|
|
4
4
|
"license": "Apache-2.0",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
}
|
|
21
21
|
},
|
|
22
22
|
"dependencies": {
|
|
23
|
-
"@riebeckite/core": "0.0.
|
|
23
|
+
"@riebeckite/core": "0.0.13"
|
|
24
24
|
},
|
|
25
25
|
"devDependencies": {
|
|
26
26
|
"tsx": "^4.22.4"
|