@fire-spark/analytics 0.25.0 → 0.26.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 +118 -10
- package/dist/index.js +762 -100
- package/package.json +2 -2
package/dist/index.d.ts
CHANGED
|
@@ -40,7 +40,10 @@ type AnalyticsRuntime = "web" | "react-native";
|
|
|
40
40
|
* loads the pixel scripts. `hybrid` does both with the same `eventId`.
|
|
41
41
|
*/
|
|
42
42
|
type AnalyticsDeliveryMode = "client" | "server" | "hybrid";
|
|
43
|
-
/**
|
|
43
|
+
/**
|
|
44
|
+
* Routes `meta`, `tiktok` and `google-ads` through a server relay. On
|
|
45
|
+
* `react-native` only `meta` is relayed and only `purchase` events.
|
|
46
|
+
*/
|
|
44
47
|
interface AnalyticsServerSideOptions {
|
|
45
48
|
/** `"/api/track"` (same-origin path) or an `https:` URL. */
|
|
46
49
|
endpoint?: string;
|
|
@@ -51,12 +54,42 @@ interface AnalyticsServerSideOptions {
|
|
|
51
54
|
providers?: ServerProviderId[];
|
|
52
55
|
/** Events per relay request, 1 to 20. Default 10. */
|
|
53
56
|
batchSize?: number;
|
|
54
|
-
/**
|
|
57
|
+
/**
|
|
58
|
+
* Batch delay in ms. Default 0. A purchase always flushes at once. On
|
|
59
|
+
* `react-native` it is also the outbox retry delay (default 60 s).
|
|
60
|
+
*/
|
|
55
61
|
flushIntervalMs?: number;
|
|
56
62
|
/** Extra non-secret request headers (for example a CSRF token). */
|
|
57
63
|
headers?: Record<string, string>;
|
|
64
|
+
/**
|
|
65
|
+
* Customer access token sent as `Authorization: Bearer`. Read at send
|
|
66
|
+
* time and never stored. After a `401`/`403` it is called once more with
|
|
67
|
+
* `{ refresh: true }`. Required on `react-native`; not used on web.
|
|
68
|
+
*/
|
|
69
|
+
getAuthToken?: (request: {
|
|
70
|
+
refresh: boolean;
|
|
71
|
+
}) => Promise<string | null> | string | null;
|
|
72
|
+
/**
|
|
73
|
+
* Device and app data for `context.app`, read for every relayed event
|
|
74
|
+
* (ATT and the advertising id can change). Required on `react-native`.
|
|
75
|
+
* `null` skips the relay for that event.
|
|
76
|
+
*/
|
|
77
|
+
getAppContext?: () => Promise<TrackingAppContext | null> | TrackingAppContext | null;
|
|
78
|
+
/** Persistent relay outbox (`react-native` only). */
|
|
79
|
+
outbox?: AnalyticsOutboxOptions;
|
|
58
80
|
}
|
|
59
|
-
|
|
81
|
+
interface AnalyticsOutboxOptions {
|
|
82
|
+
/** Oldest entries are dropped past this. Default 200. */
|
|
83
|
+
maxEvents?: number;
|
|
84
|
+
/**
|
|
85
|
+
* Entries older than this are dropped instead of sent. Default 47 hours:
|
|
86
|
+
* the server and Meta deduplicate for 48 hours.
|
|
87
|
+
*/
|
|
88
|
+
maxAgeMs?: number;
|
|
89
|
+
}
|
|
90
|
+
type AnalyticsConfigErrorCode = "ANALYTICS_SERVER_ENDPOINT_REQUIRED" | "ANALYTICS_SERVER_AUTH_REQUIRED" | "ANALYTICS_SERVER_APP_CONTEXT_REQUIRED" |
|
|
91
|
+
/** @deprecated No longer thrown: react-native supports server delivery. */
|
|
92
|
+
"ANALYTICS_SERVER_MODE_UNSUPPORTED_RUNTIME" | "ANALYTICS_INVALID_ENDPOINT" | "ANALYTICS_INVALID_MODE";
|
|
60
93
|
/**
|
|
61
94
|
* Thrown by `resolveDeliveryMode()` for an invalid `mode` / `serverSide`.
|
|
62
95
|
* In development `configure()` lets it throw; in production (`env:
|
|
@@ -413,23 +446,80 @@ interface TrackingEnvelopeV1 {
|
|
|
413
446
|
/** 1 to 20 events. */
|
|
414
447
|
events: TrackingEventV1[];
|
|
415
448
|
}
|
|
449
|
+
/** Where the event was tracked. */
|
|
450
|
+
type TrackingRuntime = "web" | "react-native";
|
|
451
|
+
/** iOS App Tracking Transparency status; Android sends `not_applicable`. */
|
|
452
|
+
type TrackingAttStatus = "authorized" | "denied" | "not_determined" | "restricted" | "not_applicable";
|
|
453
|
+
/** Device and app data of a `react-native` event, snake_case on the wire. */
|
|
454
|
+
interface TrackingAppContextV1 {
|
|
455
|
+
platform: "ios" | "android";
|
|
456
|
+
/** Bundle id or package name, 1 to 155 characters. */
|
|
457
|
+
id: string;
|
|
458
|
+
version?: string;
|
|
459
|
+
build?: string;
|
|
460
|
+
os_version: string;
|
|
461
|
+
device_model?: string;
|
|
462
|
+
/** BCP 47 as given by the device, up to 35 characters. */
|
|
463
|
+
locale?: string;
|
|
464
|
+
/** IANA time zone. */
|
|
465
|
+
timezone?: string;
|
|
466
|
+
/** Physical pixels, integer 1 to 100000. */
|
|
467
|
+
screen_width?: number;
|
|
468
|
+
screen_height?: number;
|
|
469
|
+
screen_density?: DecimalString;
|
|
470
|
+
/** 8 to 64 of `[A-Za-z0-9-]`. */
|
|
471
|
+
install_id: string;
|
|
472
|
+
/** iOS IDFV (UUID). Only when ATT is `authorized`. */
|
|
473
|
+
vendor_id?: string;
|
|
474
|
+
/** IDFA or Android advertising id (UUID, not all zeros). */
|
|
475
|
+
ad_id?: string;
|
|
476
|
+
att_status: TrackingAttStatus;
|
|
477
|
+
advertiser_tracking: boolean;
|
|
478
|
+
/** Android Play Install Referrer string, up to 2048 characters. */
|
|
479
|
+
install_referrer?: string;
|
|
480
|
+
}
|
|
481
|
+
/** Input of `getAppContext()`; sent as `TrackingAppContextV1`. */
|
|
482
|
+
interface TrackingAppContext {
|
|
483
|
+
platform: "ios" | "android";
|
|
484
|
+
id: string;
|
|
485
|
+
version?: string;
|
|
486
|
+
build?: string;
|
|
487
|
+
osVersion: string;
|
|
488
|
+
deviceModel?: string;
|
|
489
|
+
locale?: string;
|
|
490
|
+
timezone?: string;
|
|
491
|
+
screenWidth?: number;
|
|
492
|
+
screenHeight?: number;
|
|
493
|
+
/** `PixelRatio.get()`; sent as a decimal string. */
|
|
494
|
+
screenDensity?: number | DecimalString;
|
|
495
|
+
installId: string;
|
|
496
|
+
vendorId?: string;
|
|
497
|
+
adId?: string;
|
|
498
|
+
attStatus: TrackingAttStatus;
|
|
499
|
+
advertiserTracking: boolean;
|
|
500
|
+
installReferrer?: string;
|
|
501
|
+
}
|
|
416
502
|
interface TrackingContextV1 {
|
|
417
|
-
runtime:
|
|
503
|
+
runtime: TrackingRuntime;
|
|
418
504
|
/** BCP 47, for example `es-EC`. */
|
|
419
505
|
locale?: string;
|
|
420
506
|
channel_id: string;
|
|
421
507
|
store_id?: string;
|
|
422
508
|
brand_id?: string;
|
|
423
509
|
fulfillment_id?: string;
|
|
510
|
+
/** Required when `runtime` is `react-native`. */
|
|
511
|
+
app?: TrackingAppContextV1;
|
|
424
512
|
}
|
|
425
513
|
/** Input of `buildTrackingEvent()`; sent as `TrackingContextV1`. */
|
|
426
514
|
interface TrackingContext {
|
|
427
|
-
runtime:
|
|
515
|
+
runtime: TrackingRuntime;
|
|
428
516
|
locale?: string;
|
|
429
517
|
channelId: string;
|
|
430
518
|
storeId?: string;
|
|
431
519
|
brandId?: string;
|
|
432
520
|
fulfillmentId?: string;
|
|
521
|
+
/** Required when `runtime` is `react-native`. */
|
|
522
|
+
app?: TrackingAppContext;
|
|
433
523
|
}
|
|
434
524
|
interface TrackingEventV1 {
|
|
435
525
|
/** 1 to 64 of `[A-Za-z0-9:_.-]`. The same id the browser pixels get. */
|
|
@@ -438,8 +528,8 @@ interface TrackingEventV1 {
|
|
|
438
528
|
name: string;
|
|
439
529
|
/** Epoch milliseconds when `track()` was called. */
|
|
440
530
|
timestamp: number;
|
|
441
|
-
/** Page URL (`https:`). */
|
|
442
|
-
source_url
|
|
531
|
+
/** Page URL (`https:`). Required on `web`, omitted on `react-native`. */
|
|
532
|
+
source_url?: string;
|
|
443
533
|
referrer_url?: string;
|
|
444
534
|
/** Tracked params without personal data, `items`, `value` and `currency`. */
|
|
445
535
|
properties: Record<string, unknown>;
|
|
@@ -543,6 +633,11 @@ interface ValidateEnvelopeOptions {
|
|
|
543
633
|
providers?: readonly ServerProviderId[];
|
|
544
634
|
/** Accept `http://localhost` source URLs (local development only). */
|
|
545
635
|
allowLocalhost?: boolean;
|
|
636
|
+
/**
|
|
637
|
+
* Runtimes this endpoint accepts. Defaults to `["web"]`, so a web relay
|
|
638
|
+
* rejects `react-native` events with `invalid_event`.
|
|
639
|
+
*/
|
|
640
|
+
runtimes?: readonly TrackingRuntime[];
|
|
546
641
|
}
|
|
547
642
|
/** Input of `buildTrackingEvent()`. */
|
|
548
643
|
interface TrackingEventInput {
|
|
@@ -550,7 +645,8 @@ interface TrackingEventInput {
|
|
|
550
645
|
name: string;
|
|
551
646
|
/** Epoch ms when `track()` was called. */
|
|
552
647
|
timestamp: number;
|
|
553
|
-
|
|
648
|
+
/** Page URL. Required on `web`; ignored on `react-native`. */
|
|
649
|
+
sourceUrl?: string;
|
|
554
650
|
referrerUrl?: string;
|
|
555
651
|
/** Raw tracked params. Personal data is removed, never copied. */
|
|
556
652
|
properties?: Record<string, unknown>;
|
|
@@ -681,7 +777,7 @@ declare const customAdapter: (options: CustomAdapterOptions) => CustomAnalyticsA
|
|
|
681
777
|
//#endregion
|
|
682
778
|
//#region src/version.d.ts
|
|
683
779
|
/** Kept equal to package.json by `pnpm sdk:release` (see version.test.ts). */
|
|
684
|
-
declare const SDK_VERSION = "0.
|
|
780
|
+
declare const SDK_VERSION = "0.26.0";
|
|
685
781
|
//#endregion
|
|
686
782
|
//#region src/compact.d.ts
|
|
687
783
|
/** Drops `undefined`, `null`, non-finite numbers and functions, deeply. */
|
|
@@ -768,6 +864,7 @@ declare const CLICK_ID_WIRE_KEYS: {
|
|
|
768
864
|
readonly wbraid: "wbraid";
|
|
769
865
|
readonly googleSessionAttributes: "google_session_attributes";
|
|
770
866
|
};
|
|
867
|
+
type AppTrackingState = Pick<TrackingAppContextV1, "platform" | "att_status">;
|
|
771
868
|
/** 1 to 64 of `[A-Za-z0-9:_.-]`. */
|
|
772
869
|
declare const isValidEventId: (value: unknown) => value is string;
|
|
773
870
|
/**
|
|
@@ -785,6 +882,11 @@ declare const isDecimalString: (value: unknown) => value is DecimalString;
|
|
|
785
882
|
* of its shortest representation (`25.9` → `"25.9"`).
|
|
786
883
|
*/
|
|
787
884
|
declare const toDecimalString: (value: unknown) => string | undefined;
|
|
885
|
+
/**
|
|
886
|
+
* Whether app tracking data may leave the device: on iOS only with ATT
|
|
887
|
+
* `authorized`; on Android always (consent is checked separately).
|
|
888
|
+
*/
|
|
889
|
+
declare const appTrackingAllowed: (app: AppTrackingState) => boolean;
|
|
788
890
|
/**
|
|
789
891
|
* One contract v1 event from a tracked event. Personal params are
|
|
790
892
|
* dropped (pass hashed user data in `user`), money becomes decimal
|
|
@@ -809,6 +911,12 @@ declare const upgradeEnvelope: (envelope: Record<string, unknown>) => Record<str
|
|
|
809
911
|
* (`email`, `phone`, `first_name`, `last_name`, `device_ip`, `ttclid`) are
|
|
810
912
|
* dropped, and `consent.ad_user_data` / `ad_personalization` default to
|
|
811
913
|
* `ads`. Field names are snake_case, as on the wire.
|
|
914
|
+
*
|
|
915
|
+
* Only `options.runtimes` are accepted (default `["web"]`). A
|
|
916
|
+
* `react-native` event needs `context.app`; its `source_url` and
|
|
917
|
+
* `referrer_url` are dropped, all-zero `ad_id` / `vendor_id` are dropped,
|
|
918
|
+
* and on iOS without ATT `authorized` the device ids and `user` hashes
|
|
919
|
+
* are removed.
|
|
812
920
|
*/
|
|
813
921
|
declare const validateEnvelope: (input: unknown, options?: ValidateEnvelopeOptions) => EnvelopeValidation;
|
|
814
922
|
//#endregion
|
|
@@ -902,4 +1010,4 @@ declare const analytics: {
|
|
|
902
1010
|
setConsent: typeof setConsent;
|
|
903
1011
|
};
|
|
904
1012
|
//#endregion
|
|
905
|
-
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, providerEventName, purchaseEventId, readCookie, reset, resolveDeliveryMode, setConsent, setUser, sha256Hex, toDecimalString, track, upgradeEnvelope, validateEnvelope };
|
|
1013
|
+
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 AnalyticsOutboxOptions, 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 TrackingAppContext, type TrackingAppContextV1, type TrackingAttStatus, type TrackingConsent, type TrackingContext, type TrackingContextV1, type TrackingEnvelopeV1, type TrackingEventInput, type TrackingEventV1, type TrackingItemV1, type TrackingRuntime, type TrackingSdkV1, type UserDataInput, type ValidateEnvelopeOptions, analytics, appTrackingAllowed, 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, providerEventName, purchaseEventId, readCookie, reset, resolveDeliveryMode, setConsent, setUser, sha256Hex, toDecimalString, track, upgradeEnvelope, validateEnvelope };
|