auth() and signOut() calls. Keep the same server-owned customer identity and Push lifecycle.
Files you will add
1. Install the dependencies and worker
2. Configure the environment
Add the following values to.env.local and to your deployment environment:
3. Sign the authenticated customer proof
Createsrc/lib/sagepilot-push-proof.ts:
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
Createsrc/app/api/sagepilot/push-proof/route.ts:
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.
Expose a typed customer ID from Auth.js
Expose a typed customer ID from Auth.js
Add Then preserve your existing authentication configuration and map its stable account ID in the Auth.js session callback. For JWT sessions, 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
src/types/next-auth.d.ts when your application has not already extended the Auth.js session:token.sub is normally the authenticated user’s stable ID:user.id instead. Do not replace it with an email address or a browser-provided value.5. Own the browser lifecycle in one module
Createsrc/lib/sagepilot-push-client.ts:
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.
6. Connect after login and show explicit consent
Createsrc/components/sagepilot-push-controls.tsx:
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
Createsrc/components/sign-out-button.tsx:
src/app/page.tsx:
8. Verify the full flow
- Open
/sagepilot-push/sagepilot-push-worker.jsand confirm it returns JavaScript with status200. - Sign in with a newly created account and confirm the proof and SDK session requests succeed with verified contacts; the proof route must return
401when signed out. - Confirm the page shows Enable marketing notifications without opening a browser prompt automatically.
- 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.
- 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.
- Click the notification and confirm the same-origin destination opens.
- Verify
received,openedanddestination_openedseparately in Push analytics. - Sign out, send again and confirm that this browser endpoint is no longer eligible.
- 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.