@fire-spark/analytics 0.22.0 → 0.23.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/dist/index.d.ts +453 -8
- package/dist/index.js +2939 -1375
- package/package.json +3 -2
package/dist/index.d.ts
CHANGED
|
@@ -34,6 +34,39 @@ type BuiltinDestinationId = (typeof BUILTIN_DESTINATION_IDS)[number];
|
|
|
34
34
|
*/
|
|
35
35
|
type DestinationProviderId = BuiltinDestinationId | (string & {});
|
|
36
36
|
type AnalyticsRuntime = "web" | "react-native";
|
|
37
|
+
/**
|
|
38
|
+
* Where ads events are delivered. `client` only loads the browser pixels
|
|
39
|
+
* (today's behavior). `server` relays to `serverSide.endpoint` and never
|
|
40
|
+
* loads the pixel scripts. `hybrid` does both with the same `eventId`.
|
|
41
|
+
*/
|
|
42
|
+
type AnalyticsDeliveryMode = "client" | "server" | "hybrid";
|
|
43
|
+
/** Routes `meta`, `tiktok` and `google-ads` through a server relay. */
|
|
44
|
+
interface AnalyticsServerSideOptions {
|
|
45
|
+
/** `"/api/track"` (same-origin path) or an `https:` URL. */
|
|
46
|
+
endpoint?: string;
|
|
47
|
+
/**
|
|
48
|
+
* Ads providers routed through the server. Default: the configured ads
|
|
49
|
+
* adapters among `["meta","tiktok","google-ads"]`.
|
|
50
|
+
*/
|
|
51
|
+
providers?: ServerProviderId[];
|
|
52
|
+
/** Events per relay request, 1 to 20. Default 10. */
|
|
53
|
+
batchSize?: number;
|
|
54
|
+
/** Batch delay in ms. Default 0. A purchase always flushes at once. */
|
|
55
|
+
flushIntervalMs?: number;
|
|
56
|
+
/** Extra non-secret request headers (for example a CSRF token). */
|
|
57
|
+
headers?: Record<string, string>;
|
|
58
|
+
}
|
|
59
|
+
type AnalyticsConfigErrorCode = "ANALYTICS_SERVER_ENDPOINT_REQUIRED" | "ANALYTICS_SERVER_MODE_UNSUPPORTED_RUNTIME" | "ANALYTICS_INVALID_ENDPOINT" | "ANALYTICS_INVALID_MODE";
|
|
60
|
+
/**
|
|
61
|
+
* Thrown by `resolveDeliveryMode()` for an invalid `mode` / `serverSide`.
|
|
62
|
+
* In development `configure()` lets it throw; in production (`env:
|
|
63
|
+
* "production"`) it is caught, reported through `onWarning` and the client
|
|
64
|
+
* falls back to `mode: "client"` so the storefront never crashes.
|
|
65
|
+
*/
|
|
66
|
+
declare class AnalyticsConfigError extends Error {
|
|
67
|
+
readonly code: AnalyticsConfigErrorCode;
|
|
68
|
+
constructor(code: AnalyticsConfigErrorCode, message: string);
|
|
69
|
+
}
|
|
37
70
|
/** Gate declared by a custom destination. */
|
|
38
71
|
type AnalyticsConsentCategory = "analytics" | "ads";
|
|
39
72
|
/**
|
|
@@ -50,7 +83,7 @@ type AnalyticsUser = {
|
|
|
50
83
|
id?: string | null;
|
|
51
84
|
properties?: Record<string, string | number | boolean | null>;
|
|
52
85
|
};
|
|
53
|
-
type AnalyticsIssueSource = "configure" | "destination" | "ingest" | "sample" | "track" | "hash";
|
|
86
|
+
type AnalyticsIssueSource = "configure" | "destination" | "ingest" | "relay" | "sample" | "track" | "hash";
|
|
54
87
|
/** Problem the SDK hit without throwing to the caller. */
|
|
55
88
|
type AnalyticsIssue = {
|
|
56
89
|
level: "error" | "warning";
|
|
@@ -62,6 +95,47 @@ type AnalyticsIssue = {
|
|
|
62
95
|
};
|
|
63
96
|
/** Host hash for PII. Must return the lowercase hex SHA-256 of `value`. */
|
|
64
97
|
type AnalyticsHash = (value: string) => string | Promise<string>;
|
|
98
|
+
/** How a hashed `phone` param is written before hashing. */
|
|
99
|
+
type PhoneHashFormat = "e164" | "digits";
|
|
100
|
+
/** Raw personal data for `hashUserData()`. Every field is optional. */
|
|
101
|
+
interface UserDataInput {
|
|
102
|
+
email?: string;
|
|
103
|
+
phone?: string;
|
|
104
|
+
firstName?: string;
|
|
105
|
+
lastName?: string;
|
|
106
|
+
/** Your user id. Hashed the same way as the `external_id` of the pixels. */
|
|
107
|
+
externalId?: string;
|
|
108
|
+
/** ISO 3166-1 alpha-2 of the user. Returned uppercase, never hashed. */
|
|
109
|
+
countryCode?: string;
|
|
110
|
+
}
|
|
111
|
+
interface HashUserDataOptions {
|
|
112
|
+
/** ISO 3166-1 alpha-2 for phones typed without a country code. */
|
|
113
|
+
defaultCountry?: string;
|
|
114
|
+
/** Defaults to `sha256Hex`. */
|
|
115
|
+
hash?: AnalyticsHash;
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* SHA-256 (lowercase hex) of each normalized field. A field that is missing
|
|
119
|
+
* or invalid (for example a phone that is not a real number) is omitted.
|
|
120
|
+
*/
|
|
121
|
+
interface HashedUserData {
|
|
122
|
+
/** `normalizeEmail`: Meta `em`, TikTok `email`. */
|
|
123
|
+
emailSha256?: string;
|
|
124
|
+
/** `normalizeEmailForGoogle`: Google `emailAddress`. */
|
|
125
|
+
emailGoogleSha256?: string;
|
|
126
|
+
/** E.164 with `+`: TikTok `phone`, Google `phoneNumber`. */
|
|
127
|
+
phoneE164Sha256?: string;
|
|
128
|
+
/** E.164 digits without `+`: Meta `ph`. */
|
|
129
|
+
phoneDigitsSha256?: string;
|
|
130
|
+
/** `normalizeExternalId`: Meta and TikTok `external_id`. */
|
|
131
|
+
externalIdSha256?: string;
|
|
132
|
+
/** `normalizeName`: Meta `fn`. */
|
|
133
|
+
firstNameSha256?: string;
|
|
134
|
+
/** `normalizeName`: Meta `ln`. */
|
|
135
|
+
lastNameSha256?: string;
|
|
136
|
+
/** ISO 3166-1 alpha-2, uppercase, not hashed. */
|
|
137
|
+
countryCode?: string;
|
|
138
|
+
}
|
|
65
139
|
/** Subset of React Native `AppState`. */
|
|
66
140
|
type AnalyticsAppState = {
|
|
67
141
|
addEventListener: (type: "change", listener: (state: string) => void) => {
|
|
@@ -82,9 +156,16 @@ type NormalizedEvent = {
|
|
|
82
156
|
context: Record<string, unknown>;
|
|
83
157
|
runtime: AnalyticsRuntime;
|
|
84
158
|
consent: AnalyticsConsent;
|
|
85
|
-
/**
|
|
159
|
+
/**
|
|
160
|
+
* Same id for every destination of one `track()`, for deduplication. A
|
|
161
|
+
* `purchase` with an `order_id` uses `purchase:<order_id>`.
|
|
162
|
+
*/
|
|
86
163
|
eventId?: string;
|
|
87
|
-
/**
|
|
164
|
+
/**
|
|
165
|
+
* Hashed advanced-matching fields. Meta: `em`, `ph` (E.164 digits without
|
|
166
|
+
* `+`), `external_id`. TikTok: `email`, `phone_number` (E.164 with `+`),
|
|
167
|
+
* `external_id`.
|
|
168
|
+
*/
|
|
88
169
|
userData?: Record<string, string>;
|
|
89
170
|
/** Meta app events `valueToSum` (react-native). */
|
|
90
171
|
valueToSum?: number;
|
|
@@ -114,8 +195,9 @@ interface CustomDestinationIdentity {
|
|
|
114
195
|
}
|
|
115
196
|
/**
|
|
116
197
|
* Raw tracked event passed to a custom `map`. Catalog renames are not
|
|
117
|
-
* applied. `
|
|
118
|
-
* `
|
|
198
|
+
* applied. With `consent: "ads"`, `email` and `phone` (E.164 with `+`) in
|
|
199
|
+
* `properties` and `items` are already hashed, an invalid one is omitted,
|
|
200
|
+
* and `device_ip` and `ttclid` stay raw.
|
|
119
201
|
*/
|
|
120
202
|
interface CustomDestinationInput {
|
|
121
203
|
name: string;
|
|
@@ -123,6 +205,7 @@ interface CustomDestinationInput {
|
|
|
123
205
|
items?: Array<Record<string, unknown>>;
|
|
124
206
|
/** ISO 4217 for this event, or the merchant currency. */
|
|
125
207
|
currency?: string;
|
|
208
|
+
/** `purchase:<order_id>` for a purchase with an `order_id`. */
|
|
126
209
|
eventId: string;
|
|
127
210
|
/** Unix seconds. */
|
|
128
211
|
eventTime: number;
|
|
@@ -268,9 +351,15 @@ type AnalyticsConfigureOptions = {
|
|
|
268
351
|
/**
|
|
269
352
|
* SHA-256 for PII sent to Meta, TikTok and custom `ads` destinations.
|
|
270
353
|
* Defaults to `crypto.subtle`, or a built-in implementation when it is
|
|
271
|
-
* missing (Hermes, insecure web).
|
|
354
|
+
* missing (Hermes, insecure web). It receives the normalized value.
|
|
272
355
|
*/
|
|
273
356
|
hash?: AnalyticsHash;
|
|
357
|
+
/**
|
|
358
|
+
* ISO 3166-1 alpha-2 used to read a `phone` typed without a country code
|
|
359
|
+
* (for example `"EC"`). Without it, the merchant country from preferences
|
|
360
|
+
* is used. An invalid code is reported and ignored.
|
|
361
|
+
*/
|
|
362
|
+
defaultCountry?: string;
|
|
274
363
|
/** Send the queue once it holds this many events. Default 20. */
|
|
275
364
|
flushAt?: number;
|
|
276
365
|
/** Send the queue this long after an event is queued. 0 disables. */
|
|
@@ -282,6 +371,14 @@ type AnalyticsConfigureOptions = {
|
|
|
282
371
|
flushOnHide?: boolean;
|
|
283
372
|
/** React Native `AppState`: the queue is sent when the app backgrounds. */
|
|
284
373
|
appState?: AnalyticsAppState;
|
|
374
|
+
/**
|
|
375
|
+
* Delivery mode for the ads providers. Omitted resolves automatically: an
|
|
376
|
+
* endpoint ⇒ `hybrid` on web, no endpoint ⇒ `client`. See
|
|
377
|
+
* `resolveDeliveryMode`.
|
|
378
|
+
*/
|
|
379
|
+
mode?: AnalyticsDeliveryMode;
|
|
380
|
+
/** Server relay for `meta`, `tiktok` and `google-ads`. */
|
|
381
|
+
serverSide?: AnalyticsServerSideOptions;
|
|
285
382
|
};
|
|
286
383
|
type AnalyticsConfig = {
|
|
287
384
|
session: {
|
|
@@ -293,6 +390,208 @@ type AnalyticsConfig = {
|
|
|
293
390
|
declare const isFunnelEventName: (name: string) => name is FunnelEventName;
|
|
294
391
|
declare const isInteractionEventName: (name: string) => name is InteractionEventName;
|
|
295
392
|
//#endregion
|
|
393
|
+
//#region src/contract.types.d.ts
|
|
394
|
+
/** `"12.50"`: matches `/^-?\d+(\.\d+)?$/`, read with Big.js, never rounded. */
|
|
395
|
+
type DecimalString = string;
|
|
396
|
+
/** Lowercase hex SHA-256 (64 characters). */
|
|
397
|
+
type Sha256Hex = string;
|
|
398
|
+
/** Ads platforms the server relays to. Other destinations stay client-side. */
|
|
399
|
+
type ServerProviderId = "meta" | "tiktok" | "google-ads";
|
|
400
|
+
interface TrackingSdkV1 {
|
|
401
|
+
name: string;
|
|
402
|
+
version: string;
|
|
403
|
+
}
|
|
404
|
+
/**
|
|
405
|
+
* Body of `POST {serverSide.endpoint}`, contract version 1. Every wire
|
|
406
|
+
* field is snake_case; the builder maps the camelCase inputs to it.
|
|
407
|
+
*/
|
|
408
|
+
interface TrackingEnvelopeV1 {
|
|
409
|
+
v: 1;
|
|
410
|
+
sdk: TrackingSdkV1;
|
|
411
|
+
/** ISO 8601 time the envelope was built. */
|
|
412
|
+
sent_at: string;
|
|
413
|
+
/** 1 to 20 events. */
|
|
414
|
+
events: TrackingEventV1[];
|
|
415
|
+
}
|
|
416
|
+
interface TrackingContextV1 {
|
|
417
|
+
runtime: "web";
|
|
418
|
+
/** BCP 47, for example `es-EC`. */
|
|
419
|
+
locale?: string;
|
|
420
|
+
channel_id: string;
|
|
421
|
+
store_id?: string;
|
|
422
|
+
brand_id?: string;
|
|
423
|
+
fulfillment_id?: string;
|
|
424
|
+
}
|
|
425
|
+
/** Input of `buildTrackingEvent()`; sent as `TrackingContextV1`. */
|
|
426
|
+
interface TrackingContext {
|
|
427
|
+
runtime: "web";
|
|
428
|
+
locale?: string;
|
|
429
|
+
channelId: string;
|
|
430
|
+
storeId?: string;
|
|
431
|
+
brandId?: string;
|
|
432
|
+
fulfillmentId?: string;
|
|
433
|
+
}
|
|
434
|
+
interface TrackingEventV1 {
|
|
435
|
+
/** 1 to 64 of `[A-Za-z0-9:_.-]`. The same id the browser pixels get. */
|
|
436
|
+
event_id: string;
|
|
437
|
+
/** Fire Spark tracked name, for example `purchase`. */
|
|
438
|
+
name: string;
|
|
439
|
+
/** Epoch milliseconds when `track()` was called. */
|
|
440
|
+
timestamp: number;
|
|
441
|
+
/** Page URL (`https:`). */
|
|
442
|
+
source_url: string;
|
|
443
|
+
referrer_url?: string;
|
|
444
|
+
/** Tracked params without personal data, `items`, `value` and `currency`. */
|
|
445
|
+
properties: Record<string, unknown>;
|
|
446
|
+
/** ISO 4217, uppercase. */
|
|
447
|
+
currency?: string;
|
|
448
|
+
value?: DecimalString;
|
|
449
|
+
items?: TrackingItemV1[];
|
|
450
|
+
order_id?: string;
|
|
451
|
+
user: HashedUserDataV1;
|
|
452
|
+
click_ids: ClickIdsV1;
|
|
453
|
+
consent: ConsentV1;
|
|
454
|
+
providers: ServerProviderId[];
|
|
455
|
+
context: TrackingContextV1;
|
|
456
|
+
}
|
|
457
|
+
interface TrackingItemV1 {
|
|
458
|
+
id: string;
|
|
459
|
+
name?: string;
|
|
460
|
+
category?: string;
|
|
461
|
+
brand?: string;
|
|
462
|
+
/** Unit price. */
|
|
463
|
+
price?: DecimalString;
|
|
464
|
+
quantity?: DecimalString;
|
|
465
|
+
}
|
|
466
|
+
/** `hashUserData()` output on the wire: lowercase hex SHA-256 values. */
|
|
467
|
+
interface HashedUserDataV1 {
|
|
468
|
+
email_sha256?: Sha256Hex;
|
|
469
|
+
email_google_sha256?: Sha256Hex;
|
|
470
|
+
phone_e164_sha256?: Sha256Hex;
|
|
471
|
+
phone_digits_sha256?: Sha256Hex;
|
|
472
|
+
external_id_sha256?: Sha256Hex;
|
|
473
|
+
first_name_sha256?: Sha256Hex;
|
|
474
|
+
last_name_sha256?: Sha256Hex;
|
|
475
|
+
/** ISO 3166-1 alpha-2, uppercase. Not hashed. */
|
|
476
|
+
country_code?: string;
|
|
477
|
+
}
|
|
478
|
+
/** Ad click identifiers on the wire, raw (the ads APIs reject hashes). */
|
|
479
|
+
interface ClickIdsV1 {
|
|
480
|
+
fbp?: string;
|
|
481
|
+
fbc?: string;
|
|
482
|
+
ttclid?: string;
|
|
483
|
+
ttp?: string;
|
|
484
|
+
gclid?: string;
|
|
485
|
+
gbraid?: string;
|
|
486
|
+
wbraid?: string;
|
|
487
|
+
google_session_attributes?: string;
|
|
488
|
+
}
|
|
489
|
+
/** What `captureClickIds()` returns; sent as `ClickIdsV1`. */
|
|
490
|
+
interface ClickIds {
|
|
491
|
+
/** Meta `_fbp`: `fb.<subdomainIndex>.<creationTimeMs>.<random>`. */
|
|
492
|
+
fbp?: string;
|
|
493
|
+
/** Meta `_fbc`: `fb.<subdomainIndex>.<creationTimeMs>.<fbclid>`. */
|
|
494
|
+
fbc?: string;
|
|
495
|
+
ttclid?: string;
|
|
496
|
+
/** TikTok `_ttp` cookie. */
|
|
497
|
+
ttp?: string;
|
|
498
|
+
gclid?: string;
|
|
499
|
+
gbraid?: string;
|
|
500
|
+
wbraid?: string;
|
|
501
|
+
/** Google session attributes (base64), passed in by the merchant. */
|
|
502
|
+
googleSessionAttributes?: string;
|
|
503
|
+
}
|
|
504
|
+
interface ConsentV1 {
|
|
505
|
+
ads: boolean;
|
|
506
|
+
/** Google `ad_user_data`. Defaults to `ads`. */
|
|
507
|
+
ad_user_data?: boolean;
|
|
508
|
+
/** Google `ad_personalization`. Defaults to `ads`. */
|
|
509
|
+
ad_personalization?: boolean;
|
|
510
|
+
}
|
|
511
|
+
/** Input of `buildTrackingEvent()`; sent as `ConsentV1`. */
|
|
512
|
+
interface TrackingConsent {
|
|
513
|
+
ads: boolean;
|
|
514
|
+
/** Google `adUserData`. Defaults to `ads`. */
|
|
515
|
+
adUserData?: boolean;
|
|
516
|
+
/** Google `adPersonalization`. Defaults to `ads`. */
|
|
517
|
+
adPersonalization?: boolean;
|
|
518
|
+
}
|
|
519
|
+
type EnvelopeError = "invalid_json" | "invalid_envelope" | "unsupported_contract_version";
|
|
520
|
+
type RejectReason = "invalid_event" | "invalid_event_id" | "invalid_name" | "event_too_old" | "event_in_future" | "invalid_source_url" | "origin_not_allowed" | "invalid_hash" | "invalid_decimal" | "invalid_currency" | "unknown_provider";
|
|
521
|
+
/** One entry of the relay's `rejected` list. */
|
|
522
|
+
interface RejectedEvent {
|
|
523
|
+
event_id?: string;
|
|
524
|
+
reason: RejectReason;
|
|
525
|
+
}
|
|
526
|
+
type EnvelopeValidation = {
|
|
527
|
+
ok: true;
|
|
528
|
+
envelope: TrackingEnvelopeV1;
|
|
529
|
+
rejected: RejectedEvent[];
|
|
530
|
+
} | {
|
|
531
|
+
ok: false;
|
|
532
|
+
error: EnvelopeError;
|
|
533
|
+
};
|
|
534
|
+
interface ValidateEnvelopeOptions {
|
|
535
|
+
/** Epoch ms used for the timestamp window. Defaults to `Date.now()`. */
|
|
536
|
+
now?: number;
|
|
537
|
+
/**
|
|
538
|
+
* Origins (`https://shop.example.com`) a `source_url` may come from.
|
|
539
|
+
* Omitted: any `https:` origin is accepted.
|
|
540
|
+
*/
|
|
541
|
+
allowedOrigins?: readonly string[];
|
|
542
|
+
/** Providers the server has configured. Defaults to all of them. */
|
|
543
|
+
providers?: readonly ServerProviderId[];
|
|
544
|
+
/** Accept `http://localhost` source URLs (local development only). */
|
|
545
|
+
allowLocalhost?: boolean;
|
|
546
|
+
}
|
|
547
|
+
/** Input of `buildTrackingEvent()`. */
|
|
548
|
+
interface TrackingEventInput {
|
|
549
|
+
eventId: string;
|
|
550
|
+
name: string;
|
|
551
|
+
/** Epoch ms when `track()` was called. */
|
|
552
|
+
timestamp: number;
|
|
553
|
+
sourceUrl: string;
|
|
554
|
+
referrerUrl?: string;
|
|
555
|
+
/** Raw tracked params. Personal data is removed, never copied. */
|
|
556
|
+
properties?: Record<string, unknown>;
|
|
557
|
+
/** Merchant ISO 4217 code. A valid `properties.currency` wins. */
|
|
558
|
+
currency?: string;
|
|
559
|
+
/** From `hashUserData()`. */
|
|
560
|
+
user?: HashedUserData;
|
|
561
|
+
/** From `captureClickIds()`. */
|
|
562
|
+
clickIds?: ClickIds;
|
|
563
|
+
consent: TrackingConsent;
|
|
564
|
+
providers: ServerProviderId[];
|
|
565
|
+
context: TrackingContext;
|
|
566
|
+
}
|
|
567
|
+
interface ClickIdCaptureOptions {
|
|
568
|
+
/** Nothing is read or stored without ads consent. */
|
|
569
|
+
consent: {
|
|
570
|
+
ads: boolean;
|
|
571
|
+
};
|
|
572
|
+
/** Page URL. Defaults to `location.href`. */
|
|
573
|
+
url?: string;
|
|
574
|
+
/** Cookie string. Defaults to `document.cookie`. */
|
|
575
|
+
cookie?: string;
|
|
576
|
+
/**
|
|
577
|
+
* Keeps click ids from the landing URL for 90 days under `fs_ck_*` keys
|
|
578
|
+
* (for example `localStorage`). Omitted: nothing is stored.
|
|
579
|
+
*/
|
|
580
|
+
storage?: AnalyticsStorage;
|
|
581
|
+
/** Epoch ms. Defaults to `Date.now()`. */
|
|
582
|
+
now?: number;
|
|
583
|
+
/** Google session attributes from Google's capture snippet. */
|
|
584
|
+
googleSessionAttributes?: string;
|
|
585
|
+
}
|
|
586
|
+
interface BuildEnvelopeOptions {
|
|
587
|
+
/** Epoch ms for `sent_at`. Defaults to `Date.now()`. */
|
|
588
|
+
now?: number;
|
|
589
|
+
}
|
|
590
|
+
//#endregion
|
|
591
|
+
//#region src/mode.d.ts
|
|
592
|
+
/** The resolved delivery mode. Throws `AnalyticsConfigError` when invalid. */
|
|
593
|
+
declare const resolveDeliveryMode: (options: AnalyticsConfigureOptions) => AnalyticsDeliveryMode;
|
|
594
|
+
//#endregion
|
|
296
595
|
//#region src/flush.d.ts
|
|
297
596
|
/** Sends the default instance queue to Fire Spark. */
|
|
298
597
|
declare const flush: () => Promise<void>;
|
|
@@ -382,7 +681,7 @@ declare const customAdapter: (options: CustomAdapterOptions) => CustomAnalyticsA
|
|
|
382
681
|
//#endregion
|
|
383
682
|
//#region src/version.d.ts
|
|
384
683
|
/** Kept equal to package.json by `pnpm sdk:release` (see version.test.ts). */
|
|
385
|
-
declare const SDK_VERSION = "0.
|
|
684
|
+
declare const SDK_VERSION = "0.23.0";
|
|
386
685
|
//#endregion
|
|
387
686
|
//#region src/compact.d.ts
|
|
388
687
|
/** Drops `undefined`, `null`, non-finite numbers and functions, deeply. */
|
|
@@ -400,6 +699,152 @@ declare const hasScript: (prefix: string, exceptId?: string) => boolean;
|
|
|
400
699
|
*/
|
|
401
700
|
declare const loadScript: (src: string, id: string) => Promise<void> | null;
|
|
402
701
|
//#endregion
|
|
702
|
+
//#region src/normalize.d.ts
|
|
703
|
+
/**
|
|
704
|
+
* Lowercase hex SHA-256 of the UTF-8 bytes of `value`: `crypto.subtle`
|
|
705
|
+
* when available, else a built-in implementation (Hermes, insecure web).
|
|
706
|
+
*/
|
|
707
|
+
declare const sha256Hex: AnalyticsHash;
|
|
708
|
+
/** Meta and TikTok: trim and lowercase. Not an email → `undefined`. */
|
|
709
|
+
declare const normalizeEmail: (value: string) => string | undefined;
|
|
710
|
+
/**
|
|
711
|
+
* Google only: removes every whitespace and lowercases. For `gmail.com`
|
|
712
|
+
* and `googlemail.com` it also drops the dots and any `+tag` of the local
|
|
713
|
+
* part. Never use it for Meta or TikTok.
|
|
714
|
+
*/
|
|
715
|
+
declare const normalizeEmailForGoogle: (value: string) => string | undefined;
|
|
716
|
+
/** ISO 3166-1 alpha-2, uppercase. Anything else → `undefined`. */
|
|
717
|
+
declare const normalizeCountryCode: (value: unknown) => string | undefined;
|
|
718
|
+
/**
|
|
719
|
+
* E.164 with `+` (`+593991234567`). A number without a country code is
|
|
720
|
+
* read in `defaultCountry`. A value that is not a valid phone number →
|
|
721
|
+
* `undefined`: omit it, never hash it.
|
|
722
|
+
*/
|
|
723
|
+
declare const normalizePhoneE164: (value: string, defaultCountry?: string) => Promise<string | undefined>;
|
|
724
|
+
/** Meta `ph`: the E.164 digits without `+`. Not E.164 → `undefined`. */
|
|
725
|
+
declare const phoneDigits: (e164: string) => string | undefined;
|
|
726
|
+
/**
|
|
727
|
+
* Meta `fn` / `ln`: lowercase, without punctuation, digits or symbols.
|
|
728
|
+
* Letters keep their accents (UTF-8); inner spaces collapse to one.
|
|
729
|
+
*/
|
|
730
|
+
declare const normalizeName: (value: string) => string | undefined;
|
|
731
|
+
/** `external_id`: trim and lowercase, as the user id always was. */
|
|
732
|
+
declare const normalizeExternalId: (value: string) => string | undefined;
|
|
733
|
+
/**
|
|
734
|
+
* Normalizes and hashes each field the way each ads platform expects. One
|
|
735
|
+
* email gives two hashes: `emailSha256` (Meta, TikTok) and
|
|
736
|
+
* `emailGoogleSha256` (Google). One phone gives `phoneE164Sha256` (TikTok,
|
|
737
|
+
* Google) and `phoneDigitsSha256` (Meta).
|
|
738
|
+
*/
|
|
739
|
+
declare const hashUserData: (input: UserDataInput, options?: HashUserDataOptions) => Promise<HashedUserData>;
|
|
740
|
+
//#endregion
|
|
741
|
+
//#region src/contract.d.ts
|
|
742
|
+
declare const TRACKING_CONTRACT_VERSION: 1;
|
|
743
|
+
/** Versions a server accepts: the current one and the one before. */
|
|
744
|
+
declare const SUPPORTED_CONTRACT_VERSIONS: readonly [1];
|
|
745
|
+
declare const SERVER_PROVIDER_IDS: readonly ["meta", "tiktok", "google-ads"];
|
|
746
|
+
declare const TRACKING_SDK_NAME = "@fire-spark/analytics";
|
|
747
|
+
declare const MAX_ENVELOPE_EVENTS = 20;
|
|
748
|
+
/** Params never copied into a contract event (raw personal data). */
|
|
749
|
+
declare const CONTRACT_PII_KEYS: readonly ["email", "phone", "first_name", "last_name", "device_ip", "ttclid"];
|
|
750
|
+
/** `hashUserData()` field → its snake_case wire name. */
|
|
751
|
+
declare const HASHED_USER_WIRE_KEYS: {
|
|
752
|
+
readonly emailSha256: "email_sha256";
|
|
753
|
+
readonly emailGoogleSha256: "email_google_sha256";
|
|
754
|
+
readonly phoneE164Sha256: "phone_e164_sha256";
|
|
755
|
+
readonly phoneDigitsSha256: "phone_digits_sha256";
|
|
756
|
+
readonly externalIdSha256: "external_id_sha256";
|
|
757
|
+
readonly firstNameSha256: "first_name_sha256";
|
|
758
|
+
readonly lastNameSha256: "last_name_sha256";
|
|
759
|
+
};
|
|
760
|
+
/** `captureClickIds()` field → its snake_case wire name. */
|
|
761
|
+
declare const CLICK_ID_WIRE_KEYS: {
|
|
762
|
+
readonly fbp: "fbp";
|
|
763
|
+
readonly fbc: "fbc";
|
|
764
|
+
readonly ttclid: "ttclid";
|
|
765
|
+
readonly ttp: "ttp";
|
|
766
|
+
readonly gclid: "gclid";
|
|
767
|
+
readonly gbraid: "gbraid";
|
|
768
|
+
readonly wbraid: "wbraid";
|
|
769
|
+
readonly googleSessionAttributes: "google_session_attributes";
|
|
770
|
+
};
|
|
771
|
+
/** 1 to 64 of `[A-Za-z0-9:_.-]`. */
|
|
772
|
+
declare const isValidEventId: (value: unknown) => value is string;
|
|
773
|
+
/**
|
|
774
|
+
* `purchase:<order_id>`: the event id every destination (Meta pixel,
|
|
775
|
+
* TikTok pixel, the server relay) gets for a purchase, so a reloaded
|
|
776
|
+
* confirmation page is deduplicated instead of counted twice. Returns
|
|
777
|
+
* `undefined` when there is no order id or the result is not a valid
|
|
778
|
+
* event id (longer than 64 characters or with other characters).
|
|
779
|
+
*/
|
|
780
|
+
declare const purchaseEventId: (orderId: unknown) => string | undefined;
|
|
781
|
+
declare const isDecimalString: (value: unknown) => value is DecimalString;
|
|
782
|
+
/**
|
|
783
|
+
* Money as a decimal string, never rounded. A decimal string is kept as
|
|
784
|
+
* written (`"25.90"` stays `"25.90"`); a finite number keeps every digit
|
|
785
|
+
* of its shortest representation (`25.9` → `"25.9"`).
|
|
786
|
+
*/
|
|
787
|
+
declare const toDecimalString: (value: unknown) => string | undefined;
|
|
788
|
+
/**
|
|
789
|
+
* One contract v1 event from a tracked event. Personal params are
|
|
790
|
+
* dropped (pass hashed user data in `user`), money becomes decimal
|
|
791
|
+
* strings without rounding, and `items` / `value` / `currency` follow the
|
|
792
|
+
* same rules as the browser pixels.
|
|
793
|
+
*/
|
|
794
|
+
declare const buildTrackingEvent: (input: TrackingEventInput) => TrackingEventV1;
|
|
795
|
+
/** Wraps 1 to 20 events in a contract v1 envelope. */
|
|
796
|
+
declare const buildTrackingEnvelope: (events: TrackingEventV1[], options?: BuildEnvelopeOptions) => TrackingEnvelopeV1;
|
|
797
|
+
//#endregion
|
|
798
|
+
//#region src/contract.validate.d.ts
|
|
799
|
+
/**
|
|
800
|
+
* Brings an envelope of a supported older version to the current one.
|
|
801
|
+
* Version 1 is current, so it is returned as is.
|
|
802
|
+
*/
|
|
803
|
+
declare const upgradeEnvelope: (envelope: Record<string, unknown>) => Record<string, unknown>;
|
|
804
|
+
/**
|
|
805
|
+
* Validates a relay body (a JSON string or a parsed value). A malformed
|
|
806
|
+
* body or an unsupported `v` fails as a whole; otherwise every event is
|
|
807
|
+
* checked on its own and the invalid ones are listed in `rejected`. The
|
|
808
|
+
* returned envelope is a clean copy: unknown fields and personal params
|
|
809
|
+
* (`email`, `phone`, `first_name`, `last_name`, `device_ip`, `ttclid`) are
|
|
810
|
+
* dropped, and `consent.ad_user_data` / `ad_personalization` default to
|
|
811
|
+
* `ads`. Field names are snake_case, as on the wire.
|
|
812
|
+
*/
|
|
813
|
+
declare const validateEnvelope: (input: unknown, options?: ValidateEnvelopeOptions) => EnvelopeValidation;
|
|
814
|
+
//#endregion
|
|
815
|
+
//#region src/click-ids.d.ts
|
|
816
|
+
declare const CLICK_ID_STORAGE_PREFIX = "fs_ck_";
|
|
817
|
+
/** Click ids from a landing URL are kept for 90 days. */
|
|
818
|
+
declare const CLICK_ID_TTL_MS: number;
|
|
819
|
+
/** Value of cookie `name` in a `document.cookie` string. */
|
|
820
|
+
declare const readCookie: (cookie: string, name: string) => string | undefined;
|
|
821
|
+
/**
|
|
822
|
+
* Meta `fbc` from a `fbclid` URL param:
|
|
823
|
+
* `fb.<subdomainIndex>.<creationTimeMs>.<fbclid>`. The fbclid keeps its
|
|
824
|
+
* case.
|
|
825
|
+
*/
|
|
826
|
+
declare const fbcFromFbclid: (fbclid: string, creationTimeMs: number, subdomainIndex?: number) => string;
|
|
827
|
+
/** The gclid inside a Google `_gcl_aw` cookie (`GCL.<time>.<gclid>`). */
|
|
828
|
+
declare const gclidFromGclAw: (value: string) => string | undefined;
|
|
829
|
+
/** `fbclid`, `ttclid`, `gclid`, `gbraid` and `wbraid` of a URL. */
|
|
830
|
+
declare const parseClickIdParams: (url: string) => Partial<Record<"fbclid" | "gbraid" | "gclid" | "ttclid" | "wbraid", string>>;
|
|
831
|
+
/**
|
|
832
|
+
* Reads ad click ids for the server relay. Without ads consent it returns
|
|
833
|
+
* `{}` and reads or writes nothing.
|
|
834
|
+
*
|
|
835
|
+
* - `fbc`: a `fbclid` in the URL, else the `_fbc` cookie, else storage.
|
|
836
|
+
* - `fbp`: the `_fbp` cookie set by the Meta pixel.
|
|
837
|
+
* - `ttclid`, `gbraid`, `wbraid`: the URL, else storage.
|
|
838
|
+
* - `ttp`: the `_ttp` cookie set by the TikTok pixel (read only).
|
|
839
|
+
* - `gclid`: the URL, else the `_gcl_aw` cookie, else storage.
|
|
840
|
+
*
|
|
841
|
+
* With `storage`, ids found in the URL are kept for 90 days under
|
|
842
|
+
* `fs_ck_*` keys so a later page (the checkout) still has them.
|
|
843
|
+
*/
|
|
844
|
+
declare const captureClickIds: (options: ClickIdCaptureOptions) => Promise<ClickIds>;
|
|
845
|
+
/** Removes the `fs_ck_*` entries, for example when ads consent is revoked. */
|
|
846
|
+
declare const clearClickIds: (storage: AnalyticsStorage) => Promise<void>;
|
|
847
|
+
//#endregion
|
|
403
848
|
//#region src/index.d.ts
|
|
404
849
|
type TrackName = (name: string, params?: Record<string, unknown>, opts?: TrackOptions) => Promise<void>;
|
|
405
850
|
type TrackAlias = (event: TrackEvent) => Promise<void>;
|
|
@@ -447,4 +892,4 @@ declare const analytics: {
|
|
|
447
892
|
setConsent: typeof setConsent;
|
|
448
893
|
};
|
|
449
894
|
//#endregion
|
|
450
|
-
export { Analytics, type AnalyticsAdapter, type AnalyticsAppState, type AnalyticsConfig, type AnalyticsConfigureOptions, type AnalyticsConsent, type AnalyticsConsentCategory, type AnalyticsContext, type AnalyticsCustomer, type AnalyticsDestination, type AnalyticsHash, type AnalyticsIssue, type AnalyticsIssueSource, type AnalyticsPlatform, type AnalyticsRuntime, type AnalyticsSampleOptions, type AnalyticsScope, type AnalyticsStorage, type AnalyticsUser, BUILTIN_DESTINATION_IDS, type BuiltinDestinationId, type CustomAdapterOptions, type CustomAnalyticsAdapter, type CustomDestinationEvent, type CustomDestinationIdentity, type CustomDestinationInput, type CustomDestinationMap, type CustomRevenue, 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, customAdapter, endSession, flush, hasScript, isFunnelEventName, isInteractionEventName, loadScript, reset, setConsent, setUser, track };
|
|
895
|
+
export { Analytics, type AnalyticsAdapter, type AnalyticsAppState, type AnalyticsConfig, AnalyticsConfigError, type AnalyticsConfigErrorCode, type AnalyticsConfigureOptions, type AnalyticsConsent, type AnalyticsConsentCategory, type AnalyticsContext, type AnalyticsCustomer, type AnalyticsDeliveryMode, type AnalyticsDestination, type AnalyticsHash, type AnalyticsIssue, type AnalyticsIssueSource, type AnalyticsPlatform, type AnalyticsRuntime, type AnalyticsSampleOptions, type AnalyticsScope, type AnalyticsServerSideOptions, type AnalyticsStorage, type AnalyticsUser, BUILTIN_DESTINATION_IDS, type BuildEnvelopeOptions, type BuiltinDestinationId, CLICK_ID_STORAGE_PREFIX, CLICK_ID_TTL_MS, CLICK_ID_WIRE_KEYS, CONTRACT_PII_KEYS, type ClickIdCaptureOptions, type ClickIds, type ClickIdsV1, type ConsentV1, type CustomAdapterOptions, type CustomAnalyticsAdapter, type CustomDestinationEvent, type CustomDestinationIdentity, type CustomDestinationInput, type CustomDestinationMap, type CustomRevenue, type DecimalString, type DestinationProviderId, type EnvelopeError, type EnvelopeValidation, FUNNEL_EVENTS, type FunnelEventName, HASHED_USER_WIRE_KEYS, type HashUserDataOptions, type HashedUserData, type HashedUserDataV1, INTERACTION_EVENTS, type InteractionEventName, MAX_ENVELOPE_EVENTS, type NormalizedEvent, type PhoneHashFormat, type RejectReason, type RejectedEvent, SDK_VERSION, SERVER_PROVIDER_IDS, SUPPORTED_CONTRACT_VERSIONS, type ServerProviderId, type Sha256Hex, TRACKING_CONTRACT_VERSION, TRACKING_SDK_NAME, type TrackOptions as TrackCallOptions, type TrackOptions, type TrackEvent, type TrackingConsent, type TrackingContext, type TrackingContextV1, type TrackingEnvelopeV1, type TrackingEventInput, type TrackingEventV1, type TrackingItemV1, type TrackingSdkV1, type UserDataInput, type ValidateEnvelopeOptions, analytics, buildTrackingEnvelope, buildTrackingEvent, captureClickIds, clearClickIds, compactPayload, configure, customAdapter, endSession, fbcFromFbclid, flush, gclidFromGclAw, hasScript, hashUserData, isDecimalString, isFunnelEventName, isInteractionEventName, isValidEventId, loadScript, normalizeCountryCode, normalizeEmail, normalizeEmailForGoogle, normalizeExternalId, normalizeName, normalizePhoneE164, parseClickIdParams, phoneDigits, purchaseEventId, readCookie, reset, resolveDeliveryMode, setConsent, setUser, sha256Hex, toDecimalString, track, upgradeEnvelope, validateEnvelope };
|