segment-cdp（分段 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 {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.