用户属性管理

通过跟踪用户的特征与行为模式，可以实现个性化服务与定向营销。

🔍 用户识别

通过用户属性进行识别

AdStage Web SDK 不提供单独的用户 ID 设置 API。取而代之的是，通过用户属性（setUserProperties）记录用户的特征，并将其用于分群与漏斗分析：

// 登录时设置用户属性
AdStage.events.setUserProperties({
  gender: 'male',      // 'male' | 'female' | 'other' | 'unknown'
  country: 'KR',       // ISO 国家代码
  city: 'Seoul',       // 城市名
  age: '25-34',        // 年龄段
  language: 'ko-KR'    // 语言代码
});
 
// 确认当前已设置的用户属性
const userProperties = AdStage.events.getUserProperties();
console.log('当前用户属性:', userProperties);

匿名用户跟踪

未登录的用户也会基于会话自动被跟踪：

// 匿名用户跟踪由 SDK 自动管理
// 不提供单独的设置或查询 API
// 基于会话自动进行跟踪

👤 用户属性设置

支持的标准属性

SDK 支持的标准用户属性如下：

// 一次性设置多个属性（推荐方法）
AdStage.events.setUserProperties({
  age: '25',           // 年龄（字符串）
  gender: 'female',    // 'male' | 'female' | 'other' | 'unknown'
  country: 'KR',       // ISO 国家代码 (ISO 3166-1 alpha-2)
  city: 'Seoul',       // 城市名
  language: 'ko-KR'    // 语言代码 (BCP 47)
});
 
// 目前不提供单个属性的设置 API
// 所有属性请通过 setUserProperties() 设置

自动收集的属性

SDK 在浏览器中自动收集的信息：

// 从浏览器语言设置中自动提取
// navigator.language → 自动设置 language、country
// 例如: 'ko-KR' → language: 'ko-KR', country: 'KR'
 
// 确认自动收集到的用户信息
const userInfo = AdStage.events.getUserInfo();
console.log(userInfo);
// { language: 'ko-KR', country: 'KR' }
 
// 基于时区的地区推定在内部执行，
// 不会作为单独的 API 暴露

属性限制事项

目前 AdStage Web SDK 仅支持标准属性：

// ✅ 支持的标准属性
AdStage.events.setUserProperties({
  gender: 'female',      // 'male' | 'female' | 'other' | 'unknown'
  country: 'KR',         // ISO 国家代码
  city: 'Seoul',         // 城市名
  age: '25',             // 年龄（字符串）
  language: 'ko-KR'      // 语言代码
});
 
// ❌ 不支持自定义属性
// 请改用事件参数
AdStage.events.track('user_profile_updated', {
  subscription_tier: 'premium',    // 以事件参数发送
  account_type: 'business',
  last_login: '2024-01-15'
});

📊 用户属性管理

属性查询与管理

// 查询当前已设置的用户属性
const currentProperties = AdStage.events.getUserProperties();
console.log('当前用户属性:', currentProperties);
 
// 目前不提供单个属性查询与属性重置的 API
// 所有属性请通过 getUserProperties() 一并查询
 
// 若要重置属性，请设置为空对象
AdStage.events.setUserProperties({});

地区信息的运用

// 确认基于浏览器自动收集的信息
const userInfo = AdStage.events.getUserInfo();
console.log('自动收集的用户信息:', userInfo);
// { language: 'ko-KR', country: 'KR' }
 
// 地区信息会在内部自动推定并设置
// 如果手动掌握更准确的信息，可以将其覆盖
AdStage.events.setUserProperties({
  country: 'KR',
  city: 'Seoul',
  language: 'ko-KR'
});

🎯 个性化运用

基于用户属性的个性化

// 基于用户属性的内容推荐
function personalizeContent() {
  const userProperties = AdStage.events.getUserProperties();
  
  // 按年龄段的内容
  if (userProperties.age && parseInt(userProperties.age) < 30) {
    showYoungAdultContent();
  }
  
  // 按地区的内容
  if (userProperties.country === 'KR') {
    showKoreanContent();
  }
  
  // 按语言的内容
  if (userProperties.language?.startsWith('ko')) {
    setKoreanLanguage();
  }
}
 
// 属性变更时更新个性化
AdStage.events.setUserProperties({
  country: 'KR',
  language: 'ko-KR',
  age: '28'
});
personalizeContent();

与事件一起运用

// 用户属性会自动包含在所有事件中
AdStage.events.track('page_view', {
  page: 'product_detail',
  product_id: 'prod_123'
});
// 服务器接收到的数据中会包含已设置的用户属性：
// {
//   eventName: 'page_view',
//   user: {
//     gender: 'female',
//     country: 'KR',
//     city: 'Seoul',
//     age: '28',
//     language: 'ko-KR'
//   },
//   params: { page: 'product_detail', product_id: 'prod_123' }
// }

用户属性管理

目录