@adv-re/ spement- wrapper (英语)
现代TypeScript抽象层位于分会场分析库上方,内置支持分会场集成,Adobe分析,TCF遵守,以及同意管理.
特征
- ✨ 类型脚本支持 - 全面安全和情报
- 🔒 TCF/GDPR 遵守情况 - 透明度和同意框架支助
- 🎯 Adobe 分析 - Adobe 访问者 API 整合
- 🔌 中间软件系统 - 广泛的源头和目的地中间软件
- 📊 运动跟踪 - UTM和STC参数解析和转发
- 🆔 通用标识 - 跨域用户识别
- 📦 多个格式 - 建立无害环境管理、共同JS和UMD
- 🧪 测试良好 - 综合测试覆盖率
安装
npm install @adv-re/segment-wrapper
快速启动
基本用途(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 用法 (浏览器)
<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>
版本选项 :
<!-- 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>
配置
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
})
见 配置指南 用于所有可用的选项.
API 参考
核心方法
analytics.track(event, properties?, context?, callback?)- 跟踪自定义事件analytics.page(name?, properties?, context?, callback?)- 音轨页面浏览analytics.identify(userId, traits?, options?, callback?)- 识别用户analytics.reset()- 重新设置用户识别
公用事业
getConfig(key)- 获得配置值setConfig(key, value)- 设定配置值clearConfig()- 清除所有配置getUniversalId()- 获取当前通用IDgetAdobeMCVisitorID()- 得到Adobe营销云访问者的身份getAdobeVisitorData()- 获取 Adobe 访问者 API 数据getCampaignDetails()- 从 URL 获取 UTM/STC 竞选参数
见 API 参考 详细文件.
高级特性
中间软件系统
区段-收发器包括一个强大的中件系统,允许您在发送前修改跟踪数据:
// 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
见 中件文档 更多细节.
TCF/GDPR 遵守情况
对透明度和同意框架的内置支持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)
事件会根据用户的同意自动被屏蔽或修改.
见 TCF 文档 更多细节.
运动跟踪
自动 UTM 和 STC 活动参数解析 :
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
特征 :
- UTM 参数解析( utm source, utm 中型, utm 校园等)
- STC 格式支持( Customal Adeventa 格式 :?stc=medical- source- Campaign)
- 自动转发到区段( 以及GA4 等下游目的地)
移徙指南
从 v4 移到 v5
见 升级到 v5 指南 关于升级到第5版的分步指示.
V5 中的关键变化 :
- GA4 现在由分块设备模式管理(没有更直接的gtag.js初始化)
- 删除
googleAnalyticsMeasurementId, (中文(简体) ),googleAnalyticsConfig等配置选项 - 作为事件属性而不是直接调用 gtag 模式
- 运动跟踪仍然得到支持(UTM/STC参数)
从@s-ui/ 组件- wrapper 迁移
见 移徙指南 关于遗产迁移的分步指示 @s-ui/segment-wrapper 软件包.
关键更改 :
- 软件包名称 :
@s-ui/segment-wrapper→@adv-re/segment-wrapper - 带有类型定义的完整类型脚本支持
- 现代建设系统(Tsup 而不是自宽)
- 改善摇树和捆绑大小
浏览器支持
- Chrome/Edge(后2个版本)
- Firefox(最后2个版本)
- Safari(最后两个版本)
- iOS Safari(后2个版本)
套装大小
- 无害环境管理:~34KB(最小)
- 通用JS:~36KB(最小化)
- UMD:~15KB(最小化)
发展
# Install dependencies
npm install
# Run tests
npm test
# Build
npm run build
# Build UMD bundle
npm run build:umd
# Lint
npm run lint
文档
许可证
公务员制度委员会