back
loading skill details...
Expert patterns for Segment Customer Data Platform including
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 {children};
}
// Event tracking in components
function PricingButton({ plan }: { plan: string }) {
const handleClick = () => {
track('Plan Selected', {
plan_name: plan,
page: 'pricing',
source: 'pricing_page',
});
};
return Select {plan};
}
// 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: number;
currency?: string;
products: Array<{
product_id: string;
name: string;
price: number;
quantity: number;
}>;
};
'Feature Used': {
feature_name: string;
usage_count?: number;
};
}
// Type-safe track function
export function trackEvent(
event: T,
properties: TrackingEvents[T]
) {
analytics.track(event, properties);
}
// Usage - compile-time type checking
trackEvent('Order Completed', {
order_id: 'ord_123',
total: 99.99,
products: [
{ product_id: 'prod_1', name: 'Widget', price: 49.99, quantity: 2 },
],
});
// This would be a TypeScript error:
// trackEvent('Order Completed', { total: 99.99 }); // Missing order_id
Context
tracking plan
data governance
event schema
Identity Resolution
Track anonymous users, then merge with identified users via identify().
Use alias() for identity merging between systems. Group users into
companies/organizations.
// Identity flow implementation
// lib/identity.ts
// Anonymous user tracking
export function trackAnonymousAction(event: string, properties?: object) {
// Analytics.js automatically generates anonymousId
analytics.track(event, properties);
}
// When user signs up or logs in
export async function identifyUser(user: {
id: string;
email: string;
name?: string;
plan?: string;
}) {
// This merges anonymous history with user profile
await analytics.identify(user.id, {
email: user.email,
name: user.name,
plan: user.plan,
created_at: new Date().toISOString(),
});
// Track the identification event
analytics.track('User Identified', {
method: 'signup',
});
}
// B2B: Associate user with company
export function associateWithCompany(company: {
id: string;
name: string;
plan?: string;
employees?: number;
industry?: string;
}) {
analytics.group(company.id, {
name: company.name,
plan: company.plan,
employees: company.employees,
industry: company.industry,
});
}
// Alias: Link identities (e.g., pre-signup email to user ID)
export function linkIdentities(previousId: string, newUserId: string) {
// Use when you identified someone with a temporary ID
// and now have their permanent user ID
analytics.alias(newUserId, previousId);
}
// Full signup flow
export async function handleSignup(
email: string,
password: string,
company?: { name: string; size: string }
) {
// 1. Create user in your system
const user = await createUser(email, password);
// 2. Identify with Segment (merges anonymous history)
await identifyUser({
id: user.id,
email: user.email,
name: user.name,
plan: 'free',
});
// 3. Track signup event
analytics.track('User Signed Up', {
signup_method: 'email',
plan: 'free',
});
// 4. If B2B, associate with company
if (company) {
const companyRecord = await createCompany(company, user.id);
associateWithCompany({
id: companyRecord.id,
name: company.name,
employees: parseInt(company.size),
});
}
}
Context
user identification
anonymous tracking
b2b tracking
Destinations Configuration
Route data to analytics tools, data warehouses, and marketing platforms.
Use device-mode for client-side tools, cloud-mode for server processing.
// Segment destinations are configured in the Segment UI
// but here's how to optimize your implementation
// Conditional tracking based on destination needs
// lib/segment-destinations.ts
interface DestinationConfig {
mixpanel: boolean;
amplitude: boolean;
googleAnalytics: boolean;
warehouse: boolean;
hubspot: boolean;
}
// Only send events needed by specific destinations
export function trackWithDestinations(
event: string,
properties: Record<string, any>,
options?: {
integrations?: Partial;
}
) {
analytics.track(event, properties, {
integrations: {
// Override specific destinations
All: true, // Send to all by default
...options?.integrations,
},
});
}
// Example: Track revenue event only to revenue-tracking destinations
export function trackRevenue(order: {
orderId: string;
total: number;
currency: string;
}) {
analytics.track('Order Completed', {
order_id: order.orderId,
revenue: order.total,
currency: order.currency,
}, {
integrations: {
// Explicitly enable revenue destinations
'Google Analytics 4': true,
'Mixpanel': true,
'Amplitude': true,
// Disable non-revenue destinations
'Intercom': false,
'Zendesk': false,
},
});
}
// Send PII only to secure destinations
export function identifyWithPII(userId: string, traits: {
email: string;
phone?: string;
address?: string;
}) {
analytics.identify(userId, traits, {
integrations: {
'All': false, // Disable all by default
// Only send PII to trusted destinations
'HubSpot': true,
'Salesforce': true,
'Warehouse': true, // Your data warehouse
// Don't send PII to analytics tools
'Mixpanel': false,
'Amplitude': false,
},
});
}
// Context enrichment for all events
export function enrichedTrack(
event: string,
properties: Record<string, any>
) {
analytics.track(event, {
...properties,
// Add common context
app_version: process.env.NEXT_PUBLIC_APP_VERSION,
environment: process.env.NODE_ENV,
timestamp: new Date().toISOString(),
}, {
context: {
app: {
name: 'MyApp',
version: process.env.NEXT_PUBLIC_APP_VERSION,
},
},
});
}
Context
data routing
destination setup
tool integration
HTTP Tracking API
Direct HTTP API for any environment. Useful for edge functions,
workers, and non-Node.js backends. Batch up to 500KB per request.
// Edge/Serverless tracking via HTTP API
// lib/segment-http.ts
const SEGMENT_WRITE_KEY = process.env.SEGMENT_WRITE_KEY!;
const SEGMENT_API = 'https://api.segment.io/v1';
// Base64 encode write key for auth
const authHeader = Basic ${btoa(SEGMENT_WRITE_KEY + ':')};
interface SegmentEvent {
userId?: string;
anonymousId?: string;
event?: string;
name?: string; // For page calls
properties?: Record<string, any>;
traits?: Record<string, any>;
context?: Record<string, any>;
timestamp?: string;
}
async function segmentRequest(
endpoint: string,
payload: SegmentEvent
): Promise {
const response = await fetch(${SEGMENT_API}${endpoint}, {
method: 'POST',
headers: {
'Authorization': authHeader,
'Content-Type': 'application/json',
},
body: JSON.stringify({
...payload,
timestamp: payload.timestamp || new Date().toISOString(),
}),
});
if (!response.ok) {
console.error('Segment API error:', await response.text());
}
}
// HTTP API methods
export async function httpIdentify(
userId: string,
traits: Record<string, any>,
context?: Record<string, any>
) {
await segmentRequest('/identify', {
userId,
traits,
context,
});
}
export async function httpTrack(
userId: string,
event: string,
properties?: Record<string, any>,
context?: Record<string, any>
) {
await segmentRequest('/track', {
userId,
event,
properties,
context,
});
}
export async function httpPage(
userId: string,
name: string,
properties?: Record<string, any>
) {
await segmentRequest('/page', {
userId,
name,
properties,
});
}
// Batch API for high volume
export async function httpBatch(
events: Array<{
type: 'identify' | 'track' | 'page' | 'group';
userId?: string;
anonymousId?: string;
event?: string;
name?: string;
properties?: Record<string, any>;
traits?: Record<string, any>;
}>
) {
// Max 500KB per batch, 32KB per event
await segmentRequest('/batch', {
batch: events.map(e => ({
...e,
timestamp: new Date().toISOString(),
})),
} as any);
}
// Cloudflare Worker example
export default {
async fetch(request: Request): Promise {
const { userId, action, data } = await request.json();
// Track in edge function
await httpTrack(userId, action, data, {
ip: request.headers.get('cf-connecting-ip'),
userAgent: request.headers.get('user-agent'),
});
return new Response('ok');
},
};
Context
edge functions
serverless
http tracking
Sharp Edges
Anonymous ID Persists Until Explicit Reset
Severity: MEDIUM
Device Mode Bypasses Protocols Blocking
Severity: HIGH
HTTP API Has Strict Size Limits
Severity: MEDIUM
Track Calls Without Identify Are Anonymous
Severity: HIGH
Write Key in Client is Visible (But Intentional)
Severity: LOW
Events May Be Lost on Page Navigation
Severity: MEDIUM
Timestamps Without Timezone Cause Analytics Issues
Severity: MEDIUM
Tracking Before Consent Violates GDPR
Severity: HIGH
Validation Checks
Dynamic Event Name
Severity: ERROR
Event names should be static, not include dynamic values
Message: Dynamic event name detected. Use static event names with dynamic properties.
Inconsistent Event Name Casing
Severity: WARNING
Event names should follow consistent casing convention
Message: Mixed casing in event name. Use consistent convention (e.g., Title Case).
Track Without Prior Identify
Severity: WARNING
Users should be identified before tracking critical events
Message: Revenue/conversion event without identify. Ensure user is identified.
Missing Analytics Reset on Logout
Severity: WARNING
Analytics should be reset when user logs out
Message: Logout without analytics.reset(). Anonymous ID will persist to next user.
Hardcoded Segment Write Key
Severity: ERROR
Write key should use environment variables
Message: Hardcoded Segment write key. Use environment variables.
PII Sent to All Destinations
Severity: WARNING
PII should have destination controls
Message: PII in tracking without destination controls. Consider limiting destinations.
Event Without Proper Timestamp
Severity: INFO
Explicit timestamps help with historical data
Message: Server track without explicit timestamp. Consider adding timestamp.
Potentially Large Property Values
Severity: WARNING
Properties over 32KB will be rejected
Message: Potentially large property value. Segment has 32KB per event limit.
Tracking Before Consent Check
Severity: ERROR
GDPR requires consent before tracking
Message: Tracking without consent check. Implement consent management for GDPR.
Collaboration
Delegation Triggers
user needs A/B testing -> analytics-specialist (Segment + LaunchDarkly/Optimizely integration)
user needs data warehouse -> data-engineer (Segment to BigQuery/Snowflake/Redshift)
user needs customer support integration -> zendesk-integration (Identify calls syncing to support tools)
user needs marketing automation -> hubspot-integration (Segment to HubSpot destination)
user needs consent management -> privacy-specialist (GDPR/CCPA compliance with Segment)
When to Use
User mentions or implies: segment
User mentions or implies: analytics.js
User mentions or implies: customer data platform
User mentions or implies: cdp
User mentions or implies: tracking plan
User mentions or implies: event tracking
User mentions or implies: identify track page
User mentions or implies: data routing
Limitations
Use this skill only when the task clearly matches the scope described above.
Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.don't have the plugin yet? install it then click "run inline in claude" again.