Skip to main content
This example adds Sagepilot Web Push to a Next.js App Router application that already uses Auth.js. It covers the authenticated proof route, automatic connection after login, an explicit marketing-consent button, logout cleanup and retrying a failed endpoint revocation. If your application uses another authentication library, replace only the auth() and signOut() calls. Keep the same server-owned customer identity and Push lifecycle.
This example requires @sagepilot-ai/web-push-addon version 0.1.1 or newer. Complete the Push channel configuration before running it.

Files you will add

1. Install the dependencies and worker

Use the portable copy script from Deploy the service worker, and run it after install and before each build:

2. Configure the environment

Add the following values to .env.local and to your deployment environment:
Restart the Next.js development server after changing these values.

3. Sign the authenticated customer proof

Create src/lib/sagepilot-push-proof.ts:
The value in session.user.id must be your stable customer ID. Do not use a request-body customer ID, a browser-generated UUID, an FCM token or an ID that changes between logins. This example validates the 1–45-character limit for new integrations. Existing longer IDs are lookup-only; do not truncate them.

4. Expose the proof through the logged-in session

Create src/app/api/sagepilot/push-proof/route.ts:
Your Auth.js session callback must expose the canonical customer ID as session.user.id. If your auth library uses another field, map it on the server before calling createSagepilotPushProof(). Populate verifiedEmail and/or verifiedPhone from your backend’s verified account records in that callback, or load those records in this route. These are application-defined fields, not built-in Auth.js guarantees. Do not copy session.user.email unless your authentication flow verified it, and never accept contact values or verification flags from a client session-update request.
Before onboarding new customers, wire this verified-contact mapping. A new ID-only customer has no contact details in Sagepilot and can receive 403 when anonymous SDK push is disabled. An already identified customer may use an ID-only proof. Enable anonymous push only if your brand intentionally supports contactless customers; this signed-in example does not create guest sessions.
Add src/types/next-auth.d.ts when your application has not already extended the Auth.js session:
Then preserve your existing authentication configuration and map its stable account ID in the Auth.js session callback. For JWT sessions, token.sub is normally the authenticated user’s stable ID:
The callback above shows only the stable-ID mapping; implement the verified-contact mapping for your authentication provider before using this with new identified customers. If you use an Auth.js database adapter, map your adapter’s stable user.id instead. Do not replace it with an email address or a browser-provided value.

5. Own the browser lifecycle in one module

Create src/lib/sagepilot-push-client.ts:
The pending flag is intentionally scoped to the Push key. The add-on keeps a delete-only binding after a failed logout(), allowing the next page load to finish revocation before another customer is identified. The module stops new registration/renewal when logout starts and waits for outstanding calls before revoking. This example uses Auth.js’s full-page sign-out redirect to reset the module for the next login. Route account switching through that same logout flow; do not switch customers in place while old registration is running. Create src/components/sagepilot-push-controls.tsx:
Mount the controls from src/app/layout.tsx so every same-origin notification destination initializes the add-on and can flush destination_opened:
connectSagepilotPush() runs after login or a signed-in page reload. The component renews the 24-hour grant after 23 hours while visible, or on return to the foreground. Renewal errors stop automatic renewal and show Retry setup; inspect persistent authorization errors rather than repeatedly retrying them. It never opens the browser permission prompt. Only the visible button calls subscribe(). The UI checks saved consent as well as endpoint registration. An existing endpoint with marketing disabled still shows the opt-in button. A global opt-out stays paused; your app’s notification settings must obtain an explicit customer choice before restoring that master preference. Web opt-in does not change app marketing preferences.

7. Revoke Push before Auth.js logout

Create src/components/sign-out-button.tsx:
Render login and logout controls from a server page such as src/app/page.tsx:
After Auth.js completes login, Next.js renders the authenticated layout, the browser obtains a proof from the protected route and the add-on synchronizes any existing subscription. Logout attempts Sagepilot revocation before Auth.js clears the session; a temporary failure removes the local subscription and is retried on the next application load.

8. Verify the full flow

  1. Open /sagepilot-push/sagepilot-push-worker.js and confirm it returns JavaScript with status 200.
  2. Sign in with a newly created account and confirm the proof and SDK session requests succeed with verified contacts; the proof route must return 401 when signed out.
  3. Confirm the page shows Enable marketing notifications without opening a browser prompt automatically.
  4. Click the button, allow notifications and confirm saved web marketing consent before the UI shows Marketing notifications are enabled. Reload with an existing endpoint but marketing disabled and confirm it still offers opt-in. A global pause must stay paused.
  5. Trigger a business event through your event integration, verify its mapped customer and expected journey entry, then inspect the send. Also test a Campaign with a segment containing this customer. The Push add-on does not emit Add to Cart or other business events for you.
  6. Click the notification and confirm the same-origin destination opens.
  7. Verify received, opened and destination_opened separately in Push analytics.
  8. Sign out, send again and confirm that this browser endpoint is no longer eligible.
  9. Test a long-lived tab’s authorization renewal, sign-out during an in-flight connection and login to a different account. No old request should re-register the signed-out account after revocation.
For status meanings and failure codes, see the Web SDK API reference. For delivery troubleshooting, return to the complete Web Push guide.