@fire-spark/analytics 0.17.3 → 0.19.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 +34 -0
- package/dist/index.d.ts +119 -6
- package/dist/index.js +1759 -574
- package/package.json +3 -2
package/README.md
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# @fire-spark/analytics
|
|
2
|
+
|
|
3
|
+
Sends events to Fire Spark and to the GA4, Meta, TikTok and Masivo adapters.
|
|
4
|
+
|
|
5
|
+
```typescript
|
|
6
|
+
import { analytics } from "@fire-spark/analytics";
|
|
7
|
+
import { ga4 } from "@fire-spark/analytics-ga4";
|
|
8
|
+
|
|
9
|
+
await analytics.configure({
|
|
10
|
+
channel_id: "web",
|
|
11
|
+
platform: "web",
|
|
12
|
+
storage: window.localStorage,
|
|
13
|
+
getCustomer: () => session.customer,
|
|
14
|
+
adapters: [ga4({ measurementId: "G-XXXXXXX" })],
|
|
15
|
+
onError: issue => console.error(issue)
|
|
16
|
+
});
|
|
17
|
+
|
|
18
|
+
await analytics.track("add_to_cart", { product_id: "p1", quantity: 1 });
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Behavior to know before you integrate:
|
|
22
|
+
|
|
23
|
+
- Calls to `track()` before `configure()` are kept and sent once it runs.
|
|
24
|
+
- Fire Spark stores funnel and interaction events and any event sent as
|
|
25
|
+
`track({ name, properties })`. `track("name", params)` with another name
|
|
26
|
+
only reaches the destinations (by design).
|
|
27
|
+
- Fire Spark keeps one event per funnel step per session; destinations
|
|
28
|
+
receive every occurrence.
|
|
29
|
+
- The queue is sent on its own (`flushAt`, `flushIntervalMs`, page hide on
|
|
30
|
+
web, `appState` in React Native).
|
|
31
|
+
- Destination failures go to `onError`; `track()` never rejects for them.
|
|
32
|
+
- `setUser()` and `setConsent()` reach every destination.
|
|
33
|
+
|
|
34
|
+
Guide: https://firespark.cloud/docs/guides/analytics/use-analytics-in-the-sdk
|
package/dist/index.d.ts
CHANGED
|
@@ -28,26 +28,69 @@ type AnalyticsScope = {
|
|
|
28
28
|
};
|
|
29
29
|
type DestinationProviderId = "ga4" | "meta" | "masivo" | "tiktok";
|
|
30
30
|
type AnalyticsRuntime = "web" | "react-native";
|
|
31
|
+
/**
|
|
32
|
+
* `analytics` gates GA4 and Masivo; `ads` gates Meta and TikTok. Fire Spark
|
|
33
|
+
* ingest is first-party and is not gated.
|
|
34
|
+
*/
|
|
31
35
|
type AnalyticsConsent = {
|
|
32
36
|
analytics: boolean;
|
|
33
37
|
ads: boolean;
|
|
34
38
|
};
|
|
39
|
+
/** User identity forwarded to destinations. `id: null` clears it. */
|
|
40
|
+
type AnalyticsUser = {
|
|
41
|
+
id?: string | null;
|
|
42
|
+
properties?: Record<string, string | number | boolean | null>;
|
|
43
|
+
};
|
|
44
|
+
type AnalyticsIssueSource = "configure" | "destination" | "ingest" | "sample" | "track" | "hash";
|
|
45
|
+
/** Problem the SDK hit without throwing to the caller. */
|
|
46
|
+
type AnalyticsIssue = {
|
|
47
|
+
level: "error" | "warning";
|
|
48
|
+
source: AnalyticsIssueSource;
|
|
49
|
+
message: string;
|
|
50
|
+
error?: unknown;
|
|
51
|
+
provider?: DestinationProviderId;
|
|
52
|
+
event?: string;
|
|
53
|
+
};
|
|
54
|
+
/** Host hash for PII. Must return the lowercase hex SHA-256 of `value`. */
|
|
55
|
+
type AnalyticsHash = (value: string) => string | Promise<string>;
|
|
56
|
+
/** Subset of React Native `AppState`. */
|
|
57
|
+
type AnalyticsAppState = {
|
|
58
|
+
addEventListener: (type: "change", listener: (state: string) => void) => {
|
|
59
|
+
remove: () => void;
|
|
60
|
+
} | undefined | void;
|
|
61
|
+
};
|
|
35
62
|
type AnalyticsSampleOptions = {
|
|
36
63
|
firstPerEvent?: boolean;
|
|
37
64
|
rate?: number;
|
|
38
65
|
};
|
|
39
66
|
type NormalizedEvent = {
|
|
67
|
+
/** Destination event name (catalog binding, or the tracked name). */
|
|
40
68
|
name: string;
|
|
69
|
+
/** Destination payload: catalog params merged with the provider fields. */
|
|
41
70
|
params: Record<string, unknown>;
|
|
42
71
|
items?: Array<Record<string, unknown>>;
|
|
43
72
|
userProperties?: Record<string, unknown>;
|
|
44
73
|
context: Record<string, unknown>;
|
|
45
74
|
runtime: AnalyticsRuntime;
|
|
46
75
|
consent: AnalyticsConsent;
|
|
76
|
+
/** Same id for every destination of one `track()`, for deduplication. */
|
|
77
|
+
eventId?: string;
|
|
78
|
+
/** Hashed advanced-matching fields (Meta and TikTok). */
|
|
79
|
+
userData?: Record<string, string>;
|
|
80
|
+
/** Meta app events `valueToSum` (react-native). */
|
|
81
|
+
valueToSum?: number;
|
|
82
|
+
/**
|
|
83
|
+
* Current user. Ads providers (Meta, TikTok) receive the SHA-256 of `id`.
|
|
84
|
+
*/
|
|
85
|
+
user?: AnalyticsUser;
|
|
47
86
|
};
|
|
48
87
|
type AnalyticsAdapter = {
|
|
49
88
|
provider: DestinationProviderId;
|
|
50
89
|
send: (event: NormalizedEvent) => Promise<void> | void;
|
|
90
|
+
/** Called by `setUser()`. Ads providers receive the SHA-256 of `id`. */
|
|
91
|
+
setUser?: (user: AnalyticsUser, runtime: AnalyticsRuntime) => Promise<void> | void;
|
|
92
|
+
/** Called by `setConsent()`, also when consent is revoked. */
|
|
93
|
+
setConsent?: (consent: AnalyticsConsent, runtime: AnalyticsRuntime) => Promise<void> | void;
|
|
51
94
|
};
|
|
52
95
|
type TrackOptions = {
|
|
53
96
|
only?: DestinationProviderId[];
|
|
@@ -114,6 +157,8 @@ type AnalyticsLimits = {
|
|
|
114
157
|
type AnalyticsMerchantContext = () => Record<string, unknown>;
|
|
115
158
|
type AnalyticsConfigureOptions = {
|
|
116
159
|
baseUrl?: string;
|
|
160
|
+
/** Storage key prefix. Use a different one per `Analytics` instance. */
|
|
161
|
+
storagePrefix?: string;
|
|
117
162
|
getAccessToken?: () => Promise<string>;
|
|
118
163
|
storage: AnalyticsStorage;
|
|
119
164
|
getCustomer: () => AnalyticsCustomer | null;
|
|
@@ -126,13 +171,38 @@ type AnalyticsConfigureOptions = {
|
|
|
126
171
|
limits?: AnalyticsLimits;
|
|
127
172
|
fetchImpl?: typeof fetch;
|
|
128
173
|
sessionMs?: number;
|
|
174
|
+
/**
|
|
175
|
+
* ISO 4217 code. An invalid code is reported and ignored; the merchant
|
|
176
|
+
* currency from preferences is used instead.
|
|
177
|
+
*/
|
|
129
178
|
currency?: string;
|
|
130
179
|
adapters?: AnalyticsAdapter[];
|
|
131
180
|
env?: "production" | "staging";
|
|
132
181
|
planVersionId?: string;
|
|
182
|
+
/** Read on every event unless `setConsent()` was called. */
|
|
133
183
|
consent?: () => AnalyticsConsent;
|
|
134
184
|
sample?: AnalyticsSampleOptions;
|
|
135
185
|
runtime?: AnalyticsRuntime;
|
|
186
|
+
/** Errors (destination failures, dropped events). Default `console.error`. */
|
|
187
|
+
onError?: (issue: AnalyticsIssue) => void;
|
|
188
|
+
/** Recoverable problems. Default `console.warn`. */
|
|
189
|
+
onWarning?: (issue: AnalyticsIssue) => void;
|
|
190
|
+
/**
|
|
191
|
+
* SHA-256 for PII sent to Meta and TikTok. Defaults to `crypto.subtle`,
|
|
192
|
+
* or a built-in implementation when it is missing (Hermes, insecure web).
|
|
193
|
+
*/
|
|
194
|
+
hash?: AnalyticsHash;
|
|
195
|
+
/** Send the queue once it holds this many events. Default 20. */
|
|
196
|
+
flushAt?: number;
|
|
197
|
+
/** Send the queue this long after an event is queued. 0 disables. */
|
|
198
|
+
flushIntervalMs?: number;
|
|
199
|
+
/**
|
|
200
|
+
* Send the queue when the page is hidden (`visibilitychange`,
|
|
201
|
+
* `pagehide`, with `keepalive`). Default true on web.
|
|
202
|
+
*/
|
|
203
|
+
flushOnHide?: boolean;
|
|
204
|
+
/** React Native `AppState`: the queue is sent when the app backgrounds. */
|
|
205
|
+
appState?: AnalyticsAppState;
|
|
136
206
|
};
|
|
137
207
|
type AnalyticsConfig = {
|
|
138
208
|
session: {
|
|
@@ -145,24 +215,65 @@ declare const isFunnelEventName: (name: string) => name is FunnelEventName;
|
|
|
145
215
|
declare const isInteractionEventName: (name: string) => name is InteractionEventName;
|
|
146
216
|
//#endregion
|
|
147
217
|
//#region src/flush.d.ts
|
|
218
|
+
/** Sends the default instance queue to Fire Spark. */
|
|
148
219
|
declare const flush: () => Promise<void>;
|
|
149
220
|
//#endregion
|
|
221
|
+
//#region src/version.d.ts
|
|
222
|
+
/** Kept equal to package.json by `pnpm sdk:release` (see version.test.ts). */
|
|
223
|
+
declare const SDK_VERSION = "0.19.0";
|
|
224
|
+
//#endregion
|
|
225
|
+
//#region src/compact.d.ts
|
|
226
|
+
/** Drops `undefined`, `null`, non-finite numbers and functions, deeply. */
|
|
227
|
+
declare const compactPayload: (value: Record<string, unknown>) => Record<string, unknown>;
|
|
228
|
+
//#endregion
|
|
229
|
+
//#region src/script.d.ts
|
|
230
|
+
/**
|
|
231
|
+
* True when the page has a `<script>` whose `src` starts with `prefix`,
|
|
232
|
+
* ignoring the one with id `exceptId` (the adapter's own).
|
|
233
|
+
*/
|
|
234
|
+
declare const hasScript: (prefix: string, exceptId?: string) => boolean;
|
|
235
|
+
/**
|
|
236
|
+
* Injects `src` once per page. A failed script is removed and forgotten, so
|
|
237
|
+
* the next call retries. Returns null outside a browser.
|
|
238
|
+
*/
|
|
239
|
+
declare const loadScript: (src: string, id: string) => Promise<void> | null;
|
|
240
|
+
//#endregion
|
|
150
241
|
//#region src/index.d.ts
|
|
151
|
-
declare const configure: (options: AnalyticsConfigureOptions) => Promise<void>;
|
|
152
242
|
type TrackName = (name: string, params?: Record<string, unknown>, opts?: TrackOptions) => Promise<void>;
|
|
153
243
|
type TrackAlias = (event: TrackEvent) => Promise<void>;
|
|
154
244
|
type TrackEither = (nameOrEvent: string | TrackEvent, params?: Record<string, unknown>, opts?: TrackOptions) => Promise<void>;
|
|
245
|
+
/**
|
|
246
|
+
* Both forms reach the destinations. Fire Spark stores funnel and
|
|
247
|
+
* interaction events, and any event sent with the object form
|
|
248
|
+
* `track({ name, properties })`; `track("name", params)` with another name
|
|
249
|
+
* is not stored (by design). Calls before `configure()` are kept and sent
|
|
250
|
+
* once it runs.
|
|
251
|
+
*/
|
|
155
252
|
type TrackFn = TrackName & TrackAlias & TrackEither;
|
|
253
|
+
declare const configure: (options: AnalyticsConfigureOptions) => Promise<void>;
|
|
156
254
|
declare const track: TrackFn;
|
|
157
255
|
declare const endSession: () => Promise<void>;
|
|
158
256
|
declare const reset: () => Promise<void>;
|
|
257
|
+
/** User for destinations (GA4 user_id, Meta/TikTok external_id). */
|
|
258
|
+
declare const setUser: (user: AnalyticsUser | null) => Promise<void>;
|
|
259
|
+
/** Updates consent and propagates it to every destination. */
|
|
260
|
+
declare const setConsent: (consent: AnalyticsConsent) => Promise<void>;
|
|
261
|
+
/**
|
|
262
|
+
* Independent analytics client: its own queue, session, timers and
|
|
263
|
+
* adapters. The module-level functions use a shared default instance.
|
|
264
|
+
*/
|
|
159
265
|
declare class Analytics {
|
|
266
|
+
#private;
|
|
267
|
+
/** Settles when the constructor `configure()` finishes. */
|
|
268
|
+
readonly ready: Promise<void>;
|
|
160
269
|
constructor(options?: AnalyticsConfigureOptions);
|
|
161
|
-
configure:
|
|
270
|
+
configure: (options: AnalyticsConfigureOptions) => Promise<void>;
|
|
162
271
|
track: TrackFn;
|
|
163
|
-
flush:
|
|
164
|
-
endSession:
|
|
165
|
-
reset:
|
|
272
|
+
flush: () => Promise<void>;
|
|
273
|
+
endSession: () => Promise<void>;
|
|
274
|
+
reset: () => Promise<void>;
|
|
275
|
+
setUser: (user: AnalyticsUser | null) => Promise<void>;
|
|
276
|
+
setConsent: (consent: AnalyticsConsent) => Promise<void>;
|
|
166
277
|
}
|
|
167
278
|
declare const analytics: {
|
|
168
279
|
configure: typeof configure;
|
|
@@ -170,6 +281,8 @@ declare const analytics: {
|
|
|
170
281
|
flush: typeof flush;
|
|
171
282
|
endSession: typeof endSession;
|
|
172
283
|
reset: typeof reset;
|
|
284
|
+
setUser: typeof setUser;
|
|
285
|
+
setConsent: typeof setConsent;
|
|
173
286
|
};
|
|
174
287
|
//#endregion
|
|
175
|
-
export { Analytics, type AnalyticsAdapter, type AnalyticsConfig, type AnalyticsConfigureOptions, type AnalyticsConsent, type AnalyticsContext, type AnalyticsCustomer, type AnalyticsPlatform, type AnalyticsRuntime, type AnalyticsSampleOptions, type AnalyticsScope, type AnalyticsStorage, type DestinationProviderId, FUNNEL_EVENTS, type FunnelEventName, INTERACTION_EVENTS, type InteractionEventName, type NormalizedEvent, type TrackOptions as TrackCallOptions, type TrackOptions, type TrackEvent, analytics, configure, endSession, flush, isFunnelEventName, isInteractionEventName, reset, track };
|
|
288
|
+
export { Analytics, type AnalyticsAdapter, type AnalyticsAppState, type AnalyticsConfig, type AnalyticsConfigureOptions, type AnalyticsConsent, type AnalyticsContext, type AnalyticsCustomer, type AnalyticsHash, type AnalyticsIssue, type AnalyticsIssueSource, type AnalyticsPlatform, type AnalyticsRuntime, type AnalyticsSampleOptions, type AnalyticsScope, type AnalyticsStorage, type AnalyticsUser, type DestinationProviderId, FUNNEL_EVENTS, type FunnelEventName, INTERACTION_EVENTS, type InteractionEventName, type NormalizedEvent, SDK_VERSION, type TrackOptions as TrackCallOptions, type TrackOptions, type TrackEvent, analytics, compactPayload, configure, endSession, flush, hasScript, isFunnelEventName, isInteractionEventName, loadScript, reset, setConsent, setUser, track };
|