@fire-spark/analytics 0.24.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.
Files changed (3) hide show
  1. package/dist/index.d.ts +128 -10
  2. package/dist/index.js +780 -100
  3. 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
- /** Routes `meta`, `tiktok` and `google-ads` through a server relay. */
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
- /** Batch delay in ms. Default 0. A purchase always flushes at once. */
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
- type AnalyticsConfigErrorCode = "ANALYTICS_SERVER_ENDPOINT_REQUIRED" | "ANALYTICS_SERVER_MODE_UNSUPPORTED_RUNTIME" | "ANALYTICS_INVALID_ENDPOINT" | "ANALYTICS_INVALID_MODE";
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: "web";
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: "web";
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: string;
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
- sourceUrl: string;
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.24.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,9 +911,25 @@ 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
923
+ //#region src/provider-name.d.ts
924
+ /**
925
+ * Event name a destination gets for a Fire Spark event on the web, from
926
+ * the same catalog transform the browser pixels use (`purchase` →
927
+ * Meta `Purchase`, TikTok `CompletePayment`). A server must send this
928
+ * exact name, or the platform cannot deduplicate it against the pixel.
929
+ * `null` when the catalog does not send the event to that provider.
930
+ */
931
+ declare const providerEventName: (provider: Exclude<ServerProviderId, "google-ads">, name: string) => string | null;
932
+ //#endregion
815
933
  //#region src/click-ids.d.ts
816
934
  declare const CLICK_ID_STORAGE_PREFIX = "fs_ck_";
817
935
  /** Click ids from a landing URL are kept for 90 days. */
@@ -892,4 +1010,4 @@ declare const analytics: {
892
1010
  setConsent: typeof setConsent;
893
1011
  };
894
1012
  //#endregion
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 };
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 };