@analyticscli/sdk 0.1.0-preview.10
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/LICENSE +21 -0
- package/README.md +239 -0
- package/dist/browser.cjs +1978 -0
- package/dist/browser.d.cts +1 -0
- package/dist/browser.d.ts +1 -0
- package/dist/browser.js +36 -0
- package/dist/chunk-6EPJZLLK.js +1937 -0
- package/dist/index.cjs +1978 -0
- package/dist/index.d.cts +587 -0
- package/dist/index.d.ts +587 -0
- package/dist/index.js +36 -0
- package/dist/react-native.cjs +1978 -0
- package/dist/react-native.d.cts +1 -0
- package/dist/react-native.d.ts +1 -0
- package/dist/react-native.js +36 -0
- package/package.json +58 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,587 @@
|
|
|
1
|
+
declare const ONBOARDING_EVENTS: {
|
|
2
|
+
readonly START: "onboarding:start";
|
|
3
|
+
readonly STEP_VIEW: "onboarding:step_view";
|
|
4
|
+
readonly STEP_COMPLETE: "onboarding:step_complete";
|
|
5
|
+
readonly COMPLETE: "onboarding:complete";
|
|
6
|
+
readonly SKIP: "onboarding:skip";
|
|
7
|
+
};
|
|
8
|
+
type OnboardingEventName = (typeof ONBOARDING_EVENTS)[keyof typeof ONBOARDING_EVENTS];
|
|
9
|
+
declare const PAYWALL_EVENTS: {
|
|
10
|
+
readonly SHOWN: "paywall:shown";
|
|
11
|
+
readonly SKIP: "paywall:skip";
|
|
12
|
+
};
|
|
13
|
+
type PaywallEventName = (typeof PAYWALL_EVENTS)[keyof typeof PAYWALL_EVENTS];
|
|
14
|
+
declare const PURCHASE_EVENTS: {
|
|
15
|
+
readonly STARTED: "purchase:started";
|
|
16
|
+
readonly SUCCESS: "purchase:success";
|
|
17
|
+
readonly FAILED: "purchase:failed";
|
|
18
|
+
readonly CANCEL: "purchase:cancel";
|
|
19
|
+
};
|
|
20
|
+
type PurchaseEventName = (typeof PURCHASE_EVENTS)[keyof typeof PURCHASE_EVENTS];
|
|
21
|
+
type PaywallJourneyEventName = PaywallEventName | PurchaseEventName;
|
|
22
|
+
declare const ONBOARDING_SURVEY_EVENTS: {
|
|
23
|
+
readonly RESPONSE: "onboarding:survey_response";
|
|
24
|
+
};
|
|
25
|
+
type OnboardingSurveyEventName = (typeof ONBOARDING_SURVEY_EVENTS)[keyof typeof ONBOARDING_SURVEY_EVENTS];
|
|
26
|
+
declare const ONBOARDING_PROGRESS_EVENT_ORDER: readonly ["onboarding:complete", "onboarding:skip"];
|
|
27
|
+
declare const PAYWALL_JOURNEY_EVENT_ORDER: readonly ["paywall:shown", "paywall:skip", "purchase:success", "purchase:failed"];
|
|
28
|
+
declare const ONBOARDING_SCREEN_EVENT_PREFIXES: readonly ["screen:onboarding", "screen:onboarding_"];
|
|
29
|
+
declare const PAYWALL_ANCHOR_EVENT_CANDIDATES: readonly ["paywall:shown"];
|
|
30
|
+
declare const PAYWALL_SKIP_EVENT_CANDIDATES: readonly ["paywall:skip"];
|
|
31
|
+
declare const PURCHASE_SUCCESS_EVENT_CANDIDATES: readonly ["purchase:success"];
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Arbitrary key/value payload sent with an event.
|
|
35
|
+
*/
|
|
36
|
+
type EventProperties = Record<string, unknown>;
|
|
37
|
+
type StorageGetItemCallback = (error?: Error | null, value?: string | null) => void;
|
|
38
|
+
type StorageMutationCallback = (error?: Error | null) => void;
|
|
39
|
+
type AnalyticsStorageAdapter = {
|
|
40
|
+
/**
|
|
41
|
+
* Storage APIs can be sync or async.
|
|
42
|
+
* This allows passing AsyncStorage/localStorage directly, or custom adapters.
|
|
43
|
+
*/
|
|
44
|
+
getItem: (key: string, callback?: StorageGetItemCallback) => string | null | Promise<string | null>;
|
|
45
|
+
setItem: (key: string, value: string, callback?: StorageMutationCallback) => void | Promise<void>;
|
|
46
|
+
removeItem?: (key: string, callback?: StorageMutationCallback) => void | Promise<void>;
|
|
47
|
+
};
|
|
48
|
+
type EventContext = {
|
|
49
|
+
appBuild?: string;
|
|
50
|
+
osName?: string;
|
|
51
|
+
osVersion?: string;
|
|
52
|
+
country?: string;
|
|
53
|
+
region?: string;
|
|
54
|
+
city?: string;
|
|
55
|
+
};
|
|
56
|
+
type OnboardingEventProperties = EventProperties & {
|
|
57
|
+
isNewUser?: boolean;
|
|
58
|
+
onboardingFlowId?: string;
|
|
59
|
+
onboardingFlowVersion?: string | number;
|
|
60
|
+
onboardingExperimentId?: string;
|
|
61
|
+
stepKey?: string;
|
|
62
|
+
stepIndex?: number;
|
|
63
|
+
stepCount?: number;
|
|
64
|
+
};
|
|
65
|
+
type PaywallEventProperties = EventProperties & {
|
|
66
|
+
source: string;
|
|
67
|
+
fromScreen?: string;
|
|
68
|
+
paywallId?: string;
|
|
69
|
+
offering?: string;
|
|
70
|
+
paywallEntryId?: string;
|
|
71
|
+
packageId?: string;
|
|
72
|
+
price?: number;
|
|
73
|
+
currency?: string;
|
|
74
|
+
experimentVariant?: string;
|
|
75
|
+
entitlementKey?: string;
|
|
76
|
+
};
|
|
77
|
+
type OnboardingSurveyAnswerType = 'single_choice' | 'multiple_choice' | 'boolean' | 'numeric' | 'text' | 'unknown';
|
|
78
|
+
type OnboardingSurveyResponseInput = {
|
|
79
|
+
surveyKey: string;
|
|
80
|
+
questionKey: string;
|
|
81
|
+
answerType: OnboardingSurveyAnswerType;
|
|
82
|
+
responseKey?: string;
|
|
83
|
+
responseKeys?: string[];
|
|
84
|
+
responseBoolean?: boolean;
|
|
85
|
+
responseNumber?: number;
|
|
86
|
+
responseText?: string;
|
|
87
|
+
appVersion?: string;
|
|
88
|
+
isNewUser?: boolean;
|
|
89
|
+
onboardingFlowId?: string;
|
|
90
|
+
onboardingFlowVersion?: string | number;
|
|
91
|
+
onboardingExperimentId?: string;
|
|
92
|
+
stepKey?: string;
|
|
93
|
+
stepIndex?: number;
|
|
94
|
+
stepCount?: number;
|
|
95
|
+
experimentVariant?: string;
|
|
96
|
+
paywallId?: string;
|
|
97
|
+
properties?: EventProperties;
|
|
98
|
+
};
|
|
99
|
+
type OnboardingTrackerDefaults = OnboardingEventProperties & {
|
|
100
|
+
surveyKey?: string;
|
|
101
|
+
};
|
|
102
|
+
type OnboardingTrackerSurveyInput = Omit<OnboardingSurveyResponseInput, 'surveyKey'> & {
|
|
103
|
+
surveyKey?: string;
|
|
104
|
+
};
|
|
105
|
+
type OnboardingStepTracker = {
|
|
106
|
+
view: (properties?: Omit<OnboardingEventProperties, 'stepKey' | 'stepIndex'>) => void;
|
|
107
|
+
complete: (properties?: Omit<OnboardingEventProperties, 'stepKey' | 'stepIndex'>) => void;
|
|
108
|
+
surveyResponse: (input: Omit<OnboardingTrackerSurveyInput, 'stepKey' | 'stepIndex'>) => void;
|
|
109
|
+
};
|
|
110
|
+
type OnboardingTracker = {
|
|
111
|
+
track: (eventName: OnboardingEventName, properties?: OnboardingEventProperties) => void;
|
|
112
|
+
start: (properties?: OnboardingEventProperties) => void;
|
|
113
|
+
stepView: (properties: OnboardingEventProperties) => void;
|
|
114
|
+
stepComplete: (properties: OnboardingEventProperties) => void;
|
|
115
|
+
complete: (properties?: OnboardingEventProperties) => void;
|
|
116
|
+
skip: (properties?: OnboardingEventProperties) => void;
|
|
117
|
+
surveyResponse: (input: OnboardingTrackerSurveyInput) => void;
|
|
118
|
+
step: (stepKey: string, stepIndex: number, properties?: Omit<OnboardingEventProperties, 'stepKey' | 'stepIndex'>) => OnboardingStepTracker;
|
|
119
|
+
};
|
|
120
|
+
type PaywallTrackerDefaults = PaywallEventProperties;
|
|
121
|
+
type PaywallTrackerProperties = Partial<PaywallEventProperties>;
|
|
122
|
+
type PaywallTracker = {
|
|
123
|
+
track: (eventName: PaywallJourneyEventName, properties?: PaywallTrackerProperties) => void;
|
|
124
|
+
shown: (properties?: PaywallTrackerProperties) => void;
|
|
125
|
+
skip: (properties?: PaywallTrackerProperties) => void;
|
|
126
|
+
purchaseStarted: (properties?: PaywallTrackerProperties) => void;
|
|
127
|
+
purchaseSuccess: (properties?: PaywallTrackerProperties) => void;
|
|
128
|
+
purchaseFailed: (properties?: PaywallTrackerProperties) => void;
|
|
129
|
+
purchaseCancel: (properties?: PaywallTrackerProperties) => void;
|
|
130
|
+
};
|
|
131
|
+
type AnalyticsConsentState = 'granted' | 'denied' | 'unknown';
|
|
132
|
+
type IdentityTrackingMode = 'strict' | 'consent_gated' | 'always_on';
|
|
133
|
+
type AnalyticsIngestError = {
|
|
134
|
+
/**
|
|
135
|
+
* Stable error name for host-app monitoring.
|
|
136
|
+
*/
|
|
137
|
+
name: 'AnalyticsIngestError';
|
|
138
|
+
/**
|
|
139
|
+
* Human-readable summary of the ingest failure.
|
|
140
|
+
*/
|
|
141
|
+
message: string;
|
|
142
|
+
/**
|
|
143
|
+
* Collector endpoint base URL configured in the SDK client.
|
|
144
|
+
*/
|
|
145
|
+
endpoint: string;
|
|
146
|
+
/**
|
|
147
|
+
* Collector path that failed.
|
|
148
|
+
*/
|
|
149
|
+
path: '/v1/collect';
|
|
150
|
+
/**
|
|
151
|
+
* HTTP status when available.
|
|
152
|
+
*/
|
|
153
|
+
status?: number;
|
|
154
|
+
/**
|
|
155
|
+
* Structured server error code when available.
|
|
156
|
+
*/
|
|
157
|
+
errorCode?: string;
|
|
158
|
+
/**
|
|
159
|
+
* Structured server message when available.
|
|
160
|
+
*/
|
|
161
|
+
serverMessage?: string;
|
|
162
|
+
/**
|
|
163
|
+
* Request correlation id when exposed by the collector response.
|
|
164
|
+
*/
|
|
165
|
+
requestId?: string;
|
|
166
|
+
/**
|
|
167
|
+
* Whether retrying can help (`true` for network/5xx/429 class failures).
|
|
168
|
+
*/
|
|
169
|
+
retryable: boolean;
|
|
170
|
+
/**
|
|
171
|
+
* Number of attempts that were made for this batch.
|
|
172
|
+
*/
|
|
173
|
+
attempts: number;
|
|
174
|
+
/**
|
|
175
|
+
* SDK max retries configured on the client.
|
|
176
|
+
*/
|
|
177
|
+
maxRetries: number;
|
|
178
|
+
/**
|
|
179
|
+
* Number of events in the failed batch.
|
|
180
|
+
*/
|
|
181
|
+
batchSize: number;
|
|
182
|
+
/**
|
|
183
|
+
* Current queue size after requeue.
|
|
184
|
+
*/
|
|
185
|
+
queueSize: number;
|
|
186
|
+
/**
|
|
187
|
+
* ISO timestamp when the failure was surfaced to host-app callbacks.
|
|
188
|
+
*/
|
|
189
|
+
timestamp: string;
|
|
190
|
+
};
|
|
191
|
+
type AnalyticsIngestErrorHandler = (error: AnalyticsIngestError) => void;
|
|
192
|
+
type SetConsentOptions = {
|
|
193
|
+
/**
|
|
194
|
+
* Whether consent state should be persisted to storage when enabled.
|
|
195
|
+
*/
|
|
196
|
+
persist?: boolean;
|
|
197
|
+
};
|
|
198
|
+
type AnalyticsClientOptions = {
|
|
199
|
+
/**
|
|
200
|
+
* Publishable ingest API key.
|
|
201
|
+
* If omitted, the client becomes a safe no-op until a valid key is provided.
|
|
202
|
+
*/
|
|
203
|
+
apiKey?: string | null;
|
|
204
|
+
/**
|
|
205
|
+
* Optional collector override reserved for SDK/internal testing.
|
|
206
|
+
* Host app integrations should not set this option.
|
|
207
|
+
*/
|
|
208
|
+
endpoint?: string | null;
|
|
209
|
+
batchSize?: number | null;
|
|
210
|
+
flushIntervalMs?: number | null;
|
|
211
|
+
maxRetries?: number | null;
|
|
212
|
+
/**
|
|
213
|
+
* Enables SDK debug logs (`console.debug`).
|
|
214
|
+
* Defaults to `false`.
|
|
215
|
+
*
|
|
216
|
+
* React Native/Expo recommendation:
|
|
217
|
+
* `debug: __DEV__`
|
|
218
|
+
*/
|
|
219
|
+
debug?: boolean | null;
|
|
220
|
+
/**
|
|
221
|
+
* Optional host-app hook for ingest delivery failures.
|
|
222
|
+
* Use this to forward operational diagnostics to your own monitoring stack.
|
|
223
|
+
*
|
|
224
|
+
* GDPR recommendation:
|
|
225
|
+
* forward this structured metadata only and avoid attaching event payloads or raw identifiers.
|
|
226
|
+
*/
|
|
227
|
+
onIngestError?: AnalyticsIngestErrorHandler | null;
|
|
228
|
+
/**
|
|
229
|
+
* Optional platform hint.
|
|
230
|
+
* React Native/Expo: passing `Platform.OS` directly is supported.
|
|
231
|
+
*/
|
|
232
|
+
platform?: string | null;
|
|
233
|
+
/**
|
|
234
|
+
* Optional app version hint.
|
|
235
|
+
* Accepts nullable runtime values (for example Expo's `nativeApplicationVersion`).
|
|
236
|
+
*/
|
|
237
|
+
appVersion?: string | null;
|
|
238
|
+
/**
|
|
239
|
+
* Optional project surface hint to separate product surfaces/channels
|
|
240
|
+
* (for example `landing`, `dashboard`, `app`) from runtime `platform`.
|
|
241
|
+
*/
|
|
242
|
+
projectSurface?: string | null;
|
|
243
|
+
/**
|
|
244
|
+
* Initial event-collection consent state.
|
|
245
|
+
* Defaults to `true` when `apiKey` is present.
|
|
246
|
+
* Set to `false` to enforce explicit `optIn()` / `setConsent(true)` before event collection.
|
|
247
|
+
*/
|
|
248
|
+
initialConsentGranted?: boolean | null;
|
|
249
|
+
/**
|
|
250
|
+
* Controls identity persistence behavior.
|
|
251
|
+
* - `consent_gated` (default): starts in strict mode and enables persistence only after consent
|
|
252
|
+
* - `always_on`: enables persistence immediately
|
|
253
|
+
* - `strict`: disables persistence and identity linkage
|
|
254
|
+
*/
|
|
255
|
+
identityTrackingMode?: IdentityTrackingMode | null;
|
|
256
|
+
/**
|
|
257
|
+
* Boolean shortcut for `identityTrackingMode: 'always_on'`.
|
|
258
|
+
* Kept for host-app ergonomics.
|
|
259
|
+
*/
|
|
260
|
+
enableFullTrackingWithoutConsent?: boolean | null;
|
|
261
|
+
/**
|
|
262
|
+
* Initial consent state for identity persistence when `identityTrackingMode='consent_gated'`.
|
|
263
|
+
* Defaults to `false`.
|
|
264
|
+
*/
|
|
265
|
+
initialFullTrackingConsentGranted?: boolean | null;
|
|
266
|
+
/**
|
|
267
|
+
* Persist full-tracking consent in configured storage.
|
|
268
|
+
*/
|
|
269
|
+
persistConsentState?: boolean | null;
|
|
270
|
+
/**
|
|
271
|
+
* Storage key for persisted full-tracking consent state.
|
|
272
|
+
* Defaults to `analyticscli:consent:v1`.
|
|
273
|
+
*/
|
|
274
|
+
consentStorageKey?: string | null;
|
|
275
|
+
context?: EventContext | null;
|
|
276
|
+
/**
|
|
277
|
+
* Optional custom persistence adapter used when identity persistence is active.
|
|
278
|
+
*/
|
|
279
|
+
storage?: AnalyticsStorageAdapter | null;
|
|
280
|
+
/**
|
|
281
|
+
* Optional explicit anonymous device id when identity persistence is active.
|
|
282
|
+
*/
|
|
283
|
+
anonId?: string | null;
|
|
284
|
+
/**
|
|
285
|
+
* Optional explicit session id when identity persistence is active.
|
|
286
|
+
*/
|
|
287
|
+
sessionId?: string | null;
|
|
288
|
+
sessionTimeoutMs?: number | null;
|
|
289
|
+
/**
|
|
290
|
+
* Drops duplicate `onboarding:step_view` events for the same step within one session.
|
|
291
|
+
* This only affects the dedicated onboarding step-view event, not `screen(...)` or paywall events.
|
|
292
|
+
* Defaults to `true`. Set to `false` to disable this behavior.
|
|
293
|
+
*/
|
|
294
|
+
dedupeOnboardingStepViewsPerSession?: boolean | null;
|
|
295
|
+
/**
|
|
296
|
+
* Drops immediate duplicate `screen(...)` events for the same screen key within one session.
|
|
297
|
+
* This guards against double-fired focus/mount hooks while keeping intentional revisits intact.
|
|
298
|
+
* Defaults to `true`. Set to `false` to disable this behavior.
|
|
299
|
+
*/
|
|
300
|
+
dedupeScreenViewsPerSession?: boolean | null;
|
|
301
|
+
/**
|
|
302
|
+
* Time window used by `dedupeScreenViewsPerSession` in milliseconds.
|
|
303
|
+
* A duplicate screen event emitted again within this window is dropped.
|
|
304
|
+
* Defaults to `1200`.
|
|
305
|
+
*/
|
|
306
|
+
screenViewDedupeWindowMs?: number | null;
|
|
307
|
+
/**
|
|
308
|
+
* Cookie domain for optional cookie-backed persistence.
|
|
309
|
+
*/
|
|
310
|
+
cookieDomain?: string | null;
|
|
311
|
+
cookieMaxAgeSeconds?: number | null;
|
|
312
|
+
/**
|
|
313
|
+
* Enables cookie-backed persistence in browsers.
|
|
314
|
+
*/
|
|
315
|
+
useCookieStorage?: boolean | null;
|
|
316
|
+
};
|
|
317
|
+
type InitOptions = AnalyticsClientOptions;
|
|
318
|
+
type InitInput = InitOptions | string | null | undefined;
|
|
319
|
+
|
|
320
|
+
declare class AnalyticsClient {
|
|
321
|
+
private readonly apiKey;
|
|
322
|
+
private readonly hasIngestConfig;
|
|
323
|
+
private readonly endpoint;
|
|
324
|
+
private readonly batchSize;
|
|
325
|
+
private readonly flushIntervalMs;
|
|
326
|
+
private readonly maxRetries;
|
|
327
|
+
private readonly debug;
|
|
328
|
+
private readonly onIngestError;
|
|
329
|
+
private readonly platform;
|
|
330
|
+
private readonly projectSurface;
|
|
331
|
+
private readonly appVersion;
|
|
332
|
+
private readonly identityTrackingMode;
|
|
333
|
+
private context;
|
|
334
|
+
private readonly configuredStorage;
|
|
335
|
+
private storage;
|
|
336
|
+
private storageReadsAreAsync;
|
|
337
|
+
private readonly persistConsentState;
|
|
338
|
+
private readonly consentStorageKey;
|
|
339
|
+
private readonly hasExplicitInitialConsent;
|
|
340
|
+
private readonly hasExplicitInitialFullTrackingConsent;
|
|
341
|
+
private readonly sessionTimeoutMs;
|
|
342
|
+
private readonly dedupeOnboardingStepViewsPerSession;
|
|
343
|
+
private readonly dedupeScreenViewsPerSession;
|
|
344
|
+
private readonly screenViewDedupeWindowMs;
|
|
345
|
+
private readonly runtimeEnv;
|
|
346
|
+
private readonly hasExplicitAnonId;
|
|
347
|
+
private readonly hasExplicitSessionId;
|
|
348
|
+
private readonly hydrationPromise;
|
|
349
|
+
private queue;
|
|
350
|
+
private flushTimer;
|
|
351
|
+
private isFlushing;
|
|
352
|
+
private consentGranted;
|
|
353
|
+
private fullTrackingConsentGranted;
|
|
354
|
+
private userId;
|
|
355
|
+
private anonId;
|
|
356
|
+
private sessionId;
|
|
357
|
+
private sessionEventSeq;
|
|
358
|
+
private inMemoryLastSeenMs;
|
|
359
|
+
private hydrationCompleted;
|
|
360
|
+
private deferredEventsBeforeHydration;
|
|
361
|
+
private onboardingStepViewStateSessionId;
|
|
362
|
+
private onboardingStepViewsSeen;
|
|
363
|
+
private lastScreenViewDedupeSessionId;
|
|
364
|
+
private lastScreenViewDedupeKey;
|
|
365
|
+
private lastScreenViewDedupeTsMs;
|
|
366
|
+
private flushPausedUntilMs;
|
|
367
|
+
constructor(options: AnalyticsClientOptions);
|
|
368
|
+
/**
|
|
369
|
+
* Resolves once client initialization work completes.
|
|
370
|
+
*/
|
|
371
|
+
ready(): Promise<void>;
|
|
372
|
+
/**
|
|
373
|
+
* Enables or disables event collection.
|
|
374
|
+
* When disabled, queued events are dropped immediately.
|
|
375
|
+
*/
|
|
376
|
+
setConsent(granted: boolean, options?: SetConsentOptions): void;
|
|
377
|
+
optIn(options?: SetConsentOptions): void;
|
|
378
|
+
optOut(options?: SetConsentOptions): void;
|
|
379
|
+
getConsent(): boolean;
|
|
380
|
+
getConsentState(): AnalyticsConsentState;
|
|
381
|
+
/**
|
|
382
|
+
* Sets or updates shared event context fields (useful for mobile device/app metadata).
|
|
383
|
+
*/
|
|
384
|
+
setContext(context: EventContext): void;
|
|
385
|
+
private enqueueInitialSessionStart;
|
|
386
|
+
/**
|
|
387
|
+
* Associates following events with a known user id.
|
|
388
|
+
* Anonymous history remains linked by anonId/sessionId.
|
|
389
|
+
*/
|
|
390
|
+
identify(userId: string, traits?: EventProperties): void;
|
|
391
|
+
/**
|
|
392
|
+
* Convenience helper for login/logout boundaries.
|
|
393
|
+
* - pass a non-empty user id to emit an identify event
|
|
394
|
+
* - pass null/undefined/empty string to clear user linkage
|
|
395
|
+
*/
|
|
396
|
+
setUser(userId: string | null | undefined, traits?: EventProperties): void;
|
|
397
|
+
/**
|
|
398
|
+
* Sets consent specifically for persistent identity tracking.
|
|
399
|
+
* In `consent_gated` mode this toggles strict-vs-full identity behavior while generic event tracking can stay enabled.
|
|
400
|
+
*/
|
|
401
|
+
setFullTrackingConsent(granted: boolean, options?: SetConsentOptions): void;
|
|
402
|
+
optInFullTracking(options?: SetConsentOptions): void;
|
|
403
|
+
optOutFullTracking(options?: SetConsentOptions): void;
|
|
404
|
+
isFullTrackingEnabled(): boolean;
|
|
405
|
+
/**
|
|
406
|
+
* Clears the current identified user from in-memory SDK state.
|
|
407
|
+
*/
|
|
408
|
+
clearUser(): void;
|
|
409
|
+
/**
|
|
410
|
+
* Sends a generic product event.
|
|
411
|
+
*/
|
|
412
|
+
track(eventName: string, properties?: EventProperties): void;
|
|
413
|
+
/**
|
|
414
|
+
* Sends a typed onboarding event with conventional onboarding metadata.
|
|
415
|
+
*/
|
|
416
|
+
trackOnboardingEvent(eventName: OnboardingEventName, properties?: OnboardingEventProperties): void;
|
|
417
|
+
/**
|
|
418
|
+
* Creates a scoped onboarding tracker that applies shared flow properties to every onboarding event.
|
|
419
|
+
* This reduces app-side boilerplate while keeping each emitted event fully self-describing.
|
|
420
|
+
*/
|
|
421
|
+
createOnboardingTracker(defaults: OnboardingTrackerDefaults): OnboardingTracker;
|
|
422
|
+
/**
|
|
423
|
+
* Creates a scoped paywall tracker that applies shared paywall defaults to every journey event.
|
|
424
|
+
* Useful when a flow has a stable `source`, `paywallId`, `offering`, or experiment metadata.
|
|
425
|
+
* Reuse the returned tracker for that flow context; creating a new tracker per event resets
|
|
426
|
+
* paywall entry correlation.
|
|
427
|
+
*/
|
|
428
|
+
createPaywallTracker(defaults: PaywallTrackerDefaults): PaywallTracker;
|
|
429
|
+
/**
|
|
430
|
+
* Sends a typed paywall/purchase journey event.
|
|
431
|
+
* Direct calls ignore `paywallEntryId`; use `createPaywallTracker(...)` for entry correlation.
|
|
432
|
+
*/
|
|
433
|
+
trackPaywallEvent(eventName: PaywallJourneyEventName, properties: PaywallEventProperties): void;
|
|
434
|
+
private sendPaywallEvent;
|
|
435
|
+
/**
|
|
436
|
+
* Sends anonymized onboarding survey responses using canonical event naming.
|
|
437
|
+
* Free text and raw numeric values are reduced to coarse buckets.
|
|
438
|
+
*/
|
|
439
|
+
trackOnboardingSurveyResponse(input: OnboardingSurveyResponseInput, eventName?: OnboardingSurveyEventName): void;
|
|
440
|
+
/**
|
|
441
|
+
* Sends a screen-view style event using the `screen:<name>` convention.
|
|
442
|
+
*/
|
|
443
|
+
screen(name: string, properties?: EventProperties): void;
|
|
444
|
+
/**
|
|
445
|
+
* Alias of `screen(...)` for web-style naming.
|
|
446
|
+
*/
|
|
447
|
+
page(name: string, properties?: EventProperties): void;
|
|
448
|
+
/**
|
|
449
|
+
* Sends a feedback event.
|
|
450
|
+
*/
|
|
451
|
+
feedback(message: string, rating?: number, properties?: EventProperties): void;
|
|
452
|
+
/**
|
|
453
|
+
* Flushes current event queue to the ingest endpoint.
|
|
454
|
+
*/
|
|
455
|
+
flush(): Promise<void>;
|
|
456
|
+
/**
|
|
457
|
+
* Stops internal timers and unload handlers.
|
|
458
|
+
*/
|
|
459
|
+
shutdown(): void;
|
|
460
|
+
private enqueue;
|
|
461
|
+
private scheduleFlush;
|
|
462
|
+
private sendWithRetry;
|
|
463
|
+
private createHttpIngestSendError;
|
|
464
|
+
private shouldRetryHttpStatus;
|
|
465
|
+
private toIngestSendError;
|
|
466
|
+
private createIngestDiagnostics;
|
|
467
|
+
private reportIngestError;
|
|
468
|
+
private parsePersistedConsent;
|
|
469
|
+
private readPersistedConsentSync;
|
|
470
|
+
private readPersistedConsentAsync;
|
|
471
|
+
private writePersistedConsent;
|
|
472
|
+
private startAutoFlush;
|
|
473
|
+
private ensureDeviceId;
|
|
474
|
+
private ensureSessionId;
|
|
475
|
+
private getSessionId;
|
|
476
|
+
private readSessionEventSeq;
|
|
477
|
+
private readSessionEventSeqAsync;
|
|
478
|
+
private parseSessionEventSeq;
|
|
479
|
+
private writeSessionEventSeq;
|
|
480
|
+
private hydrateIdentityFromStorage;
|
|
481
|
+
private shouldDeferEventsUntilHydrated;
|
|
482
|
+
private deferEventUntilHydrated;
|
|
483
|
+
private drainDeferredEventsAfterHydration;
|
|
484
|
+
private cloneProperties;
|
|
485
|
+
private detectAsyncStorageReads;
|
|
486
|
+
private withRuntimeMetadata;
|
|
487
|
+
private shouldDropOnboardingStepView;
|
|
488
|
+
private shouldDropScreenView;
|
|
489
|
+
private getScreenViewDedupeKey;
|
|
490
|
+
private getOnboardingStepViewDedupeKey;
|
|
491
|
+
private readPropertyAsString;
|
|
492
|
+
private readPropertyAsStepIndex;
|
|
493
|
+
private syncOnboardingStepViewState;
|
|
494
|
+
private hydrateOnboardingStepViewState;
|
|
495
|
+
private persistOnboardingStepViewState;
|
|
496
|
+
private parseOnboardingStepViewState;
|
|
497
|
+
private resolveIdentityTrackingModeOption;
|
|
498
|
+
private resolveConfiguredStorage;
|
|
499
|
+
private normalizeCookieMaxAgeSeconds;
|
|
500
|
+
private normalizeScreenViewDedupeWindowMs;
|
|
501
|
+
private isFullTrackingActive;
|
|
502
|
+
private applyIdentityTrackingState;
|
|
503
|
+
private getEventUserId;
|
|
504
|
+
private withEventContext;
|
|
505
|
+
private normalizeOptions;
|
|
506
|
+
private readRequiredStringOption;
|
|
507
|
+
private normalizePlatformOption;
|
|
508
|
+
private normalizeProjectSurfaceOption;
|
|
509
|
+
private log;
|
|
510
|
+
private reportMissingApiKey;
|
|
511
|
+
}
|
|
512
|
+
|
|
513
|
+
type ContextClientInput = InitInput | AnalyticsClient | null | undefined;
|
|
514
|
+
type AnalyticsContextConsentControls = {
|
|
515
|
+
get: () => boolean;
|
|
516
|
+
getState: () => AnalyticsConsentState;
|
|
517
|
+
set: (granted: boolean, options?: SetConsentOptions) => void;
|
|
518
|
+
optIn: (options?: SetConsentOptions) => void;
|
|
519
|
+
optOut: (options?: SetConsentOptions) => void;
|
|
520
|
+
setFullTracking: (granted: boolean, options?: SetConsentOptions) => void;
|
|
521
|
+
optInFullTracking: (options?: SetConsentOptions) => void;
|
|
522
|
+
optOutFullTracking: (options?: SetConsentOptions) => void;
|
|
523
|
+
isFullTrackingEnabled: () => boolean;
|
|
524
|
+
};
|
|
525
|
+
type AnalyticsContextUserControls = {
|
|
526
|
+
identify: (userId: string, traits?: EventProperties) => void;
|
|
527
|
+
set: (userId: string | null | undefined, traits?: EventProperties) => void;
|
|
528
|
+
clear: () => void;
|
|
529
|
+
};
|
|
530
|
+
type AnalyticsContext = {
|
|
531
|
+
client: AnalyticsClient;
|
|
532
|
+
onboarding: OnboardingTracker;
|
|
533
|
+
paywall: PaywallTracker | null;
|
|
534
|
+
consent: AnalyticsContextConsentControls;
|
|
535
|
+
user: AnalyticsContextUserControls;
|
|
536
|
+
track: (eventName: string, properties?: EventProperties) => void;
|
|
537
|
+
trackOnboardingEvent: (eventName: OnboardingEventName, properties?: OnboardingEventProperties) => void;
|
|
538
|
+
trackOnboardingSurveyResponse: (input: OnboardingSurveyResponseInput, eventName?: OnboardingSurveyEventName) => void;
|
|
539
|
+
trackPaywallEvent: (eventName: PaywallJourneyEventName, properties: PaywallEventProperties) => void;
|
|
540
|
+
screen: (name: string, properties?: EventProperties) => void;
|
|
541
|
+
page: (name: string, properties?: EventProperties) => void;
|
|
542
|
+
feedback: (message: string, rating?: number, properties?: EventProperties) => void;
|
|
543
|
+
setContext: (context: EventContext) => void;
|
|
544
|
+
createOnboarding: (defaults: OnboardingTrackerDefaults) => OnboardingTracker;
|
|
545
|
+
createPaywall: (defaults: PaywallTrackerDefaults) => PaywallTracker;
|
|
546
|
+
configureOnboarding: (defaults: OnboardingTrackerDefaults) => OnboardingTracker;
|
|
547
|
+
configurePaywall: (defaults: PaywallTrackerDefaults) => PaywallTracker;
|
|
548
|
+
ready: () => Promise<void>;
|
|
549
|
+
flush: () => Promise<void>;
|
|
550
|
+
shutdown: () => void;
|
|
551
|
+
};
|
|
552
|
+
type CreateAnalyticsContextOptions = {
|
|
553
|
+
/**
|
|
554
|
+
* Either an existing client instance or standard `init(...)` input.
|
|
555
|
+
*/
|
|
556
|
+
client?: ContextClientInput;
|
|
557
|
+
/**
|
|
558
|
+
* Defaults used for the exported `context.onboarding` tracker instance.
|
|
559
|
+
*/
|
|
560
|
+
onboarding?: OnboardingTrackerDefaults | null;
|
|
561
|
+
/**
|
|
562
|
+
* Optional defaults used for the exported `context.paywall` tracker instance.
|
|
563
|
+
*/
|
|
564
|
+
paywall?: PaywallTrackerDefaults | null;
|
|
565
|
+
};
|
|
566
|
+
/**
|
|
567
|
+
* Host-app friendly SDK context with low boilerplate and rich defaults.
|
|
568
|
+
* Provides pre-wired onboarding + consent/user controls and optional paywall tracker binding.
|
|
569
|
+
*/
|
|
570
|
+
declare const createAnalyticsContext: (options?: CreateAnalyticsContextOptions) => AnalyticsContext;
|
|
571
|
+
|
|
572
|
+
/**
|
|
573
|
+
* Creates a browser analytics client instance.
|
|
574
|
+
*/
|
|
575
|
+
declare const init: (input?: InitInput) => AnalyticsClient;
|
|
576
|
+
/**
|
|
577
|
+
* Creates an analytics client with consent-first defaults.
|
|
578
|
+
* Tracking stays disabled until `optIn()` / `setConsent(true)` is called.
|
|
579
|
+
*/
|
|
580
|
+
declare const initConsentFirst: (input?: InitInput) => AnalyticsClient;
|
|
581
|
+
/**
|
|
582
|
+
* Creates an analytics client and resolves once client initialization completes.
|
|
583
|
+
*/
|
|
584
|
+
declare const initAsync: (input?: InitInput) => Promise<AnalyticsClient>;
|
|
585
|
+
declare const initConsentFirstAsync: (input?: InitInput) => Promise<AnalyticsClient>;
|
|
586
|
+
|
|
587
|
+
export { AnalyticsClient, type AnalyticsClientOptions, type AnalyticsConsentState, type AnalyticsContext, type AnalyticsContextConsentControls, type AnalyticsContextUserControls, type AnalyticsIngestError, type AnalyticsIngestErrorHandler, type AnalyticsStorageAdapter, type CreateAnalyticsContextOptions, type EventContext, type EventProperties, type IdentityTrackingMode, type InitInput, type InitOptions, ONBOARDING_EVENTS, ONBOARDING_PROGRESS_EVENT_ORDER, ONBOARDING_SCREEN_EVENT_PREFIXES, ONBOARDING_SURVEY_EVENTS, type OnboardingEventName, type OnboardingEventProperties, type OnboardingStepTracker, type OnboardingSurveyAnswerType, type OnboardingSurveyEventName, type OnboardingSurveyResponseInput, type OnboardingTracker, type OnboardingTrackerDefaults, type OnboardingTrackerSurveyInput, PAYWALL_ANCHOR_EVENT_CANDIDATES, PAYWALL_EVENTS, PAYWALL_JOURNEY_EVENT_ORDER, PAYWALL_SKIP_EVENT_CANDIDATES, PURCHASE_EVENTS, PURCHASE_SUCCESS_EVENT_CANDIDATES, type PaywallEventName, type PaywallEventProperties, type PaywallJourneyEventName, type PaywallTracker, type PaywallTrackerDefaults, type PaywallTrackerProperties, type PurchaseEventName, type SetConsentOptions, createAnalyticsContext, init, initAsync, initConsentFirst, initConsentFirstAsync };
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import {
|
|
2
|
+
AnalyticsClient,
|
|
3
|
+
ONBOARDING_EVENTS,
|
|
4
|
+
ONBOARDING_PROGRESS_EVENT_ORDER,
|
|
5
|
+
ONBOARDING_SCREEN_EVENT_PREFIXES,
|
|
6
|
+
ONBOARDING_SURVEY_EVENTS,
|
|
7
|
+
PAYWALL_ANCHOR_EVENT_CANDIDATES,
|
|
8
|
+
PAYWALL_EVENTS,
|
|
9
|
+
PAYWALL_JOURNEY_EVENT_ORDER,
|
|
10
|
+
PAYWALL_SKIP_EVENT_CANDIDATES,
|
|
11
|
+
PURCHASE_EVENTS,
|
|
12
|
+
PURCHASE_SUCCESS_EVENT_CANDIDATES,
|
|
13
|
+
createAnalyticsContext,
|
|
14
|
+
init,
|
|
15
|
+
initAsync,
|
|
16
|
+
initConsentFirst,
|
|
17
|
+
initConsentFirstAsync
|
|
18
|
+
} from "./chunk-6EPJZLLK.js";
|
|
19
|
+
export {
|
|
20
|
+
AnalyticsClient,
|
|
21
|
+
ONBOARDING_EVENTS,
|
|
22
|
+
ONBOARDING_PROGRESS_EVENT_ORDER,
|
|
23
|
+
ONBOARDING_SCREEN_EVENT_PREFIXES,
|
|
24
|
+
ONBOARDING_SURVEY_EVENTS,
|
|
25
|
+
PAYWALL_ANCHOR_EVENT_CANDIDATES,
|
|
26
|
+
PAYWALL_EVENTS,
|
|
27
|
+
PAYWALL_JOURNEY_EVENT_ORDER,
|
|
28
|
+
PAYWALL_SKIP_EVENT_CANDIDATES,
|
|
29
|
+
PURCHASE_EVENTS,
|
|
30
|
+
PURCHASE_SUCCESS_EVENT_CANDIDATES,
|
|
31
|
+
createAnalyticsContext,
|
|
32
|
+
init,
|
|
33
|
+
initAsync,
|
|
34
|
+
initConsentFirst,
|
|
35
|
+
initConsentFirstAsync
|
|
36
|
+
};
|