Skip to main content
segment-cdp Segment Customer Data Platform engineering patterns — Analytics.js, server-side tracking, tracking plans with Protocols, identity resolution, destinations config, and data governance. USE WHEN instrumenting a product with Segment to capture clean customer event data and route it to downstream marketing/analytics tools.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/Sheshiyer/skill-clusters --skill segment-cdpThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository Arcplume runs Grok through the Grok Build CLI's own OAuth-authenticated session (grok login) for image generation, with strict preflight validation, secret-safe handling, and headless CLI-driven execution -- no separate XAI_API_KEY billing. Video falls back to the billed xAI API. USE WHEN a user wants to generate an image via a locally logged-in Grok Build CLI session, e.g. 'generate an image with grok', 'use grok build', or 'use my logged-in grok session'.
Shared reference for the Selemene cluster: the two report surfaces (deterministic Rust reports vs. narrative witness-pipeline readings), the @selemene/bridge CLI contract, the output manifest format, and non-prescriptive witnessing tone. USE WHEN deciding which Selemene surface to invoke or when routing between birth/compatibility/transit reports and solo/dyadic readings.
Route Selemene Engine tasks to the right surface: deterministic reports (birth/compatibility/transit) via selemene-core and the @selemene/bridge CLI, or narrative witness readings via selemene-report. USE WHEN the user wants anything under the Selemene/Noesis umbrella but has not named the exact surface.
Related occupations SOC
Based on SOC occupation classification
name segment-cdp description Segment Customer Data Platform engineering patterns — Analytics.js, server-side tracking, tracking plans with Protocols, identity resolution, destinations config, and data governance. USE WHEN instrumenting a product with Segment to capture clean customer event data and route it to downstream marketing/analytics tools. cluster business-content version 1.0.0 origin antigravity-awesome-skills (MIT) risk safe source vibeship-spawner-skills (Apache 2.0) date_added "2026-02-27T00:00:00.000Z"
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
// 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
Device Mode Bypasses Protocols Blocking
HTTP API Has Strict Size Limits
Track Calls Without Identify Are Anonymous
Write Key in Client is Visible (But Intentional)
Events May Be Lost on Page Navigation
Timestamps Without Timezone Cause Analytics Issues
Tracking Before Consent Violates GDPR
Validation Checks
Dynamic Event Name 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 Event names should follow consistent casing convention
Message: Mixed casing in event name. Use consistent convention (e.g., Title Case).
Track Without Prior Identify Users should be identified before tracking critical events
Message: Revenue/conversion event without identify. Ensure user is identified.
Missing Analytics Reset on Logout Analytics should be reset when user logs out
Message: Logout without analytics.reset(). Anonymous ID will persist to next user.
Hardcoded Segment Write Key Write key should use environment variables
Message: Hardcoded Segment write key. Use environment variables.
PII Sent to All Destinations PII should have destination controls
Message: PII in tracking without destination controls. Consider limiting destinations.
Event Without Proper Timestamp Explicit timestamps help with historical data
Message: Server track without explicit timestamp. Consider adding timestamp.
Potentially Large Property Values Properties over 32KB will be rejected
Message: Potentially large property value. Segment has 32KB per event limit.
Tracking Before Consent Check 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.
