@adv-re/segment-wrapper

Modern TypeScript abstraction layer on top of the Segment Analytics library with built-in support for Segment integrations, Adobe Analytics, TCF compliance, and consent management.

Features

• ✨ TypeScript Support - Full type safety and IntelliSense
• 🔒 TCF/GDPR Compliance - Built-in Transparency & Consent Framework support
• 🎯 Adobe Analytics - Adobe Visitor API integration
• 🔌 Middleware System - Extensible source and destination middlewares
• 📊 Campaign Tracking - UTM and STC parameter parsing and forwarding
• 🆔 Universal ID - User identification across domains
• 📦 Multiple Formats - ESM, CommonJS, and UMD builds
• 🧪 Well Tested - Comprehensive test coverage

Installation

npm install @adv-re/segment-wrapper

Quick Start

Basic Usage (ESM/TypeScript)

import analytics from '@adv-re/segment-wrapper'
import {initConfig} from '@adv-re/segment-wrapper'

// Initialize configuration (optional - for custom settings)
initConfig({
  userIdPrefix: 'fc-',
  adobeMarketingCloudOrgId: 'YOUR_ORG_ID@AdobeOrg',
  sendXandrId: true,
  defaultProperties: {
    platform: 'web'
  }
})

// Track events
await analytics.track('Button Clicked', {
  buttonName: 'Sign Up',
  location: 'Homepage'
})

// Track page views
await analytics.page('Homepage', {
  title: 'Welcome to Our Site'
})

// Identify users
await analytics.identify('user-123', {
  email: '[email protected]',
  plan: 'premium'
})

UMD Usage (Browser)

<script src="https://cdn.segment.com/analytics.js/v1/YOUR_WRITE_KEY/analytics.min.js"></script>
<!-- Use specific version (recommended for production) -->
<script async src="https://unpkg.com/@adv-re/segment-wrapper@latest"></script>

<script>
  // Access via window.sui.analytics
  window.sui.analytics.track('Page Viewed', {
    page: 'home'
  })
</script>

Version Options:

<!-- Specific version (recommended for production) -->
<script async src="https://unpkg.com/@adv-re/[email protected]"></script>

<!-- Latest version (use only for development) -->
<script async src="https://unpkg.com/@adv-re/segment-wrapper"></script>

Configuration

import {initConfig} from '@adv-re/segment-wrapper'

initConfig({
  // Segment API Key
  key: 'xOoVeB57iXT3X1ehtxLk0Ipte3eIYTZw',

  // User ID Configuration
  userIdPrefix: 'fc-',

  // Adobe Analytics
  adobeMarketingCloudOrgId: 'YOUR_ORG_ID@AdobeOrg',

  // Xandr ID
  sendXandrId: true,

  // Default Properties (added to all track calls)
  defaultProperties: {
    platform: 'web',
    app: 'my-app'
  },

  // Middlewares
  experimentalPageDataMiddleware: false
})

See Configuration Guide for all available options.

API Reference

Core Methods

• analytics.track(event, properties?, context?, callback?) - Track custom events
• analytics.page(name?, properties?, context?, callback?) - Track page views
• analytics.identify(userId, traits?, options?, callback?) - Identify users
• analytics.reset() - Reset user identification

Utilities

• getConfig(key) - Get configuration value
• setConfig(key, value) - Set configuration value
• clearConfig() - Clear all configuration
• getUniversalId() - Get current Universal ID
• getAdobeMCVisitorID() - Get Adobe Marketing Cloud Visitor ID
• getAdobeVisitorData() - Get Adobe Visitor API data
• getCampaignDetails() - Get UTM/STC campaign parameters from URL

See API Reference for detailed documentation.

Advanced Features

Middleware System

The segment-wrapper includes a powerful middleware system that allows you to modify tracking data before it's sent:

// Middlewares are automatically registered on initialization
// They enrich events with:
// - User traits (anonymous ID, user ID)
// - Campaign context (UTM parameters, STC tracking)
// - Page referrer information
// - Screen dimensions
// - Default context properties

See Middleware Documentation for more details.

TCF/GDPR Compliance

Built-in support for Transparency & Consent Framework (TCF) v2:

import {getGdprPrivacyValue, checkAnalyticsGdprIsAccepted} from '@adv-re/segment-wrapper'

// Get current GDPR consent state
const gdprValue = await getGdprPrivacyValue()
// { analytics: 'accepted', advertising: 'declined' }

// Check if analytics tracking is allowed
const canTrack = checkAnalyticsGdprIsAccepted(gdprValue)

Events are automatically blocked or modified based on user consent.

See TCF Documentation for more details.

Campaign Tracking

Automatic UTM and STC campaign parameter parsing:

import {getCampaignDetails} from '@adv-re/segment-wrapper'

// Get campaign details from URL
const campaign = getCampaignDetails()
// Returns: { utm_source: 'google', utm_medium: 'cpc', ... }

// Campaign parameters are automatically added to all events
// via the campaignContext middleware

Features:

• UTM parameter parsing (utm_source, utm_medium, utm_campaign, etc.)
• STC format support (custom Adevinta format: ?stc=medium-source-campaign)
• Automatic forwarding to Segment (and downstream destinations like GA4)

Migration Guides

Migrating from v4 to v5

See Upgrade to v5 Guide for step-by-step instructions on upgrading to version 5.

Key changes in v5:

• GA4 now managed by Segment Device Mode (no more direct gtag.js initialization)
• Removed googleAnalyticsMeasurementId, googleAnalyticsConfig, etc. configuration options
• Consent Mode sent as event properties instead of direct gtag calls
• Campaign tracking still supported (UTM/STC parameters)

Migrating from @s-ui/segment-wrapper

See Migration Guide for step-by-step instructions on migrating from the legacy @s-ui/segment-wrapper package.

Key changes:

• Package name: @s-ui/segment-wrapper → @adv-re/segment-wrapper
• Full TypeScript support with type definitions
• Modern build system (tsup instead of sui-bundler)
• Improved tree-shaking and bundle size

Browser Support

• Chrome/Edge (last 2 versions)
• Firefox (last 2 versions)
• Safari (last 2 versions)
• iOS Safari (last 2 versions)

Bundle Size

• ESM: ~34KB (minified)
• CommonJS: ~36KB (minified)
• UMD: ~15KB (minified)

Development

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Build UMD bundle
npm run build:umd

# Lint
npm run lint

Documentation

• Configuration Guide
• API Reference
• Middleware System
• TCF Compliance
• Upgrade to v5 Guide
• Migration from @s-ui/segment-wrapper
• Examples

License

ISC