@aranova/tracking-next 0.5.0 → 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 +150 -0
- package/dist/index.d.mts +194 -112
- package/dist/index.d.ts +194 -112
- package/dist/index.js +183 -73
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +183 -73
- package/dist/index.mjs.map +1 -1
- package/dist/middleware.js +97 -66
- package/dist/middleware.js.map +1 -1
- package/dist/middleware.mjs +98 -67
- package/dist/middleware.mjs.map +1 -1
- package/dist/server.js +97 -66
- package/dist/server.js.map +1 -1
- package/dist/server.mjs +98 -67
- package/dist/server.mjs.map +1 -1
- package/package.json +3 -2
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
|
+
|