@adv-re/segment-wrapper

@adv-re/segment-wrapper

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

Features

• ✨ TypeScript Support - Full type safety and IntelliSense
• 🔒 TCF/GDPR Compliance - Built-in Transparency & Consent Framework support
• 📊 Google Analytics 4 - Native GA4 integration with consent mode
• 🎯 Adobe Analytics - Adobe Visitor API integration
• 🔌 Middleware System - Extensible source and destination middlewares
• 🆔 Universal ID - User identification across domains
• 📦 Multiple Formats - ESM, CommonJS, and UMD builds
• 🧪 Well Tested - 203 tests with 80%+ 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
initConfig({
  segmentKey: 'your-segment-write-key',
  googleAnalyticsMeasurementId: 'G-XXXXXXXXXX',
  googleAnalyticsConsentManagement: true
})

// 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: '[e-mail]',
  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 src="https://unpkg.com/@adv-re/segment-wrapper@4.36.0"></script>

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

Version Options:

<!-- Specific version (recommended for production) -->
<script src="https://unpkg.com/@adv-re/segment-wrapper@4.36.0"></script>

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

<!-- Direct path to UMD file -->
<script src="https://unpkg.com/@adv-re/segment-wrapper@4.36.0/umd/index.global.js"></script>

Configuration

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

initConfig({
  // Segment
  segmentKey: 'your-segment-write-key',
  
  // Google Analytics 4
  googleAnalyticsMeasurementId: 'G-XXXXXXXXXX',
  googleAnalyticsConsentManagement: true,
  googleAnalyticsConfig: {
    // Custom GA4 config
  },
  
  // Adobe Analytics
  adobeVisitorId: 'YOUR_ADOBE_ORG_ID@AdobeOrg',
  
  // TCF/GDPR
  enableTcf: true,
  
  // Universal ID
  universalId: 'user-universal-id',
  userEmail: '[e-mail]',
  
  // Middlewares
  experimentalPageDataMiddleware: false,
  
  // Other
  defaultProperties: {
    platform: 'web',
    app: 'my-app'
  },
  userIdPrefix: 'usr_'
})

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

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.

Google Analytics 4 Integration

Native GA4 integration with automatic consent mode:

initConfig({
  googleAnalyticsMeasurementId: 'G-XXXXXXXXXX',
  googleAnalyticsConsentManagement: true,
  googleAnalyticsConfig: {
    send_page_view: false,
    // Additional GA4 config options
  }
})

Features:

• Automatic consent mode updates based on TCF
• Session and client ID tracking
• Campaign parameter forwarding
• Custom event tracking

Migration 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
• Migration Guide
• Examples

License

ISC