docs: align integration snippets with current core API

vklimontovich · vklimontovich · commit 339d2c1bdde3 · 2026-02-25T14:16:38.000-05:00
diff --git a/README.md b/README.md
@@ -48,7 +48,7 @@ import { segmentBackend } from "@nextlytics/core/backends/segment";
 // Optional: import your auth library to track authenticated users
 import { auth } from "./lib/auth"; // next-auth
 
-export const { middleware, handlers, analytics } = Nextlytics({
+export const { middleware, analytics } = Nextlytics({
   backends: [
     segmentBackend({
       writeKey: process.env.SEGMENT_WRITE_KEY!,
diff --git a/packages/core/src/plugins/vercel-geo.ts b/packages/core/src/plugins/vercel-geo.ts
@@ -26,7 +26,7 @@ export type VercelGeoPluginOptions = {
  * ```ts
  * import { vercelGeoPlugin } from "@nextlytics/core/plugins/vercel-geo";
  *
- * export const { middleware, handlers } = Nextlytics({
+ * export const { middleware } = Nextlytics({
  *   plugins: [vercelGeoPlugin()],
  *   // ...
  * });
diff --git a/packages/website/src/copy/index.ts b/packages/website/src/copy/index.ts
@@ -47,7 +47,7 @@ export function configSnippet(opts: ConfigSnippetOptions): string {
     "// Optional: import your auth library to track authenticated users",
     authImport,
     "",
-    "export const { middleware, handlers, analytics } = Nextlytics({",
+    "export const { middleware, analytics } = Nextlytics({",
     "  backends: [",
     opts.backendConfig,
     "  ],",
diff --git a/packages/website/src/copy/integrations/clickhouse/documentation.mdx b/packages/website/src/copy/integrations/clickhouse/documentation.mdx
@@ -4,7 +4,7 @@
 import { Nextlytics } from "@nextlytics/core/server";
 import { clickhouseBackend } from "@nextlytics/core/backends/clickhouse";
 
-export const { middleware, handlers, analytics } = Nextlytics({
+export const { middleware, analytics } = Nextlytics({
   backends: [
     clickhouseBackend({
       // Required. ClickHouse HTTP API URL.
@@ -70,11 +70,11 @@ On first use, if the table doesn't exist, Nextlytics prints the required SQL. Th
 
 - **ReplacingMergeTree** - enables deduplication for updates
 - **PARTITION BY month** - optimal partition size for analytics
-- **ORDER BY event_id** - enables efficient updates via insert
+- **ORDER BY (timestamp, event_id)** - enables efficient time-range queries and updates
 
 ```sql
 CREATE TABLE IF NOT EXISTS default.analytics (event_id String, timestamp DateTime64(3))
-ENGINE = ReplacingMergeTree() PARTITION BY toYYYYMM(timestamp) ORDER BY event_id;
+ENGINE = ReplacingMergeTree() PARTITION BY toYYYYMM(timestamp) ORDER BY (timestamp, event_id);
 
 ALTER TABLE default.analytics ADD COLUMN IF NOT EXISTS parent_event_id Nullable(String);
 ALTER TABLE default.analytics ADD COLUMN IF NOT EXISTS type LowCardinality(String);
diff --git a/packages/website/src/copy/integrations/debug-logging/documentation.mdx b/packages/website/src/copy/integrations/debug-logging/documentation.mdx
@@ -4,7 +4,7 @@
 import { Nextlytics } from "@nextlytics/core/server";
 import { loggingBackend } from "@nextlytics/core/backends/logging";
 
-export const { middleware, handlers, analytics } = Nextlytics({
+export const { middleware, analytics } = Nextlytics({
   backends: [loggingBackend()],
 });
 ```
@@ -62,7 +62,7 @@ import { Nextlytics } from "@nextlytics/core/server";
 import { loggingBackend } from "@nextlytics/core/backends/logging";
 import { posthogBackend } from "@nextlytics/core/backends/posthog";
 
-export const { middleware, handlers, analytics } = Nextlytics({
+export const { middleware, analytics } = Nextlytics({
   backends: [
     // Always log in development
     ...(process.env.NODE_ENV === "development" ? [loggingBackend()] : []),
@@ -89,7 +89,7 @@ Use in tests to verify events are being tracked correctly:
 
 ```typescript
 // In your test setup
-const { middleware, handlers, analytics } = Nextlytics({
+const { middleware, analytics } = Nextlytics({
   backends: [loggingBackend()],
 });
 
diff --git a/packages/website/src/copy/integrations/google-analytics/documentation.mdx b/packages/website/src/copy/integrations/google-analytics/documentation.mdx
@@ -4,14 +4,16 @@
 import { Nextlytics } from "@nextlytics/core/server";
 import { googleAnalyticsBackend } from "@nextlytics/core/backends/ga";
 
-export const { middleware, handlers, analytics } = Nextlytics({
+export const { middleware, analytics } = Nextlytics({
   backends: [
     googleAnalyticsBackend({
       // Required. Your GA4 Measurement ID.
       // Find it: GA4 Admin -> Data Streams -> Your Stream -> Measurement ID
       measurementId: "G-XXXXXXXXXX",
 
-      // Required for server-side events (everything except pageView).
+      // Optional but recommended for Measurement Protocol delivery.
+      // Required for server-origin custom events, and for client-origin custom
+      // events when preferClientSideForClientEvents is false.
       // Find it: GA4 Admin -> Data Streams -> Measurement Protocol API secrets
       apiSecret: "your-api-secret",
 
@@ -23,6 +25,11 @@ export const { middleware, handlers, analytics } = Nextlytics({
       // - "gaCookie" (default): Use _ga cookie set by gtag.js, fall back to anonymousUserId
       // - "anonymousUserId": Always use Nextlytics anonymousUserId
       clientIdSource: "gaCookie",
+
+      // Optional. For client-origin custom events:
+      // - true (default): send via gtag in browser
+      // - false: send via Measurement Protocol (requires apiSecret)
+      preferClientSideForClientEvents: true,
     }),
   ],
 });
@@ -34,7 +41,8 @@ Google Analytics requires page views to come from the browser. It needs to run J
 browser metadata and measure engagement. Because of this limitation, Nextlytics uses a **hybrid approach**:
 
 - **Page views** are sent client-side via a JavaScript snippet
-- **All other events** are sent server-side via the Measurement Protocol
+- **Server-origin custom events** are sent via Measurement Protocol when `apiSecret` is configured
+- **Client-origin custom events** are sent client-side by default
 
 ### Page View Events
 
@@ -46,9 +54,15 @@ The snippet maps to GA4's `page_view` event.
 
 ### Other Events
 
-All other events (purchases, form submissions, custom events) are sent server-side via the
-[Measurement Protocol](https://developers.google.com/analytics/devguides/collection/protocol/ga4).
-This means 100% delivery rate - no ad blockers can interfere.
+Custom events (purchases, form submissions, API/server events) can be delivered in two modes:
+
+- Server-origin events use
+  [Measurement Protocol](https://developers.google.com/analytics/devguides/collection/protocol/ga4)
+  when `apiSecret` is configured.
+- Client-origin events use `gtag('event', ...)` by default.
+
+To force Measurement Protocol for client-origin events too, set
+`preferClientSideForClientEvents: false` and provide `apiSecret`.
 
 ```typescript
 const { analytics } = await import("./nextlytics");
@@ -75,7 +89,7 @@ is identified, Nextlytics sends only `user_id` to GA4. For privacy, email, name,
 Custom traits are sent as user properties.
 
 ```typescript
-export const { middleware, handlers, analytics } = Nextlytics({
+export const { middleware, analytics } = Nextlytics({
   callbacks: {
     getUser: async (ctx) => {
       const session = await getSession(ctx);
@@ -101,7 +115,7 @@ export const { middleware, handlers, analytics } = Nextlytics({
   (gtag.js hasn't run). Nextlytics falls back to `anonymousUserId` for that request. Subsequent requests use
   the real `_ga` cookie.
 - **Page views require JavaScript.** This is a GA limitation, not Nextlytics.
-- **Real-time reports may be delayed.** Server-side events can take a few minutes to appear in GA4.
+- **Real-time reports may be delayed.** Measurement Protocol events can take a few minutes to appear in GA4.
 
 ## Debugging
 
diff --git a/packages/website/src/copy/integrations/google-tag-manager/documentation.mdx b/packages/website/src/copy/integrations/google-tag-manager/documentation.mdx
@@ -4,7 +4,7 @@
 import { Nextlytics } from "@nextlytics/core/server";
 import { googleTagManagerBackend } from "@nextlytics/core/backends/gtm";
 
-export const { middleware, handlers, analytics } = Nextlytics({
+export const { middleware, analytics } = Nextlytics({
   backends: [
     googleTagManagerBackend({
       // Required. Your GTM Container ID.
@@ -37,10 +37,12 @@ dataLayer.push({
   eventId: "nl_abc123",
   page_path: "/products",
   page_title: "Products",
-  page_location: "https://example.com/products",
+  page_location: "example.com/products",
 });
 ```
 
+`page_location` is built from `serverContext.host + serverContext.path`.
+
 ### Custom Events
 
 Custom events are converted to snake_case and pushed to `dataLayer`:
@@ -66,7 +68,7 @@ dataLayer.push({
 When a user is identified, their data is pushed to `dataLayer`:
 
 ```typescript
-export const { middleware, handlers, analytics } = Nextlytics({
+export const { middleware, analytics } = Nextlytics({
   callbacks: {
     getUser: async (ctx) => {
       const session = await getSession(ctx);
diff --git a/packages/website/src/copy/integrations/neon/documentation.mdx b/packages/website/src/copy/integrations/neon/documentation.mdx
@@ -4,7 +4,7 @@
 import { Nextlytics } from "@nextlytics/core/server";
 import { neonBackend } from "@nextlytics/core/backends/neon";
 
-export const { middleware, handlers, analytics } = Nextlytics({
+export const { middleware, analytics } = Nextlytics({
   backends: [
     neonBackend({
       // Required. Your Neon database URL.
diff --git a/packages/website/src/copy/integrations/posthog/documentation.mdx b/packages/website/src/copy/integrations/posthog/documentation.mdx
@@ -4,7 +4,7 @@
 import { Nextlytics } from "@nextlytics/core/server";
 import { posthogBackend } from "@nextlytics/core/backends/posthog";
 
-export const { middleware, handlers, analytics } = Nextlytics({
+export const { middleware, analytics } = Nextlytics({
   backends: [
     posthogBackend({
       // Required. Your PostHog project API key.
@@ -90,7 +90,7 @@ When a user is identified via `callbacks.getUser`, their `userId` becomes the `d
 traits are sent via PostHog's `$set` mechanism:
 
 ```typescript
-export const { middleware, handlers, analytics } = Nextlytics({
+export const { middleware, analytics } = Nextlytics({
   callbacks: {
     getUser: async (ctx) => {
       const session = await getSession(ctx);
diff --git a/packages/website/src/copy/integrations/segment/documentation.mdx b/packages/website/src/copy/integrations/segment/documentation.mdx
@@ -4,7 +4,7 @@
 import { Nextlytics } from "@nextlytics/core/server";
 import { segmentBackend } from "@nextlytics/core/backends/segment";
 
-export const { middleware, handlers, analytics } = Nextlytics({
+export const { middleware, analytics } = Nextlytics({
   backends: [
     segmentBackend({
       // Required. Your Segment write key.
@@ -41,7 +41,7 @@ All events are sent server-side via Segment's HTTP Tracking API. This means:
 
 ### Page Views
 
-Page views are sent via `/v1/page`:
+Page views are sent in a batch to `/v1/batch` with `type: "page"`:
 
 ```typescript
 // Nextlytics
@@ -62,7 +62,7 @@ await api.sendEvent("pageView");
 
 ### Custom Events
 
-All other events are sent via `/v1/track`:
+All other events are sent in a batch to `/v1/batch` with `type: "track"`:
 
 ```typescript
 await api.sendEvent("purchase", {
@@ -113,7 +113,7 @@ Segment's context object is populated with available data:
 Users are identified via `anonymousId` and `userId`:
 
 ```typescript
-export const { middleware, handlers, analytics } = Nextlytics({
+export const { middleware, analytics } = Nextlytics({
   callbacks: {
     getUser: async (ctx) => {
       const session = await getSession(ctx);
diff --git a/packages/website/src/copy/integrations/supabase/documentation.mdx b/packages/website/src/copy/integrations/supabase/documentation.mdx
@@ -6,7 +6,7 @@ import { postgrestBackend } from "@nextlytics/core/backends/postgrest";
 // Optional: import Supabase client to track authenticated users
 import { createClient } from "@/lib/supabase/server";
 
-export const { middleware, handlers, analytics } = Nextlytics({
+export const { middleware, analytics } = Nextlytics({
   backends: [
     postgrestBackend({
       // Required. Your Supabase project URL + /rest/v1
@@ -54,25 +54,28 @@ Create the analytics table in Supabase SQL editor:
 ```sql
 CREATE TABLE IF NOT EXISTS analytics (
   event_id TEXT PRIMARY KEY,
+  timestamp TIMESTAMPTZ NOT NULL,
   type TEXT NOT NULL,
-  collected_at TIMESTAMPTZ NOT NULL,
-  anonymous_user_id TEXT,
-  user_id TEXT,
-  path TEXT,
   host TEXT,
+  path TEXT,
   method TEXT,
-  ip TEXT,
+  user_id TEXT,
+  anonymous_user_id TEXT,
+  user_email TEXT,
+  user_name TEXT,
+  ip INET,
   referer TEXT,
   user_agent TEXT,
   locale TEXT,
-  properties JSONB,
+  parent_event_id TEXT,
   server_context JSONB,
   client_context JSONB,
-  user_context JSONB
+  user_traits JSONB,
+  properties JSONB
 );
 
 -- Indexes for common queries
-CREATE INDEX idx_analytics_collected_at ON analytics(collected_at DESC);
+CREATE INDEX idx_analytics_timestamp ON analytics(timestamp DESC);
 CREATE INDEX idx_analytics_type ON analytics(type);
 CREATE INDEX idx_analytics_user_id ON analytics(user_id);
 
@@ -92,23 +95,26 @@ If you're using Prisma, add this model to your `schema.prisma` instead:
 ```prisma
 model Analytics {
   event_id          String   @id
+  timestamp         DateTime @db.Timestamptz()
   type              String
-  collected_at      DateTime @db.Timestamptz()
-  anonymous_user_id String?
-  user_id           String?
-  path              String?
   host              String?
+  path              String?
   method            String?
-  ip                String?
+  user_id           String?
+  anonymous_user_id String?
+  user_email        String?
+  user_name         String?
+  ip                String?  @db.Inet
   referer           String?
   user_agent        String?
   locale            String?
-  properties        Json?    @db.JsonB
+  parent_event_id   String?
   server_context    Json?    @db.JsonB
   client_context    Json?    @db.JsonB
-  user_context      Json?    @db.JsonB
+  user_traits       Json?    @db.JsonB
+  properties        Json?    @db.JsonB
 
-  @@index([collected_at(sort: Desc)])
+  @@index([timestamp(sort: Desc)])
   @@index([type])
   @@index([user_id])
   @@map("analytics")
@@ -146,14 +152,14 @@ const { data } = await supabase
   .from("analytics")
   .select("path, count")
   .eq("type", "pageView")
-  .gte("collected_at", new Date().toISOString().split("T")[0]);
+  .gte("timestamp", new Date().toISOString().split("T")[0]);
 
 // User events
 const { data: userEvents } = await supabase
   .from("analytics")
   .select("*")
   .eq("user_id", "user_123")
-  .order("collected_at", { ascending: false });
+  .order("timestamp", { ascending: false });
 ```
 
 ## Real-time Subscriptions
diff --git a/packages/website/src/copy/integrations/vercel-geo/documentation.mdx b/packages/website/src/copy/integrations/vercel-geo/documentation.mdx

Original file line number	Diff line number	Diff line change
`@@ -26,7 +26,7 @@ export type VercelGeoPluginOptions = {`
`26`	`26`	* ```ts
`27`	`27`	`* import { vercelGeoPlugin } from "@nextlytics/core/plugins/vercel-geo";`
`28`	`28`	`*`
`29`		`- * export const { middleware, handlers } = Nextlytics({`
	`29`	`+ * export const { middleware } = Nextlytics({`
`30`	`30`	`* plugins: [vercelGeoPlugin()],`
`31`	`31`	`* // ...`
`32`	`32`	`* });`