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.