Segment CDP
Expert patterns for Segment Customer Data Platform including Analytics.js, server-side tracking, tracking plans with Protocols, identity resolution, destinations configuration, and data governance best practices.
Patterns
Analytics.js Browser Integration
Client-side tracking with Analytics.js. Include track, identify, page, and group calls. Anonymous ID persists until identify merges with user.
// Next.js - Analytics provider component // lib/segment.ts import { AnalyticsBrowser } from '@segment/analytics-next';
export const analytics = AnalyticsBrowser.load({ writeKey: process.env.NEXT_PUBLIC_SEGMENT_WRITE_KEY!, });
// Typed event helpers export interface UserTraits { email?: string; name?: string; plan?: 'free' | 'pro' | 'enterprise'; createdAt?: string; company?: { id: string; name: string; }; }
export function identify(userId: string, traits?: UserTraits) { analytics.identify(userId, traits); }
export function track<T extends Record<string, any>>( event: string, properties?: T ) { analytics.track(event, properties); }
export function page(name?: string, properties?: Record<string, any>) { analytics.page(name, properties); }
export function group(groupId: string, traits?: Record<string, any>) { analytics.group(groupId, traits); }
// React hook for analytics // hooks/useAnalytics.ts import { useEffect } from 'react'; import { usePathname, useSearchParams } from 'next/navigation'; import { analytics, page } from '@/lib/segment';
export function usePageTracking() { const pathname = usePathname(); const searchParams = useSearchParams();
useEffect(() => { // Track page view on route change page(pathname, { path: pathname, search: searchParams.toString(), url: window.location.href, title: document.title, }); }, [pathname, searchParams]); }
// Usage in _app.tsx or layout.tsx function RootLayout({ children }) { usePageTracking();
return <html>{children}</html>; }
// Event tracking in components function PricingButton({ plan }: { plan: string }) { const handleClick = () => { track('Plan Selected', { plan_name: plan, page: 'pricing', source: 'pricing_page', }); };
return <button onClick={handleClick}>Select {plan}</button>; }
// Identify on auth function onUserLogin(user: User) { identify(user.id, { email: user.email, name: user.name, plan: user.plan, createdAt: user.createdAt, });
track('User Signed In', { method: 'email', }); }
Context
- browser tracking
- website analytics
- client-side events
Server-Side Tracking with Node.js
High-performance server-side tracking using @segment/analytics-node. Non-blocking with internal batching. Essential for backend events, webhooks, and sensitive data.
// lib/segment-server.ts import { Analytics } from '@segment/analytics-node';
// Initialize once const analytics = new Analytics({ writeKey: process.env.SEGMENT_WRITE_KEY!, flushAt: 20, // Batch size before flush flushInterval: 10000, // Flush every 10 seconds });
// Typed server-side tracking export interface ServerContext { ip?: string; userAgent?: string; locale?: string; }
export function serverIdentify( userId: string, traits: Record<string, any>, context?: ServerContext ) { analytics.identify({ userId, traits, context: { ip: context?.ip, userAgent: context?.userAgent, locale: context?.locale, }, }); }
export function serverTrack( userId: string, event: string, properties?: Record<string, any>, context?: ServerContext ) { analytics.track({ userId, event, properties, timestamp: new Date(), context: { ip: context?.ip, userAgent: context?.userAgent, }, }); }
// Flush on shutdown export async function closeAnalytics() { await analytics.closeAndFlush(); }
// Usage in API routes // app/api/webhooks/stripe/route.ts export async function POST(req: Request) { const event = await req.json();
switch (event.type) { case 'checkout.session.completed': const session = event.data.object;
serverTrack(
session.client_reference_id,
'Order Completed',
{
order_id: session.id,
total: session.amount_total / 100,
currency: session.currency,
payment_method: session.payment_method_types[0],
},
{ ip: req.headers.get('x-forwarded-for') || undefined }
);
// Also update user traits
serverIdentify(session.client_reference_id, {
total_spent: session.amount_total / 100,
last_purchase_date: new Date().toISOString(),
});
break;
case 'customer.subscription.created':
serverTrack(
event.data.object.metadata.user_id,
'Subscription Started',
{
plan: event.data.object.items.data[0].price.nickname,
amount: event.data.object.items.data[0].price.unit_amount / 100,
interval: event.data.object.items.data[0].price.recurring.interval,
}
);
break;
}
return new Response('ok'); }
// Graceful shutdown process.on('SIGTERM', async () => { await closeAnalytics(); process.exit(0); });
Context
- server-side tracking
- backend events
- webhook processing
Tracking Plan Design
Design event schemas using Object + Action naming convention. Define required properties, types, and validation rules. Connect to Protocols for enforcement.
// Tracking plan definition (conceptual YAML structure) // This maps to Segment Protocols configuration /* tracking_plan: display_name: "MyApp Tracking Plan" rules: events: - name: "User Signed Up" description: "User completed registration" rules: required: - signup_method properties: signup_method: type: string enum: [email, google, github] referral_code: type: string utm_source: type: string
- name: "Product Viewed"
description: "User viewed a product page"
rules:
required:
- product_id
- product_name
properties:
product_id:
type: string
product_name:
type: string
category:
type: string
price:
type: number
currency:
type: string
default: USD
- name: "Order Completed"
description: "User completed a purchase"
rules:
required:
- order_id
- total
- products
properties:
order_id:
type: string
total:
type: number
currency:
type: string
products:
type: array
items:
type: object
properties:
product_id: { type: string }
name: { type: string }
price: { type: number }
quantity: { type: integer }
identify:
traits:
- name: email
type: string
required: true
- name: name
type: string
- name: plan
type: string
enum: [free, pro, enterprise]
- name: company
type: object
properties:
id: { type: string }
name: { type: string }
*/
// TypeScript implementation with type safety // types/segment-events.ts export interface TrackingEvents { 'User Signed Up': { signup_method: 'email' | 'google' | 'github'; referral_code?: string; utm_source?: string; };
'Product Viewed': { product_id: string; product_name: string; category?: string; price?: number; currency?: string; };
'Order Completed': { order_id: string; total: numb