@aranova/tracking-react 0.5.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,114 @@
1
+ # @aranova/tracking-react
2
+
3
+ React tracking and consent utilities for Aranova client sites.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install @aranova/tracking-react
9
+ ```
10
+
11
+ ## Setup
12
+
13
+ Create one shared tracking module and import the scoped `TrackingProvider` / `useTracking` from that module throughout your app.
14
+
15
+ ```ts
16
+ // src/lib/tracking.ts
17
+ import { createTracking } from '@aranova/tracking-react';
18
+
19
+ export const { TrackingProvider, useTracking } = createTracking({
20
+ apiKey: import.meta.env.VITE_ARANOVA_TRACKING_API_KEY,
21
+ endpoint: import.meta.env.VITE_ARANOVA_TRACKING_ENDPOINT,
22
+ triggers: {
23
+ automatic: {
24
+ page_view: {},
25
+ time_on_site: { thresholdSeconds: 60 },
26
+ specific_page_visit: {
27
+ pages: [{ name: 'contact_page', pathPattern: /^\/(contact|book|get-started)/ }],
28
+ },
29
+ },
30
+ manual: {
31
+ form_submit: {},
32
+ phone_click: {},
33
+ cta_click: {},
34
+ },
35
+ },
36
+ debug: import.meta.env.MODE !== 'production',
37
+ });
38
+ ```
39
+
40
+ Mount the provider at the root of your React tree.
41
+
42
+ ```tsx
43
+ // src/main.tsx
44
+ import { createRoot } from 'react-dom/client';
45
+ import { App } from './App';
46
+ import { TrackingProvider } from './lib/tracking';
47
+
48
+ createRoot(document.getElementById('root')!).render(
49
+ <TrackingProvider gtagId={import.meta.env.VITE_GTAG_ID}>
50
+ <App />
51
+ </TrackingProvider>,
52
+ );
53
+ ```
54
+
55
+ ## Manual Events
56
+
57
+ Manual events must be registered under `triggers.manual` before `trackEvent()` accepts them.
58
+
59
+ ```tsx
60
+ import { useTracking } from './lib/tracking';
61
+
62
+ export function LeadForm() {
63
+ const tracking = useTracking();
64
+
65
+ function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
66
+ const form = event.currentTarget;
67
+ const data = new FormData(form);
68
+
69
+ tracking.trackEvent('form_submit', {
70
+ form: {
71
+ id: form.id,
72
+ action: form.getAttribute('action'),
73
+ fields: [
74
+ {
75
+ name: 'service_interest',
76
+ type: 'select',
77
+ label: 'Service interest',
78
+ value: String(data.get('service_interest') ?? ''),
79
+ },
80
+ {
81
+ name: 'is_existing_patient',
82
+ type: 'checkbox',
83
+ label: 'Existing patient',
84
+ value: data.get('is_existing_patient') === 'on',
85
+ },
86
+ ],
87
+ },
88
+ page: { path: window.location.pathname },
89
+ });
90
+ }
91
+
92
+ return <form id="lead-form" action="/api/lead" onSubmit={handleSubmit}>{/* fields */}</form>;
93
+ }
94
+ ```
95
+
96
+ `fields[].value` can be any JSON value: string, number, boolean, null, array, or object. Values must be JSON-serializable because events are stored as JSONB. Only send reviewed, allowlisted, non-sensitive values; do not send names, emails, phone numbers entered by the visitor, addresses, payment data, medical details, passwords, file contents, or free-text messages.
97
+
98
+ ```tsx
99
+ tracking.trackEvent('phone_click', {
100
+ phone_number: '+14165550199',
101
+ page: { path: window.location.pathname },
102
+ section: 'header',
103
+ });
104
+ ```
105
+
106
+ ## Exports
107
+
108
+ - `createTracking()`
109
+ - `TrackingProvider` and scoped `useTracking`
110
+ - `GoogleAdsTracking`
111
+ - `ConsentBanner`
112
+ - `useTrackingParams()`, `useGclid()`, `useConsentState()`
113
+ - Event metadata/config types such as `FormSubmitMetadata`, `PhoneClickMetadata`, and `JsonValue`
114
+
package/dist/index.d.mts CHANGED
@@ -1,5 +1,6 @@
1
1
  import * as react_jsx_runtime from 'react/jsx-runtime';
2
2
  import { ReactNode } from 'react';
3
+ import * as src from 'src';
3
4
  import { z } from 'zod';
4
5
 
5
6
  declare function ConsentBanner(): react_jsx_runtime.JSX.Element | null;
@@ -109,7 +110,7 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
109
110
  cta_name: z.ZodString;
110
111
  page: z.ZodObject<{
111
112
  path: z.ZodString;
112
- }, "strip", z.ZodTypeAny, {
113
+ }, "strict", z.ZodTypeAny, {
113
114
  path: string;
114
115
  }, {
115
116
  path: string;
@@ -177,7 +178,7 @@ declare const formStartMetadataSchema: z.ZodObject<{
177
178
  form: z.ZodObject<{
178
179
  id: z.ZodString;
179
180
  action: z.ZodNullable<z.ZodString>;
180
- }, "strip", z.ZodTypeAny, {
181
+ }, "strict", z.ZodTypeAny, {
181
182
  id: string;
182
183
  action: string | null;
183
184
  }, {
@@ -186,7 +187,7 @@ declare const formStartMetadataSchema: z.ZodObject<{
186
187
  }>;
187
188
  page: z.ZodObject<{
188
189
  path: z.ZodString;
189
- }, "strip", z.ZodTypeAny, {
190
+ }, "strict", z.ZodTypeAny, {
190
191
  path: string;
191
192
  }, {
192
193
  path: string;
@@ -218,6 +219,9 @@ declare const formStartConfigSchema: z.ZodObject<{
218
219
  }>;
219
220
  type FormStartConfig = z.infer<typeof formStartConfigSchema>;
220
221
 
222
+ type JsonValue = string | number | boolean | null | JsonValue[] | {
223
+ [key: string]: JsonValue;
224
+ };
221
225
  declare const formSubmitMetadataSchema: z.ZodObject<{
222
226
  form: z.ZodObject<{
223
227
  id: z.ZodString;
@@ -226,40 +230,40 @@ declare const formSubmitMetadataSchema: z.ZodObject<{
226
230
  name: z.ZodString;
227
231
  type: z.ZodString;
228
232
  label: z.ZodNullable<z.ZodString>;
229
- has_value: z.ZodBoolean;
230
- }, "strip", z.ZodTypeAny, {
233
+ value: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
234
+ }, "strict", z.ZodTypeAny, {
231
235
  label: string | null;
236
+ value: JsonValue;
232
237
  type: string;
233
238
  name: string;
234
- has_value: boolean;
235
239
  }, {
236
240
  label: string | null;
241
+ value: JsonValue;
237
242
  type: string;
238
243
  name: string;
239
- has_value: boolean;
240
244
  }>, "many">>;
241
- }, "strip", z.ZodTypeAny, {
245
+ }, "strict", z.ZodTypeAny, {
242
246
  id: string;
243
247
  action: string | null;
244
248
  fields?: {
245
249
  label: string | null;
250
+ value: JsonValue;
246
251
  type: string;
247
252
  name: string;
248
- has_value: boolean;
249
253
  }[] | undefined;
250
254
  }, {
251
255
  id: string;
252
256
  action: string | null;
253
257
  fields?: {
254
258
  label: string | null;
259
+ value: JsonValue;
255
260
  type: string;
256
261
  name: string;
257
- has_value: boolean;
258
262
  }[] | undefined;
259
263
  }>;
260
264
  page: z.ZodObject<{
261
265
  path: z.ZodString;
262
- }, "strip", z.ZodTypeAny, {
266
+ }, "strict", z.ZodTypeAny, {
263
267
  path: string;
264
268
  }, {
265
269
  path: string;
@@ -270,9 +274,9 @@ declare const formSubmitMetadataSchema: z.ZodObject<{
270
274
  action: string | null;
271
275
  fields?: {
272
276
  label: string | null;
277
+ value: JsonValue;
273
278
  type: string;
274
279
  name: string;
275
- has_value: boolean;
276
280
  }[] | undefined;
277
281
  };
278
282
  page: {
@@ -284,9 +288,9 @@ declare const formSubmitMetadataSchema: z.ZodObject<{
284
288
  action: string | null;
285
289
  fields?: {
286
290
  label: string | null;
291
+ value: JsonValue;
287
292
  type: string;
288
293
  name: string;
289
- has_value: boolean;
290
294
  }[] | undefined;
291
295
  };
292
296
  page: {
@@ -301,7 +305,7 @@ declare const multiPageSessionMetadataSchema: z.ZodObject<{
301
305
  page_count: z.ZodNumber;
302
306
  page: z.ZodObject<{
303
307
  path: z.ZodString;
304
- }, "strip", z.ZodTypeAny, {
308
+ }, "strict", z.ZodTypeAny, {
305
309
  path: string;
306
310
  }, {
307
311
  path: string;
@@ -333,7 +337,7 @@ declare const pageViewMetadataSchema: z.ZodObject<{
333
337
  path: z.ZodString;
334
338
  search: z.ZodString;
335
339
  hash: z.ZodString;
336
- }, "strip", z.ZodTypeAny, {
340
+ }, "strict", z.ZodTypeAny, {
337
341
  search: string;
338
342
  title: string | null;
339
343
  path: string;
@@ -348,7 +352,7 @@ declare const pageViewMetadataSchema: z.ZodObject<{
348
352
  viewport: z.ZodOptional<z.ZodNullable<z.ZodObject<{
349
353
  w: z.ZodNumber;
350
354
  h: z.ZodNumber;
351
- }, "strip", z.ZodTypeAny, {
355
+ }, "strict", z.ZodTypeAny, {
352
356
  w: number;
353
357
  h: number;
354
358
  }, {
@@ -388,7 +392,7 @@ declare const phoneClickMetadataSchema: z.ZodObject<{
388
392
  phone_number: z.ZodString;
389
393
  page: z.ZodObject<{
390
394
  path: z.ZodString;
391
- }, "strip", z.ZodTypeAny, {
395
+ }, "strict", z.ZodTypeAny, {
392
396
  path: string;
393
397
  }, {
394
398
  path: string;
@@ -415,7 +419,7 @@ declare const scrollDepthMetadataSchema: z.ZodObject<{
415
419
  depth_percent: z.ZodNumber;
416
420
  page: z.ZodObject<{
417
421
  path: z.ZodString;
418
- }, "strip", z.ZodTypeAny, {
422
+ }, "strict", z.ZodTypeAny, {
419
423
  path: string;
420
424
  }, {
421
425
  path: string;
@@ -447,7 +451,7 @@ declare const specificPageVisitMetadataSchema: z.ZodObject<{
447
451
  page_name: z.ZodEnum<["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"]>;
448
452
  page: z.ZodObject<{
449
453
  path: z.ZodString;
450
- }, "strip", z.ZodTypeAny, {
454
+ }, "strict", z.ZodTypeAny, {
451
455
  path: string;
452
456
  }, {
453
457
  path: string;
@@ -468,7 +472,7 @@ declare const specificPageVisitConfigSchema: z.ZodObject<{
468
472
  pages: z.ZodArray<z.ZodObject<{
469
473
  name: z.ZodEnum<["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"]>;
470
474
  pathPattern: z.ZodType<RegExp, z.ZodTypeDef, RegExp>;
471
- }, "strip", z.ZodTypeAny, {
475
+ }, "strict", z.ZodTypeAny, {
472
476
  name: "contact_page" | "about_page" | "services_page" | "booking_page" | "location_page" | "pricing_page" | "faq_page" | "testimonials_page";
473
477
  pathPattern: RegExp;
474
478
  }, {
@@ -492,7 +496,7 @@ declare const timeOnSiteMetadataSchema: z.ZodObject<{
492
496
  duration_ms: z.ZodNumber;
493
497
  page: z.ZodObject<{
494
498
  path: z.ZodString;
495
- }, "strip", z.ZodTypeAny, {
499
+ }, "strict", z.ZodTypeAny, {
496
500
  path: string;
497
501
  }, {
498
502
  path: string;
@@ -527,7 +531,7 @@ declare const EVENT_REGISTRY: {
527
531
  path: z.ZodString;
528
532
  search: z.ZodString;
529
533
  hash: z.ZodString;
530
- }, "strip", z.ZodTypeAny, {
534
+ }, "strict", z.ZodTypeAny, {
531
535
  search: string;
532
536
  title: string | null;
533
537
  path: string;
@@ -542,7 +546,7 @@ declare const EVENT_REGISTRY: {
542
546
  viewport: z.ZodOptional<z.ZodNullable<z.ZodObject<{
543
547
  w: z.ZodNumber;
544
548
  h: z.ZodNumber;
545
- }, "strip", z.ZodTypeAny, {
549
+ }, "strict", z.ZodTypeAny, {
546
550
  w: number;
547
551
  h: number;
548
552
  }, {
@@ -582,7 +586,7 @@ declare const EVENT_REGISTRY: {
582
586
  duration_ms: z.ZodNumber;
583
587
  page: z.ZodObject<{
584
588
  path: z.ZodString;
585
- }, "strip", z.ZodTypeAny, {
589
+ }, "strict", z.ZodTypeAny, {
586
590
  path: string;
587
591
  }, {
588
592
  path: string;
@@ -612,7 +616,7 @@ declare const EVENT_REGISTRY: {
612
616
  page_name: z.ZodEnum<["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"]>;
613
617
  page: z.ZodObject<{
614
618
  path: z.ZodString;
615
- }, "strip", z.ZodTypeAny, {
619
+ }, "strict", z.ZodTypeAny, {
616
620
  path: string;
617
621
  }, {
618
622
  path: string;
@@ -632,7 +636,7 @@ declare const EVENT_REGISTRY: {
632
636
  pages: z.ZodArray<z.ZodObject<{
633
637
  name: z.ZodEnum<["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"]>;
634
638
  pathPattern: z.ZodType<RegExp, z.ZodTypeDef, RegExp>;
635
- }, "strip", z.ZodTypeAny, {
639
+ }, "strict", z.ZodTypeAny, {
636
640
  name: "contact_page" | "about_page" | "services_page" | "booking_page" | "location_page" | "pricing_page" | "faq_page" | "testimonials_page";
637
641
  pathPattern: RegExp;
638
642
  }, {
@@ -657,7 +661,7 @@ declare const EVENT_REGISTRY: {
657
661
  depth_percent: z.ZodNumber;
658
662
  page: z.ZodObject<{
659
663
  path: z.ZodString;
660
- }, "strip", z.ZodTypeAny, {
664
+ }, "strict", z.ZodTypeAny, {
661
665
  path: string;
662
666
  }, {
663
667
  path: string;
@@ -687,7 +691,7 @@ declare const EVENT_REGISTRY: {
687
691
  page_count: z.ZodNumber;
688
692
  page: z.ZodObject<{
689
693
  path: z.ZodString;
690
- }, "strip", z.ZodTypeAny, {
694
+ }, "strict", z.ZodTypeAny, {
691
695
  path: string;
692
696
  }, {
693
697
  path: string;
@@ -717,7 +721,7 @@ declare const EVENT_REGISTRY: {
717
721
  form: z.ZodObject<{
718
722
  id: z.ZodString;
719
723
  action: z.ZodNullable<z.ZodString>;
720
- }, "strip", z.ZodTypeAny, {
724
+ }, "strict", z.ZodTypeAny, {
721
725
  id: string;
722
726
  action: string | null;
723
727
  }, {
@@ -726,7 +730,7 @@ declare const EVENT_REGISTRY: {
726
730
  }>;
727
731
  page: z.ZodObject<{
728
732
  path: z.ZodString;
729
- }, "strip", z.ZodTypeAny, {
733
+ }, "strict", z.ZodTypeAny, {
730
734
  path: string;
731
735
  }, {
732
736
  path: string;
@@ -804,40 +808,40 @@ declare const EVENT_REGISTRY: {
804
808
  name: z.ZodString;
805
809
  type: z.ZodString;
806
810
  label: z.ZodNullable<z.ZodString>;
807
- has_value: z.ZodBoolean;
808
- }, "strip", z.ZodTypeAny, {
811
+ value: z.ZodType<src.JsonValue, z.ZodTypeDef, src.JsonValue>;
812
+ }, "strict", z.ZodTypeAny, {
809
813
  label: string | null;
814
+ value: src.JsonValue;
810
815
  type: string;
811
816
  name: string;
812
- has_value: boolean;
813
817
  }, {
814
818
  label: string | null;
819
+ value: src.JsonValue;
815
820
  type: string;
816
821
  name: string;
817
- has_value: boolean;
818
822
  }>, "many">>;
819
- }, "strip", z.ZodTypeAny, {
823
+ }, "strict", z.ZodTypeAny, {
820
824
  id: string;
821
825
  action: string | null;
822
826
  fields?: {
823
827
  label: string | null;
828
+ value: src.JsonValue;
824
829
  type: string;
825
830
  name: string;
826
- has_value: boolean;
827
831
  }[] | undefined;
828
832
  }, {
829
833
  id: string;
830
834
  action: string | null;
831
835
  fields?: {
832
836
  label: string | null;
837
+ value: src.JsonValue;
833
838
  type: string;
834
839
  name: string;
835
- has_value: boolean;
836
840
  }[] | undefined;
837
841
  }>;
838
842
  page: z.ZodObject<{
839
843
  path: z.ZodString;
840
- }, "strip", z.ZodTypeAny, {
844
+ }, "strict", z.ZodTypeAny, {
841
845
  path: string;
842
846
  }, {
843
847
  path: string;
@@ -848,9 +852,9 @@ declare const EVENT_REGISTRY: {
848
852
  action: string | null;
849
853
  fields?: {
850
854
  label: string | null;
855
+ value: src.JsonValue;
851
856
  type: string;
852
857
  name: string;
853
- has_value: boolean;
854
858
  }[] | undefined;
855
859
  };
856
860
  page: {
@@ -862,9 +866,9 @@ declare const EVENT_REGISTRY: {
862
866
  action: string | null;
863
867
  fields?: {
864
868
  label: string | null;
869
+ value: src.JsonValue;
865
870
  type: string;
866
871
  name: string;
867
- has_value: boolean;
868
872
  }[] | undefined;
869
873
  };
870
874
  page: {
@@ -879,7 +883,7 @@ declare const EVENT_REGISTRY: {
879
883
  phone_number: z.ZodString;
880
884
  page: z.ZodObject<{
881
885
  path: z.ZodString;
882
- }, "strip", z.ZodTypeAny, {
886
+ }, "strict", z.ZodTypeAny, {
883
887
  path: string;
884
888
  }, {
885
889
  path: string;
@@ -906,7 +910,7 @@ declare const EVENT_REGISTRY: {
906
910
  cta_name: z.ZodString;
907
911
  page: z.ZodObject<{
908
912
  path: z.ZodString;
909
- }, "strip", z.ZodTypeAny, {
913
+ }, "strict", z.ZodTypeAny, {
910
914
  path: string;
911
915
  }, {
912
916
  path: string;
@@ -1048,4 +1052,4 @@ interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
1048
1052
  }
1049
1053
  declare function createTracking<TRegistry extends TriggerRegistryConfig>(options: CreateTrackingOptions<TRegistry>): CreateTrackingResult<TRegistry>;
1050
1054
 
1051
- export { type AutomaticEventName, ConsentBanner, type ConsentState, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, type EventConfig, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, type FormSubmitConfig, type FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, type ManualEventName, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageViewConfig, type PageViewMetadata, type PhoneClickConfig, type PhoneClickMetadata, type RegisteredAutomaticEvents, type RegisteredManualEvents, type ScrollDepthConfig, type ScrollDepthMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackingClient, type TrackingClientContext, type TrackingEventCreatePayload, type TrackingInitConfig, type TrackingInstallSurface, type TrackingParams, type TrackingProviderProps, type TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, captureTrackingParamsFromLocation, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, getConsentState, setConsentState, useConsentState, useGclid, useTrackingParams };
1055
+ export { type AutomaticEventName, ConsentBanner, type ConsentState, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, type EventConfig, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, type FormSubmitConfig, type FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, type JsonValue, type ManualEventName, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageViewConfig, type PageViewMetadata, type PhoneClickConfig, type PhoneClickMetadata, type RegisteredAutomaticEvents, type RegisteredManualEvents, type ScrollDepthConfig, type ScrollDepthMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackingClient, type TrackingClientContext, type TrackingEventCreatePayload, type TrackingInitConfig, type TrackingInstallSurface, type TrackingParams, type TrackingProviderProps, type TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, captureTrackingParamsFromLocation, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, getConsentState, setConsentState, useConsentState, useGclid, useTrackingParams };