segment-cdp

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