@aranova/tracking-next 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,150 @@
1
+ # @aranova/tracking-next
2
+
3
+ Next.js tracking utilities for Aranova client sites. Use this package for App Router installs where attribution cookies should be captured before client JavaScript runs.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install @aranova/tracking-next
9
+ ```
10
+
11
+ ## Middleware
12
+
13
+ Install the tracking middleware so `gclid`, `fbclid`, and UTM params are written to cookies from the first HTTP response.
14
+
15
+ ```ts
16
+ // middleware.ts
17
+ import { createTrackingMiddleware } from '@aranova/tracking-next/middleware';
18
+
19
+ export default createTrackingMiddleware();
20
+
21
+ export const config = {
22
+ matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
23
+ };
24
+ ```
25
+
26
+ ## Provider
27
+
28
+ Create one shared tracking module and use its scoped exports throughout your app.
29
+
30
+ ```ts
31
+ // lib/tracking.ts
32
+ import { createTracking } from '@aranova/tracking-next';
33
+
34
+ export const { TrackingProvider, useTracking } = createTracking({
35
+ apiKey: process.env.NEXT_PUBLIC_ARANOVA_TRACKING_API_KEY!,
36
+ endpoint: process.env.NEXT_PUBLIC_ARANOVA_TRACKING_ENDPOINT!,
37
+ triggers: {
38
+ automatic: {
39
+ page_view: {},
40
+ time_on_site: { thresholdSeconds: 60 },
41
+ specific_page_visit: {
42
+ pages: [{ name: 'contact_page', pathPattern: /^\/(contact|book|get-started)/ }],
43
+ },
44
+ },
45
+ manual: {
46
+ form_submit: {},
47
+ phone_click: {},
48
+ cta_click: {},
49
+ },
50
+ },
51
+ debug: process.env.NODE_ENV !== 'production',
52
+ });
53
+ ```
54
+
55
+ Wrap the root layout.
56
+
57
+ ```tsx
58
+ // app/layout.tsx
59
+ import { ConsentBanner, GoogleAdsTracking } from '@aranova/tracking-next';
60
+ import { TrackingProvider } from '@/lib/tracking';
61
+
62
+ export default function RootLayout({ children }: { children: React.ReactNode }) {
63
+ return (
64
+ <html lang="en">
65
+ <head>
66
+ {process.env.NEXT_PUBLIC_GTAG_ID && (
67
+ <GoogleAdsTracking gtagId={process.env.NEXT_PUBLIC_GTAG_ID} />
68
+ )}
69
+ </head>
70
+ <body>
71
+ <TrackingProvider>
72
+ {children}
73
+ <ConsentBanner />
74
+ </TrackingProvider>
75
+ </body>
76
+ </html>
77
+ );
78
+ }
79
+ ```
80
+
81
+ ## Manual Events
82
+
83
+ Import `useTracking` from your local `lib/tracking` module, not directly from the package.
84
+
85
+ ```tsx
86
+ 'use client';
87
+
88
+ import { useTracking } from '@/lib/tracking';
89
+
90
+ export function LeadForm() {
91
+ const tracking = useTracking();
92
+
93
+ return (
94
+ <form
95
+ id="lead-form"
96
+ action="/api/lead"
97
+ onSubmit={(event) => {
98
+ const form = event.currentTarget;
99
+ const data = new FormData(form);
100
+
101
+ tracking.trackEvent('form_submit', {
102
+ form: {
103
+ id: form.id,
104
+ action: form.getAttribute('action'),
105
+ fields: [
106
+ {
107
+ name: 'service_interest',
108
+ type: 'select',
109
+ label: 'Service interest',
110
+ value: String(data.get('service_interest') ?? ''),
111
+ },
112
+ {
113
+ name: 'is_existing_patient',
114
+ type: 'checkbox',
115
+ label: 'Existing patient',
116
+ value: data.get('is_existing_patient') === 'on',
117
+ },
118
+ ],
119
+ },
120
+ page: { path: window.location.pathname },
121
+ });
122
+ }}
123
+ >
124
+ {/* fields */}
125
+ </form>
126
+ );
127
+ }
128
+ ```
129
+
130
+ `fields[].value` can be any JSON value: string, number, boolean, null, array, or object. 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.
131
+
132
+ ## Server Reads
133
+
134
+ Read attribution cookies from Server Components or server actions.
135
+
136
+ ```tsx
137
+ import { getTrackingParamsServer } from '@aranova/tracking-next/server';
138
+
139
+ export default function Page() {
140
+ const { gclid, utm_source } = getTrackingParamsServer();
141
+ return gclid || utm_source === 'google' ? <GoogleLanding /> : <OrganicLanding />;
142
+ }
143
+ ```
144
+
145
+ ## Exports
146
+
147
+ - Root package: `createTracking`, `TrackingProvider`, `useTracking`, `GoogleAdsTracking`, `ConsentBanner`, hooks, and event types
148
+ - `@aranova/tracking-next/middleware`: `createTrackingMiddleware()`
149
+ - `@aranova/tracking-next/server`: `getTrackingParamsServer()`
150
+
package/dist/index.d.mts CHANGED
@@ -1,6 +1,7 @@
1
1
  import { C as ConsentState, T as TrackingInstallSurface, a as TrackingClientContext, b as TrackingParams, c as TrackingEventCreatePayload, d as TrackingSessionUpsertPayload } from './types-Gp0ioRiQ.mjs';
2
2
  export { e as TrackingInitConfig } from './types-Gp0ioRiQ.mjs';
3
3
  import { z } from 'zod';
4
+ import * as src from 'src';
4
5
  import * as react_jsx_runtime from 'react/jsx-runtime';
5
6
  import { ReactNode } from 'react';
6
7
 
@@ -38,7 +39,7 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
38
39
  cta_name: z.ZodString;
39
40
  page: z.ZodObject<{
40
41
  path: z.ZodString;
41
- }, "strip", z.ZodTypeAny, {
42
+ }, "strict", z.ZodTypeAny, {
42
43
  path: string;
43
44
  }, {
44
45
  path: string;
@@ -106,7 +107,7 @@ declare const formStartMetadataSchema: z.ZodObject<{
106
107
  form: z.ZodObject<{
107
108
  id: z.ZodString;
108
109
  action: z.ZodNullable<z.ZodString>;
109
- }, "strip", z.ZodTypeAny, {
110
+ }, "strict", z.ZodTypeAny, {
110
111
  id: string;
111
112
  action: string | null;
112
113
  }, {
@@ -115,7 +116,7 @@ declare const formStartMetadataSchema: z.ZodObject<{
115
116
  }>;
116
117
  page: z.ZodObject<{
117
118
  path: z.ZodString;
118
- }, "strip", z.ZodTypeAny, {
119
+ }, "strict", z.ZodTypeAny, {
119
120
  path: string;
120
121
  }, {
121
122
  path: string;
@@ -147,6 +148,9 @@ declare const formStartConfigSchema: z.ZodObject<{
147
148
  }>;
148
149
  type FormStartConfig = z.infer<typeof formStartConfigSchema>;
149
150
 
151
+ type JsonValue = string | number | boolean | null | JsonValue[] | {
152
+ [key: string]: JsonValue;
153
+ };
150
154
  declare const formSubmitMetadataSchema: z.ZodObject<{
151
155
  form: z.ZodObject<{
152
156
  id: z.ZodString;
@@ -155,40 +159,40 @@ declare const formSubmitMetadataSchema: z.ZodObject<{
155
159
  name: z.ZodString;
156
160
  type: z.ZodString;
157
161
  label: z.ZodNullable<z.ZodString>;
158
- has_value: z.ZodBoolean;
159
- }, "strip", z.ZodTypeAny, {
162
+ value: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
163
+ }, "strict", z.ZodTypeAny, {
160
164
  label: string | null;
165
+ value: JsonValue;
161
166
  type: string;
162
167
  name: string;
163
- has_value: boolean;
164
168
  }, {
165
169
  label: string | null;
170
+ value: JsonValue;
166
171
  type: string;
167
172
  name: string;
168
- has_value: boolean;
169
173
  }>, "many">>;
170
- }, "strip", z.ZodTypeAny, {
174
+ }, "strict", z.ZodTypeAny, {
171
175
  id: string;
172
176
  action: string | null;
173
177
  fields?: {
174
178
  label: string | null;
179
+ value: JsonValue;
175
180
  type: string;
176
181
  name: string;
177
- has_value: boolean;
178
182
  }[] | undefined;
179
183
  }, {
180
184
  id: string;
181
185
  action: string | null;
182
186
  fields?: {
183
187
  label: string | null;
188
+ value: JsonValue;
184
189
  type: string;
185
190
  name: string;
186
- has_value: boolean;
187
191
  }[] | undefined;
188
192
  }>;
189
193
  page: z.ZodObject<{
190
194
  path: z.ZodString;
191
- }, "strip", z.ZodTypeAny, {
195
+ }, "strict", z.ZodTypeAny, {
192
196
  path: string;
193
197
  }, {
194
198
  path: string;
@@ -199,9 +203,9 @@ declare const formSubmitMetadataSchema: z.ZodObject<{
199
203
  action: string | null;
200
204
  fields?: {
201
205
  label: string | null;
206
+ value: JsonValue;
202
207
  type: string;
203
208
  name: string;
204
- has_value: boolean;
205
209
  }[] | undefined;
206
210
  };
207
211
  page: {
@@ -213,9 +217,9 @@ declare const formSubmitMetadataSchema: z.ZodObject<{
213
217
  action: string | null;
214
218
  fields?: {
215
219
  label: string | null;
220
+ value: JsonValue;
216
221
  type: string;
217
222
  name: string;
218
- has_value: boolean;
219
223
  }[] | undefined;
220
224
  };
221
225
  page: {
@@ -230,7 +234,7 @@ declare const multiPageSessionMetadataSchema: z.ZodObject<{
230
234
  page_count: z.ZodNumber;
231
235
  page: z.ZodObject<{
232
236
  path: z.ZodString;
233
- }, "strip", z.ZodTypeAny, {
237
+ }, "strict", z.ZodTypeAny, {
234
238
  path: string;
235
239
  }, {
236
240
  path: string;
@@ -262,7 +266,7 @@ declare const pageViewMetadataSchema: z.ZodObject<{
262
266
  path: z.ZodString;
263
267
  search: z.ZodString;
264
268
  hash: z.ZodString;
265
- }, "strip", z.ZodTypeAny, {
269
+ }, "strict", z.ZodTypeAny, {
266
270
  search: string;
267
271
  title: string | null;
268
272
  path: string;
@@ -277,7 +281,7 @@ declare const pageViewMetadataSchema: z.ZodObject<{
277
281
  viewport: z.ZodOptional<z.ZodNullable<z.ZodObject<{
278
282
  w: z.ZodNumber;
279
283
  h: z.ZodNumber;
280
- }, "strip", z.ZodTypeAny, {
284
+ }, "strict", z.ZodTypeAny, {
281
285
  w: number;
282
286
  h: number;
283
287
  }, {
@@ -317,7 +321,7 @@ declare const phoneClickMetadataSchema: z.ZodObject<{
317
321
  phone_number: z.ZodString;
318
322
  page: z.ZodObject<{
319
323
  path: z.ZodString;
320
- }, "strip", z.ZodTypeAny, {
324
+ }, "strict", z.ZodTypeAny, {
321
325
  path: string;
322
326
  }, {
323
327
  path: string;
@@ -344,7 +348,7 @@ declare const scrollDepthMetadataSchema: z.ZodObject<{
344
348
  depth_percent: z.ZodNumber;
345
349
  page: z.ZodObject<{
346
350
  path: z.ZodString;
347
- }, "strip", z.ZodTypeAny, {
351
+ }, "strict", z.ZodTypeAny, {
348
352
  path: string;
349
353
  }, {
350
354
  path: string;
@@ -376,7 +380,7 @@ declare const specificPageVisitMetadataSchema: z.ZodObject<{
376
380
  page_name: z.ZodEnum<["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"]>;
377
381
  page: z.ZodObject<{
378
382
  path: z.ZodString;
379
- }, "strip", z.ZodTypeAny, {
383
+ }, "strict", z.ZodTypeAny, {
380
384
  path: string;
381
385
  }, {
382
386
  path: string;
@@ -397,7 +401,7 @@ declare const specificPageVisitConfigSchema: z.ZodObject<{
397
401
  pages: z.ZodArray<z.ZodObject<{
398
402
  name: z.ZodEnum<["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"]>;
399
403
  pathPattern: z.ZodType<RegExp, z.ZodTypeDef, RegExp>;
400
- }, "strip", z.ZodTypeAny, {
404
+ }, "strict", z.ZodTypeAny, {
401
405
  name: "contact_page" | "about_page" | "services_page" | "booking_page" | "location_page" | "pricing_page" | "faq_page" | "testimonials_page";
402
406
  pathPattern: RegExp;
403
407
  }, {
@@ -421,7 +425,7 @@ declare const timeOnSiteMetadataSchema: z.ZodObject<{
421
425
  duration_ms: z.ZodNumber;
422
426
  page: z.ZodObject<{
423
427
  path: z.ZodString;
424
- }, "strip", z.ZodTypeAny, {
428
+ }, "strict", z.ZodTypeAny, {
425
429
  path: string;
426
430
  }, {
427
431
  path: string;
@@ -456,7 +460,7 @@ declare const EVENT_REGISTRY: {
456
460
  path: z.ZodString;
457
461
  search: z.ZodString;
458
462
  hash: z.ZodString;
459
- }, "strip", z.ZodTypeAny, {
463
+ }, "strict", z.ZodTypeAny, {
460
464
  search: string;
461
465
  title: string | null;
462
466
  path: string;
@@ -471,7 +475,7 @@ declare const EVENT_REGISTRY: {
471
475
  viewport: z.ZodOptional<z.ZodNullable<z.ZodObject<{
472
476
  w: z.ZodNumber;
473
477
  h: z.ZodNumber;
474
- }, "strip", z.ZodTypeAny, {
478
+ }, "strict", z.ZodTypeAny, {
475
479
  w: number;
476
480
  h: number;
477
481
  }, {
@@ -511,7 +515,7 @@ declare const EVENT_REGISTRY: {
511
515
  duration_ms: z.ZodNumber;
512
516
  page: z.ZodObject<{
513
517
  path: z.ZodString;
514
- }, "strip", z.ZodTypeAny, {
518
+ }, "strict", z.ZodTypeAny, {
515
519
  path: string;
516
520
  }, {
517
521
  path: string;
@@ -541,7 +545,7 @@ declare const EVENT_REGISTRY: {
541
545
  page_name: z.ZodEnum<["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"]>;
542
546
  page: z.ZodObject<{
543
547
  path: z.ZodString;
544
- }, "strip", z.ZodTypeAny, {
548
+ }, "strict", z.ZodTypeAny, {
545
549
  path: string;
546
550
  }, {
547
551
  path: string;
@@ -561,7 +565,7 @@ declare const EVENT_REGISTRY: {
561
565
  pages: z.ZodArray<z.ZodObject<{
562
566
  name: z.ZodEnum<["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"]>;
563
567
  pathPattern: z.ZodType<RegExp, z.ZodTypeDef, RegExp>;
564
- }, "strip", z.ZodTypeAny, {
568
+ }, "strict", z.ZodTypeAny, {
565
569
  name: "contact_page" | "about_page" | "services_page" | "booking_page" | "location_page" | "pricing_page" | "faq_page" | "testimonials_page";
566
570
  pathPattern: RegExp;
567
571
  }, {
@@ -586,7 +590,7 @@ declare const EVENT_REGISTRY: {
586
590
  depth_percent: z.ZodNumber;
587
591
  page: z.ZodObject<{
588
592
  path: z.ZodString;
589
- }, "strip", z.ZodTypeAny, {
593
+ }, "strict", z.ZodTypeAny, {
590
594
  path: string;
591
595
  }, {
592
596
  path: string;
@@ -616,7 +620,7 @@ declare const EVENT_REGISTRY: {
616
620
  page_count: z.ZodNumber;
617
621
  page: z.ZodObject<{
618
622
  path: z.ZodString;
619
- }, "strip", z.ZodTypeAny, {
623
+ }, "strict", z.ZodTypeAny, {
620
624
  path: string;
621
625
  }, {
622
626
  path: string;
@@ -646,7 +650,7 @@ declare const EVENT_REGISTRY: {
646
650
  form: z.ZodObject<{
647
651
  id: z.ZodString;
648
652
  action: z.ZodNullable<z.ZodString>;
649
- }, "strip", z.ZodTypeAny, {
653
+ }, "strict", z.ZodTypeAny, {
650
654
  id: string;
651
655
  action: string | null;
652
656
  }, {
@@ -655,7 +659,7 @@ declare const EVENT_REGISTRY: {
655
659
  }>;
656
660
  page: z.ZodObject<{
657
661
  path: z.ZodString;
658
- }, "strip", z.ZodTypeAny, {
662
+ }, "strict", z.ZodTypeAny, {
659
663
  path: string;
660
664
  }, {
661
665
  path: string;
@@ -733,40 +737,40 @@ declare const EVENT_REGISTRY: {
733
737
  name: z.ZodString;
734
738
  type: z.ZodString;
735
739
  label: z.ZodNullable<z.ZodString>;
736
- has_value: z.ZodBoolean;
737
- }, "strip", z.ZodTypeAny, {
740
+ value: z.ZodType<src.JsonValue, z.ZodTypeDef, src.JsonValue>;
741
+ }, "strict", z.ZodTypeAny, {
738
742
  label: string | null;
743
+ value: src.JsonValue;
739
744
  type: string;
740
745
  name: string;
741
- has_value: boolean;
742
746
  }, {
743
747
  label: string | null;
748
+ value: src.JsonValue;
744
749
  type: string;
745
750
  name: string;
746
- has_value: boolean;
747
751
  }>, "many">>;
748
- }, "strip", z.ZodTypeAny, {
752
+ }, "strict", z.ZodTypeAny, {
749
753
  id: string;
750
754
  action: string | null;
751
755
  fields?: {
752
756
  label: string | null;
757
+ value: src.JsonValue;
753
758
  type: string;
754
759
  name: string;
755
- has_value: boolean;
756
760
  }[] | undefined;
757
761
  }, {
758
762
  id: string;
759
763
  action: string | null;
760
764
  fields?: {
761
765
  label: string | null;
766
+ value: src.JsonValue;
762
767
  type: string;
763
768
  name: string;
764
- has_value: boolean;
765
769
  }[] | undefined;
766
770
  }>;
767
771
  page: z.ZodObject<{
768
772
  path: z.ZodString;
769
- }, "strip", z.ZodTypeAny, {
773
+ }, "strict", z.ZodTypeAny, {
770
774
  path: string;
771
775
  }, {
772
776
  path: string;
@@ -777,9 +781,9 @@ declare const EVENT_REGISTRY: {
777
781
  action: string | null;
778
782
  fields?: {
779
783
  label: string | null;
784
+ value: src.JsonValue;
780
785
  type: string;
781
786
  name: string;
782
- has_value: boolean;
783
787
  }[] | undefined;
784
788
  };
785
789
  page: {
@@ -791,9 +795,9 @@ declare const EVENT_REGISTRY: {
791
795
  action: string | null;
792
796
  fields?: {
793
797
  label: string | null;
798
+ value: src.JsonValue;
794
799
  type: string;
795
800
  name: string;
796
- has_value: boolean;
797
801
  }[] | undefined;
798
802
  };
799
803
  page: {
@@ -808,7 +812,7 @@ declare const EVENT_REGISTRY: {
808
812
  phone_number: z.ZodString;
809
813
  page: z.ZodObject<{
810
814
  path: z.ZodString;
811
- }, "strip", z.ZodTypeAny, {
815
+ }, "strict", z.ZodTypeAny, {
812
816
  path: string;
813
817
  }, {
814
818
  path: string;
@@ -835,7 +839,7 @@ declare const EVENT_REGISTRY: {
835
839
  cta_name: z.ZodString;
836
840
  page: z.ZodObject<{
837
841
  path: z.ZodString;
838
- }, "strip", z.ZodTypeAny, {
842
+ }, "strict", z.ZodTypeAny, {
839
843
  path: string;
840
844
  }, {
841
845
  path: string;
@@ -982,4 +986,4 @@ interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
982
986
  */
983
987
  declare function createTracking<TRegistry extends TriggerRegistryConfig>(options: CreateTrackingOptions<TRegistry>): CreateTrackingResult<TRegistry>;
984
988
 
985
- export { type AutomaticEventName, ConsentBanner, 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, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, type TrackingProviderProps, TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, captureTrackingParamsFromLocation, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, getConsentState, setConsentState, useConsentState, useGclid, useTrackingParams };
989
+ export { type AutomaticEventName, ConsentBanner, 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, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, type TrackingProviderProps, TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, captureTrackingParamsFromLocation, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, getConsentState, setConsentState, useConsentState, useGclid, useTrackingParams };