@adhub-so/adhub-nextjs-sdk 0.1.1 → 0.3.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 +182 -80
- package/dist/index.cjs +261 -13
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +8 -0
- package/dist/index.d.ts +8 -0
- package/dist/index.js +261 -13
- package/dist/index.js.map +1 -1
- package/dist/server.cjs +16 -6
- package/dist/server.cjs.map +1 -1
- package/dist/server.d.cts +1 -0
- package/dist/server.d.ts +1 -0
- package/dist/server.js +16 -6
- package/dist/server.js.map +1 -1
- package/package.json +1 -1
- package/dist/chunk-NF56G46G.js +0 -140
- package/dist/chunk-NF56G46G.js.map +0 -1
- package/dist/testing.cjs +0 -149
- package/dist/testing.cjs.map +0 -1
- package/dist/testing.d.cts +0 -6
- package/dist/testing.d.ts +0 -6
- package/dist/testing.js +0 -72
- package/dist/testing.js.map +0 -1
- package/dist/types-DMUJO8Kj.d.cts +0 -62
- package/dist/types-DMUJO8Kj.d.ts +0 -62
package/README.md
CHANGED
|
@@ -1,30 +1,28 @@
|
|
|
1
1
|
# AdHub Next.js SDK
|
|
2
2
|
|
|
3
|
-
`@adhub-so/adhub-nextjs-sdk`
|
|
3
|
+
`@adhub-so/adhub-nextjs-sdk` captures Google Ads landing touchpoints, connects anonymous visits to authenticated SaaS users, and records page, product, and business events in Next.js applications.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
For most applications, integration consists of installing the package and rendering `AdHubComponent` once in the root layout. A Route Handler, custom `endpoint`, and manual `flush()` calls are not required.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Minimal setup
|
|
8
|
+
|
|
9
|
+
### 1. Install
|
|
8
10
|
|
|
9
11
|
```bash
|
|
10
12
|
npm install @adhub-so/adhub-nextjs-sdk
|
|
11
13
|
```
|
|
12
14
|
|
|
13
|
-
|
|
15
|
+
Add the public Project key to the application environment:
|
|
14
16
|
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
"dependencies": {
|
|
18
|
-
"@adhub-so/adhub-nextjs-sdk": "file:../adhub-nextjs-sdk"
|
|
19
|
-
}
|
|
20
|
-
}
|
|
17
|
+
```dotenv
|
|
18
|
+
NEXT_PUBLIC_ADHUB_PROJECT_KEY=<project-key>
|
|
21
19
|
```
|
|
22
20
|
|
|
23
|
-
|
|
21
|
+
The Project key is a public browser identifier. Never put an ingestion key or another server secret in a `NEXT_PUBLIC_*` variable.
|
|
24
22
|
|
|
25
|
-
###
|
|
23
|
+
### 2. Add the component
|
|
26
24
|
|
|
27
|
-
Render `AdHubComponent` once in the root layout
|
|
25
|
+
Render `AdHubComponent` once in the root layout:
|
|
28
26
|
|
|
29
27
|
```tsx
|
|
30
28
|
// app/layout.tsx
|
|
@@ -36,7 +34,6 @@ export default function RootLayout({ children }: { children: React.ReactNode })
|
|
|
36
34
|
<body>
|
|
37
35
|
<AdHubComponent
|
|
38
36
|
projectKey={process.env.NEXT_PUBLIC_ADHUB_PROJECT_KEY!}
|
|
39
|
-
endpoint="/api/adhub"
|
|
40
37
|
/>
|
|
41
38
|
{children}
|
|
42
39
|
</body>
|
|
@@ -45,85 +42,166 @@ export default function RootLayout({ children }: { children: React.ReactNode })
|
|
|
45
42
|
}
|
|
46
43
|
```
|
|
47
44
|
|
|
48
|
-
|
|
45
|
+
That completes the basic browser integration. With no `endpoint`, the SDK sends directly to `https://api.adhub.so`. It automatically captures landing parameters and pageviews, sends queued events, retries transient failures, and restores pending events after a reload.
|
|
46
|
+
|
|
47
|
+
If the AdHub project has a Google Ads website tag enabled, the SDK also loads that `AW-…` tag so Google can measure its own sessions and conversions. This is not AdSense, and it does not replace AdHub offline conversion uploads. If Microsoft Clarity is enabled for the project, the SDK loads that tag too. Set `waitForConsent` when those tags must wait for a consent choice. See [Google Ads website tag](#google-ads-website-tag) and [Microsoft Clarity](#microsoft-clarity).
|
|
49
48
|
|
|
50
|
-
|
|
49
|
+
Do not add a Route Handler or call `flush()` after every event for this setup.
|
|
50
|
+
|
|
51
|
+
### 3. Connect authenticated users
|
|
52
|
+
|
|
53
|
+
When the authenticated user is available, pass the application's existing stable user ID. No AdHub-specific identity table is required.
|
|
51
54
|
|
|
52
55
|
```tsx
|
|
53
56
|
<AdHubComponent
|
|
54
57
|
projectKey={process.env.NEXT_PUBLIC_ADHUB_PROJECT_KEY!}
|
|
55
|
-
endpoint="/api/adhub"
|
|
56
58
|
profile={{ profileId: user.id, email: user.email }}
|
|
57
59
|
/>
|
|
58
60
|
```
|
|
59
61
|
|
|
60
|
-
`
|
|
62
|
+
Use `profile={undefined}` while authentication is loading, the profile object after login, and `profile={null}` only after logout is confirmed. Changing from one non-null profile to another automatically creates a new browser identity boundary before identifying the next user.
|
|
61
63
|
|
|
62
|
-
|
|
64
|
+
## Common client events
|
|
63
65
|
|
|
64
|
-
|
|
65
|
-
// app/api/adhub/[...path]/route.ts
|
|
66
|
-
import { createRouteHandler } from "@adhub-so/adhub-nextjs-sdk/server";
|
|
66
|
+
Use `useAdHub()` in Client Components. Events are sent automatically; normal application code does not need `flush()`.
|
|
67
67
|
|
|
68
|
-
|
|
68
|
+
```tsx
|
|
69
|
+
"use client";
|
|
69
70
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
71
|
+
import { useAdHub } from "@adhub-so/adhub-nextjs-sdk";
|
|
72
|
+
|
|
73
|
+
export function PricingButton() {
|
|
74
|
+
const adhub = useAdHub();
|
|
75
|
+
|
|
76
|
+
return (
|
|
77
|
+
<button
|
|
78
|
+
onClick={() => adhub.behavior({
|
|
79
|
+
eventName: "pricing_cta_clicked",
|
|
80
|
+
properties: { plan: "growth" },
|
|
81
|
+
})}
|
|
82
|
+
>
|
|
83
|
+
Choose Growth
|
|
84
|
+
</button>
|
|
85
|
+
);
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
`behavior()` records non-sensitive product analytics and works for anonymous visitors. `track()` records a configured AdHub business event and requires an identified profile:
|
|
73
90
|
|
|
74
|
-
|
|
91
|
+
```ts
|
|
92
|
+
adhub.track({
|
|
93
|
+
eventType: "signup.completed",
|
|
94
|
+
eventId: `signup:${createdUser.id}`,
|
|
95
|
+
occurredAt: createdUser.createdAt,
|
|
96
|
+
});
|
|
75
97
|
```
|
|
76
98
|
|
|
77
|
-
|
|
99
|
+
Call this from the account-creation success path. Ordinary login only identifies
|
|
100
|
+
the profile; `identify()` never creates a signup event.
|
|
78
101
|
|
|
79
|
-
|
|
102
|
+
Browser payloads can be modified by users. Trusted payment, refund, subscription, and order facts should be sent from the server.
|
|
80
103
|
|
|
81
|
-
|
|
104
|
+
## Advanced configuration
|
|
82
105
|
|
|
83
|
-
|
|
84
|
-
"use client";
|
|
106
|
+
The minimal setup above does not require any of the following features. Use them only for a specific application requirement.
|
|
85
107
|
|
|
86
|
-
|
|
108
|
+
- [Google Ads website tag](#google-ads-website-tag) for consent, SPA page views, and the same-origin config proxy.
|
|
109
|
+
- [Microsoft Clarity](#microsoft-clarity) when the project enables Clarity session recordings.
|
|
110
|
+
- [First-party Route Handler](#first-party-route-handler) for a same-origin collection path, customer-edge geo headers, or a custom API target.
|
|
111
|
+
- [Capture before hydration](#capture-before-hydration) when application code removes attribution parameters before React hydrates.
|
|
112
|
+
- [Manual flush and queue control](#manual-flush-and-queue-control) for tests, diagnostics, or `autoFlush: false`.
|
|
113
|
+
- [Trusted server events](#trusted-server-events) for payments and other authoritative business facts.
|
|
114
|
+
- [OAuth signup attribution](#oauth-signup-attribution) when a callback must distinguish signup from normal login.
|
|
115
|
+
- [Attribution testing](#attribution-testing) for zero-write dashboard previews.
|
|
87
116
|
|
|
88
|
-
|
|
89
|
-
const adhub = useAdHub();
|
|
117
|
+
### Google Ads website tag
|
|
90
118
|
|
|
91
|
-
|
|
92
|
-
const currentProfileId = adhub.getState().profileId;
|
|
93
|
-
if (currentProfileId && currentProfileId !== userId) adhub.reset();
|
|
94
|
-
if (adhub.getState().profileId !== userId) {
|
|
95
|
-
adhub.identify({ profileId: userId });
|
|
96
|
-
}
|
|
119
|
+
After `init`, the SDK requests `GET /api/v1/saas/sdk/config`. When `googleAdsWebsiteTag.enabled` is true and `conversionId` is an `AW-…` id, it installs Google's website tag:
|
|
97
120
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
121
|
+
- An existing `window.gtag` and `dataLayer` are reused. Otherwise the SDK defines the standard `dataLayer` push helper.
|
|
122
|
+
- `https://www.googletagmanager.com/gtag/js?id=AW-…` is added once, marked with `data-adhub-gtag`. A script with the same `src` is left in place.
|
|
123
|
+
- `gtag('js', new Date())` runs once, and `gtag('config', conversionId)` runs once per id.
|
|
124
|
+
- The script stays loaded across client-side route changes. With `autoPageview` left on, those navigations also send a Google `page_view`.
|
|
125
|
+
- Injection is idempotent. `window.__ADHUB_GTAG__` records the installed ids, so a later `init` on the same page does not insert a second script or call `gtag('config')` again for an id that is already installed.
|
|
101
126
|
|
|
102
|
-
|
|
103
|
-
|
|
127
|
+
A disabled tag, a null conversion id, a non-OK response, or a network failure does not throw and does not block touchpoints, identity, pageviews, or events. The SDK writes an `[AdHub SDK]` console warning only when `debug` is on.
|
|
128
|
+
|
|
129
|
+
`waitForConsent` skips the config request, so neither this tag nor Microsoft Clarity is loaded. There is no consent callback. After the visitor allows the tags, call `init` again for the same project with `waitForConsent` omitted or `false` and the SDK loads them. A tag that was already injected is not removed.
|
|
130
|
+
|
|
131
|
+
```tsx
|
|
132
|
+
<AdHubComponent
|
|
133
|
+
projectKey={process.env.NEXT_PUBLIC_ADHUB_PROJECT_KEY!}
|
|
134
|
+
waitForConsent
|
|
135
|
+
/>
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Same-origin proxy mode must forward this GET. Export `GET` from the catch-all Route Handler as well as `POST` and `OPTIONS`. `script-src` must allow `https://www.googletagmanager.com` when the tag is enabled. Direct delivery to `https://api.adhub.so` does not need the Route Handler.
|
|
139
|
+
|
|
140
|
+
### Microsoft Clarity
|
|
141
|
+
|
|
142
|
+
The same `GET /api/v1/saas/sdk/config` response may include `clarity`. When `clarity.enabled` is true and `clarity.projectId` is the Clarity project id, the SDK installs Microsoft's tag once for the page:
|
|
143
|
+
|
|
144
|
+
```js
|
|
145
|
+
(function(c,l,a,r,i,t,y){
|
|
146
|
+
c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
|
|
147
|
+
t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
|
|
148
|
+
y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
|
|
149
|
+
})(window, document, "clarity", "script", PROJECT_ID);
|
|
104
150
|
```
|
|
105
151
|
|
|
106
|
-
|
|
152
|
+
- An existing `window.clarity` is reused. Otherwise the SDK defines the standard queue function.
|
|
153
|
+
- `https://www.clarity.ms/tag/<projectId>` is inserted once, before the first script tag (or appended when the page has none), and marked with `data-adhub-clarity`. A script whose `src` is already that URL is left in place. A Clarity script for a different project is also left in place; the SDK does not add a second tag.
|
|
154
|
+
- Injection is idempotent. `window.__ADHUB_CLARITY__` records `{ projectId }`, so a later `init` on the same page does not insert another script.
|
|
155
|
+
- `identify()` calls `clarity('identify', profileId)` when `window.clarity` is available. Only the AdHub profile id is sent. Email and name are not.
|
|
156
|
+
|
|
157
|
+
A disabled tag, a missing or invalid project id, a non-OK response, or a network failure does not throw and does not block touchpoints, identity, pageviews, or events. The SDK writes an `[AdHub SDK]` console warning only when `debug` is on.
|
|
158
|
+
|
|
159
|
+
`waitForConsent` skips the shared config request, so Clarity waits along with the Google Ads tag. `script-src` must allow `https://www.clarity.ms` when the tag is enabled. Clarity also sends its own beacons to `https://*.clarity.ms`.
|
|
160
|
+
|
|
161
|
+
### First-party Route Handler
|
|
162
|
+
|
|
163
|
+
This is an optional delivery mode, not a prerequisite for using the browser SDK. Direct delivery already gives AdHub the browser connection IP, User-Agent, and site Origin.
|
|
164
|
+
|
|
165
|
+
The optional Route Handler can provide:
|
|
166
|
+
|
|
167
|
+
- A first-party request path on the application's own origin.
|
|
168
|
+
- Reduced blocking by some third-party-domain filters, without promising to bypass every blocker.
|
|
169
|
+
- A browser-to-Next.js request that does not rely on cross-origin CORS.
|
|
170
|
+
- Vercel, Cloudflare, or CloudFront geo headers available at the customer's edge.
|
|
171
|
+
- A centralized self-hosted, regional, or test AdHub API target through `apiUrl`.
|
|
172
|
+
- A restricted proxy that accepts only supported SDK ingestion paths.
|
|
173
|
+
|
|
174
|
+
The tradeoff is an extra network hop, another Next.js server request, and an additional failure point. It requires an App Router server runtime and does not work with a purely static export. It also does not make browser events trusted and must not use an ingestion key.
|
|
107
175
|
|
|
108
176
|
```ts
|
|
109
|
-
adhub.
|
|
110
|
-
|
|
111
|
-
properties: { plan: "growth" },
|
|
112
|
-
});
|
|
177
|
+
// app/api/adhub/[...path]/route.ts
|
|
178
|
+
import { createRouteHandler } from "@adhub-so/adhub-nextjs-sdk/server";
|
|
113
179
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
currency: order.currency,
|
|
180
|
+
export const runtime = "nodejs";
|
|
181
|
+
|
|
182
|
+
const handler = createRouteHandler({
|
|
183
|
+
apiUrl: process.env.ADHUB_API_URL ?? "https://api.adhub.so",
|
|
119
184
|
});
|
|
185
|
+
|
|
186
|
+
export const { GET, POST, OPTIONS } = handler;
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Then opt the single browser initialization into that path:
|
|
190
|
+
|
|
191
|
+
```tsx
|
|
192
|
+
<AdHubComponent
|
|
193
|
+
projectKey={process.env.NEXT_PUBLIC_ADHUB_PROJECT_KEY!}
|
|
194
|
+
endpoint="/api/adhub"
|
|
195
|
+
/>
|
|
120
196
|
```
|
|
121
197
|
|
|
122
|
-
|
|
198
|
+
The handler preserves the original Origin, User-Agent, client IP, supported edge geo fields, Project key, idempotency key, SDK name, and SDK version. The real site Origin must still be allowed in the AdHub Project.
|
|
199
|
+
|
|
200
|
+
Do not configure only one half of proxy mode. Setting `endpoint="/api/adhub"` without deploying the matching catch-all Route Handler causes 404 responses and leaves requests in the retry queue.
|
|
123
201
|
|
|
124
|
-
|
|
202
|
+
### Capture before hydration
|
|
125
203
|
|
|
126
|
-
Next.js 15.3 and newer can initialize AdHub synchronously from `instrumentation-client.ts`. Use this
|
|
204
|
+
Next.js 15.3 and newer can initialize AdHub synchronously from `instrumentation-client.ts`. Use this only when application code may remove attribution query parameters before React hydrates.
|
|
127
205
|
|
|
128
206
|
```ts
|
|
129
207
|
// src/instrumentation-client.ts
|
|
@@ -131,15 +209,30 @@ import { initAdHub } from "@adhub-so/adhub-nextjs-sdk";
|
|
|
131
209
|
|
|
132
210
|
initAdHub({
|
|
133
211
|
projectKey: process.env.NEXT_PUBLIC_ADHUB_PROJECT_KEY!,
|
|
134
|
-
endpoint: "/api/adhub",
|
|
135
212
|
});
|
|
136
213
|
```
|
|
137
214
|
|
|
138
|
-
|
|
215
|
+
Top-level initialization captures and persists the landing touchpoint synchronously. Network delivery remains automatic and asynchronous. Add `endpoint: "/api/adhub"` only when the optional Route Handler is deployed.
|
|
139
216
|
|
|
140
|
-
|
|
217
|
+
### Manual flush and queue control
|
|
141
218
|
|
|
142
|
-
|
|
219
|
+
The SDK uses a persistent FIFO queue to preserve touchpoint, identity, and event order and to retry transient failures. With the default `autoFlush: true`, `init`, `identify`, `page`, `behavior`, and `track` automatically schedule delivery. It also retries when the browser comes online, the page is hidden, the page is left, and while pending events remain.
|
|
220
|
+
|
|
221
|
+
`flush()` only starts an immediate attempt to drain the current queue and lets the caller wait for that attempt:
|
|
222
|
+
|
|
223
|
+
```ts
|
|
224
|
+
const result = await adhub.flush();
|
|
225
|
+
|
|
226
|
+
console.log(result.sent);
|
|
227
|
+
console.log(result.failed);
|
|
228
|
+
console.log(result.remaining);
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
Use it explicitly only for automated tests, diagnostics, `autoFlush: false`, or a flow that needs to wait for the current delivery attempt before a full-page navigation. It is not required after `track()` or `behavior()`, and it is not a final-delivery guarantee.
|
|
232
|
+
|
|
233
|
+
### Trusted server events
|
|
234
|
+
|
|
235
|
+
Import trusted server functionality only from the server entry so ingestion credentials cannot enter the client module graph:
|
|
143
236
|
|
|
144
237
|
```ts
|
|
145
238
|
import { createAdHubServerClient } from "@adhub-so/adhub-nextjs-sdk/server";
|
|
@@ -160,11 +253,14 @@ await adhub.track({
|
|
|
160
253
|
});
|
|
161
254
|
```
|
|
162
255
|
|
|
163
|
-
`eventId` is required
|
|
256
|
+
`eventId` is required and acts as the idempotency key. Reuse the same ID when retrying the same business fact. The server `profileId` must match the stable ID used by the browser integration.
|
|
164
257
|
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
258
|
+
### Signup attribution
|
|
259
|
+
|
|
260
|
+
Send signup from the account-creation success path, database hook, or auth
|
|
261
|
+
webhook that owns that business fact. A shared OAuth callback can represent
|
|
262
|
+
either signup or login, so the SDK does not infer signup from callback or
|
|
263
|
+
identify activity:
|
|
168
264
|
|
|
169
265
|
```ts
|
|
170
266
|
import {
|
|
@@ -172,23 +268,29 @@ import {
|
|
|
172
268
|
readAdHubAnonymousId,
|
|
173
269
|
} from "@adhub-so/adhub-nextjs-sdk/server";
|
|
174
270
|
|
|
175
|
-
const adhub = createAdHubServerClient({
|
|
176
|
-
projectKey: process.env.ADHUB_PROJECT_KEY!,
|
|
177
|
-
ingestionKey: process.env.ADHUB_INGESTION_KEY!,
|
|
178
|
-
});
|
|
179
|
-
|
|
180
271
|
await adhub.track({
|
|
181
272
|
eventType: process.env.ADHUB_SIGNUP_EVENT_TYPE_ID!,
|
|
182
|
-
profileId:
|
|
183
|
-
anonymousId: readAdHubAnonymousId(
|
|
184
|
-
|
|
185
|
-
|
|
273
|
+
profileId: createdUser.id,
|
|
274
|
+
anonymousId: readAdHubAnonymousId(
|
|
275
|
+
request.headers.get("cookie"),
|
|
276
|
+
process.env.ADHUB_PROJECT_KEY!,
|
|
277
|
+
) ?? undefined,
|
|
278
|
+
eventId: `signup:${createdUser.id}`,
|
|
279
|
+
occurredAt: createdUser.created_at,
|
|
186
280
|
});
|
|
187
281
|
```
|
|
188
282
|
|
|
189
|
-
|
|
283
|
+
The SDK keeps one generic `track()` API. When this AdHub event is bound to a
|
|
284
|
+
Google Ads conversion action whose category is `SIGNUP`, AdHub automatically
|
|
285
|
+
treats the event as a once-per-profile fact. Later login callbacks cannot
|
|
286
|
+
reattribute or upload the signup again, even if application code sends a new
|
|
287
|
+
`eventId`. The account creation timestamp remains the correct `occurredAt` for
|
|
288
|
+
normal retries and prevents a historical account from being attributed to a
|
|
289
|
+
newer ad click.
|
|
290
|
+
|
|
291
|
+
### Attribution testing
|
|
190
292
|
|
|
191
|
-
|
|
293
|
+
The dashboard can generate zero-write preview envelopes from the explicit testing entry:
|
|
192
294
|
|
|
193
295
|
```ts
|
|
194
296
|
import { createAttributionTestEnvelopes } from "@adhub-so/adhub-nextjs-sdk/testing";
|
|
@@ -200,6 +302,6 @@ This helper does not initialize browser tracking, modify storage, or send networ
|
|
|
200
302
|
|
|
201
303
|
- `@adhub-so/adhub-nextjs-sdk`: `AdHubComponent`, `initAdHub`, `useAdHub`, and client-side types.
|
|
202
304
|
- `@adhub-so/adhub-nextjs-sdk/server`: `createRouteHandler`, `createAdHubServerClient`, server payload helpers, errors, and server types.
|
|
203
|
-
- `@adhub-so/adhub-nextjs-sdk/testing`:
|
|
305
|
+
- `@adhub-so/adhub-nextjs-sdk/testing`: attribution-test envelope helpers and types.
|
|
204
306
|
|
|
205
|
-
|
|
307
|
+
This package targets Next.js. Browser operations stay behind the component, initialization entry, and client Hook; it does not publish a global IIFE or generic singleton event functions.
|