@plasius/analytics 1.3.2 → 1.4.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.
- package/README.md +86 -1
- package/dist/index.cjs +541 -103
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +109 -4
- package/dist/index.d.ts +109 -4
- package/dist/index.js +530 -100
- package/dist/index.js.map +1 -1
- package/dist/{metrics-B7L9phdM.d.cts → metrics-DhAg1PSO.d.cts} +1 -1
- package/dist/{metrics-B7L9phdM.d.ts → metrics-DhAg1PSO.d.ts} +1 -1
- package/dist/metrics.d.cts +1 -1
- package/dist/metrics.d.ts +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
# @plasius/analytics
|
|
2
2
|
|
|
3
|
+
For optional analytics, construct clients only after the host has obtained consent.
|
|
4
|
+
On withdrawal call `client.destroy({ discard: true })` to cancel pending transport
|
|
5
|
+
and remove its retained events and issue aggregates. Custom transports must honour
|
|
6
|
+
the provided `request.signal`. A late transport completion cannot recreate the
|
|
7
|
+
discarded queue; requests already received by a server cannot be recalled.
|
|
8
|
+
The semantic journey client's existing `destroy()` already aborts and discards.
|
|
9
|
+
|
|
3
10
|
[](https://www.npmjs.com/package/@plasius/analytics)
|
|
4
11
|
[](https://github.com/Plasius-LTD/analytics/actions/workflows/ci.yml)
|
|
5
12
|
[](https://codecov.io/gh/Plasius-LTD/analytics)
|
|
@@ -30,7 +37,12 @@ Local-space analytics primitives for browser apps and reusable React components.
|
|
|
30
37
|
npm install @plasius/analytics
|
|
31
38
|
```
|
|
32
39
|
|
|
33
|
-
## Core API
|
|
40
|
+
## Legacy Core API
|
|
41
|
+
|
|
42
|
+
The API below is a compatibility surface, not the privacy-safe event NFR path.
|
|
43
|
+
New integrations should use the opt-in semantic client and approved aggregate
|
|
44
|
+
contract below. The Plasius site is retiring unrestricted legacy ingestion;
|
|
45
|
+
do not forward these legacy records to the semantic endpoint.
|
|
34
46
|
|
|
35
47
|
```ts
|
|
36
48
|
import {
|
|
@@ -76,6 +88,79 @@ await backendAnalytics.flush();
|
|
|
76
88
|
|
|
77
89
|
Semantic journeys are an additive v2 API. The individual story remains in bounded, memory-only client state; `flush()` sends only coarse event-name/outcome counters. Aggregate payloads contain no journey, trace, event, producer, session, device, IP-derived, or user identifier.
|
|
78
90
|
|
|
91
|
+
### Reviewed aggregate views (2.1)
|
|
92
|
+
|
|
93
|
+
For screen/action or world/metric breakdowns, explicitly opt in to catalogue-owned
|
|
94
|
+
projections. An ordinary event attribute is **not** automatically uploaded:
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
import {
|
|
98
|
+
defineSemanticJourneyCatalog,
|
|
99
|
+
defineSemanticJourneyAggregatePolicy,
|
|
100
|
+
createSemanticJourneyAggregateValidator,
|
|
101
|
+
createSemanticJourneyClient,
|
|
102
|
+
} from "@plasius/analytics";
|
|
103
|
+
|
|
104
|
+
const catalogue = defineSemanticJourneyCatalog({
|
|
105
|
+
"ui.control.activate": {
|
|
106
|
+
category: "interaction",
|
|
107
|
+
attributes: {
|
|
108
|
+
screen: { type: "enum", values: ["home", "generator"] },
|
|
109
|
+
action: { type: "enum", values: ["select", "retry"] },
|
|
110
|
+
},
|
|
111
|
+
},
|
|
112
|
+
}, { sources: ["plasius.site"] });
|
|
113
|
+
const aggregatePolicy = defineSemanticJourneyAggregatePolicy(catalogue, {
|
|
114
|
+
bindings: [{ source: "plasius.site", channel: "frontend", runtime: "browser" }],
|
|
115
|
+
projections: {
|
|
116
|
+
"ui.control.activate": { "screen-action": ["screen", "action"] },
|
|
117
|
+
},
|
|
118
|
+
});
|
|
119
|
+
declare const analyticsConsentAndRemotePermission: boolean;
|
|
120
|
+
const client = createSemanticJourneyClient({
|
|
121
|
+
catalogue, aggregatePolicy, source: "plasius.site", channel: "frontend", runtime: "browser",
|
|
122
|
+
enabled: analyticsConsentAndRemotePermission,
|
|
123
|
+
aggregateEndpoint: "/api/analytics/semantic-aggregates",
|
|
124
|
+
});
|
|
125
|
+
client.track({ name: "ui.control.activate", category: "interaction", phase: "intent",
|
|
126
|
+
outcome: "success", attributes: { screen: "home", action: "select" } });
|
|
127
|
+
|
|
128
|
+
// Receiving hosts compile the same policy, then validate a bounded JSON body.
|
|
129
|
+
const validateAggregate = createSemanticJourneyAggregateValidator(aggregatePolicy);
|
|
130
|
+
// On consent withdrawal: client.destroy(); (discard, cancel; no flush).
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Each 2.1 counter contains a `view` and its exact registered enum `dimensions`.
|
|
134
|
+
The independent `total` view has no dimensions. Never sum across views. Missing
|
|
135
|
+
optional attributes omit their view; unknown fields/values reject the event.
|
|
136
|
+
Numeric/boolean attributes, private context, targets and causal IDs are not
|
|
137
|
+
projectable. Hosts must review the meaning of their finite tokens; grammar is
|
|
138
|
+
not an anonymity guarantee.
|
|
139
|
+
|
|
140
|
+
Policies allow at most 128 exact producer bindings, eight views per event, four
|
|
141
|
+
enum dimensions per view and 4,096 value combinations per view. The generated
|
|
142
|
+
validator rejects duplicate counter keys, unsafe counts, unknown fields and
|
|
143
|
+
payloads above 500 rows/64 KiB; bound HTTP reads before parsing as well.
|
|
144
|
+
|
|
145
|
+
The shared client keeps one retry snapshot and original observation hours, with
|
|
146
|
+
projected rows bounded by its queue count/byte/age settings (default 1,000 rows,
|
|
147
|
+
1 MiB, 30 minutes). To preserve consistency, expiry discards the whole pending
|
|
148
|
+
hour when its oldest row expires, potentially discarding newer observations in
|
|
149
|
+
that hour. Drops are reported, not silently retained. Projected clients default
|
|
150
|
+
to two 48-KiB batches per 60-second flush, two retries and five-second deadlines.
|
|
151
|
+
Client construction rejects `aggregateMaxBytes` if the budget cannot fit every
|
|
152
|
+
approved single-row envelope, including maximum safe counters and diagnostics.
|
|
153
|
+
Standalone projected stores validate their `maxBatchBytes` ceiling the same way;
|
|
154
|
+
per-batch overrides must fit the policy and remain within that ceiling.
|
|
155
|
+
No policy means unchanged strict 2.0 output. The validator explicitly supports
|
|
156
|
+
strict 2.0 input; it does not accept unrestricted legacy event packets.
|
|
157
|
+
|
|
158
|
+
Hosts own consent and remote controls, storage/retention, deduplication,
|
|
159
|
+
processing and low-volume report suppression. Shipping this SDK enables none of
|
|
160
|
+
those production behaviours. See [projection design](docs/design/aggregate-projections.md).
|
|
161
|
+
|
|
162
|
+
### Local causal capture and receipts
|
|
163
|
+
|
|
79
164
|
The client defaults to disabled. Hosts must pass the remotely resolved `platform.analytics.semantic-journeys.enabled` decision:
|
|
80
165
|
|
|
81
166
|
```ts
|