@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 CHANGED
@@ -1,30 +1,28 @@
1
1
  # AdHub Next.js SDK
2
2
 
3
- `@adhub-so/adhub-nextjs-sdk` is AdHub's first-party SDK for Next.js. It captures Google Ads landing touchpoints, maintains anonymous and authenticated identity, records page and product behavior, sends browser business events, and proxies requests through a Next.js Route Handler so AdHub receives the original browser IP, user agent, and edge geo headers.
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
- This package targets Next.js only. It does not publish a framework-neutral browser entry, SPA bootstrap API, or global IIFE bundle.
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
- ## Install
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
- For a local sibling checkout:
15
+ Add the public Project key to the application environment:
14
16
 
15
- ```json
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
- ## App Router setup
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
- ### 1. Add the component
23
+ ### 2. Add the component
26
24
 
27
- Render `AdHubComponent` once in the root layout. A relative `endpoint` sends browser requests through your own Next.js origin, which improves delivery and preserves the real browser context through the Route Handler in the next step.
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
- The Project key is a public browser identifier. Never pass an ingestion key or another server secret to `AdHubComponent` or a `NEXT_PUBLIC_*` environment variable.
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
- If authenticated profile data is already available to the layout, it can be supplied as a serializable prop:
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
- `profileId` can be passed directly when no other profile fields are needed. Changing directly from one non-null profile to another rotates the browser identity boundary before identifying the next user. Passing `null` resets the authenticated identity while retaining a new anonymous browser identity.
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
- ### 2. Add the Route Handler
64
+ ## Common client events
63
65
 
64
- ```ts
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
- export const runtime = "nodejs";
68
+ ```tsx
69
+ "use client";
69
70
 
70
- const handler = createRouteHandler({
71
- apiUrl: process.env.ADHUB_API_URL ?? "https://api.adhub.so",
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
- export const { POST, OPTIONS } = handler;
91
+ ```ts
92
+ adhub.track({
93
+ eventType: "signup.completed",
94
+ eventId: `signup:${createdUser.id}`,
95
+ occurredAt: createdUser.createdAt,
96
+ });
75
97
  ```
76
98
 
77
- The handler only forwards the supported SDK ingestion paths. It carries the original `Origin`, `User-Agent`, client IP, country, region, city, project key, idempotency key, SDK name, and SDK version to AdHub. It does not proxy general SaaS APIs.
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
- ### 3. Track from Client Components
102
+ Browser payloads can be modified by users. Trusted payment, refund, subscription, and order facts should be sent from the server.
80
103
 
81
- `useAdHub()` is the client API for Next.js Client Components. It exposes a reactive `state` plus identity, page, behavior, event, reset, and flush actions.
104
+ ## Advanced configuration
82
105
 
83
- ```tsx
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
- import { useAdHub } from "@adhub-so/adhub-nextjs-sdk";
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
- export function SignupButton({ userId }: { userId: string }) {
89
- const adhub = useAdHub();
117
+ ### Google Ads website tag
90
118
 
91
- async function completeSignup() {
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
- adhub.track({ eventType: "signup.completed" });
99
- await adhub.flush();
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
- return <button onClick={() => void completeSignup()}>Create account</button>;
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
- Use `behavior()` for non-sensitive product analytics and `track()` for configured AdHub business events:
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.behavior({
110
- eventName: "pricing_cta_clicked",
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
- adhub.track({
115
- eventType: "purchase",
116
- eventId: `order:${order.id}`,
117
- value: order.total,
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
- Browser `track()` requires an identified profile. Trusted payment, refund, and subscription facts should normally be sent from the server instead.
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
- ## Capture before hydration
202
+ ### Capture before hydration
125
203
 
126
- Next.js 15.3 and newer can initialize AdHub synchronously from `instrumentation-client.ts`. Use this advanced setup when application code may remove attribution query parameters before React hydrates. In that case, use `initAdHub()` here instead of relying on `AdHubComponent` to initialize.
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
- Only synchronous top-level work in `instrumentation-client.ts` is guaranteed to complete before hydration. `initAdHub()` captures and persists the landing touchpoint synchronously; network delivery remains queued and asynchronous.
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
- ## Server events
217
+ ### Manual flush and queue control
141
218
 
142
- Import trusted server functionality only from `@adhub-so/adhub-nextjs-sdk/server` so ingestion credentials cannot enter the client module graph.
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 for trusted server events and is used as the idempotency key. Reuse the same ID for retries of the same business fact.
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
- When a trusted event is sent during an OAuth callback, pass the anonymous ID
166
- that this SDK persisted in the browser cookie. AdHub will claim that anonymous
167
- identity for the profile before attributing the event:
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: user.id,
183
- anonymousId: readAdHubAnonymousId(request.headers.get("cookie"), process.env.ADHUB_PROJECT_KEY!),
184
- eventId: `signup:${user.id}`,
185
- occurredAt: user.created_at,
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
- ## Attribution testing
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
- AdHub's dashboard can create zero-write preview envelopes through the explicit testing entry:
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`: the dashboard attribution-test envelope helper and its types.
305
+ - `@adhub-so/adhub-nextjs-sdk/testing`: attribution-test envelope helpers and types.
204
306
 
205
- The package does not expose `./browser`, redundant framework subpaths, a global IIFE, a client factory, or generic singleton event functions. Browser operations stay behind the Next.js component, initialization entry, and client Hook.
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.