设备信息管理

通过收集并管理设备信息，可以针对各平台优化用户体验并进行准确的分析。

📱 设备信息概述

支持的设备属性

AdStage SDK 会收集以下设备信息：

// 设备信息结构
{
  category: 'mobile' | 'desktop' | 'tablet' | 'other',  // 设备类别
  platform: string,    // 平台信息（iOS、Android、Windows 等）
  model: string,        // 设备型号名称
  appVersion: string,   // 应用版本
  osVersion: string     // 操作系统版本
}

混合收集方式

SDK 采用 自动检测 + 用户设置 的混合方式：

自动检测：基于浏览器 User-Agent 与 navigator 对象收集基本信息
- category：基于 User-Agent 判断设备类型（mobile/desktop/tablet/other）
- platform：通过 DeviceInfoCollector 进行平台映射（iOS、Android、Desktop Web 等）
- model：使用 navigator.platform 的值
- osVersion：使用 navigator.platform 的值
用户设置：开发者可用准确的信息进行覆盖

🔧 设备信息设置

设置全部设备信息

// 一次性设置多个设备属性
AdStage.events.setDeviceInfo({
  category: 'mobile',
  platform: 'iOS',
  model: 'iPhone 15 Pro',
  appVersion: '2.1.0',
  osVersion: '17.1.1'
});
 
// Web 应用 / PWA 的示例
AdStage.events.setDeviceInfo({
  category: 'mobile',
  platform: 'Mobile Web',
  model: 'PWA App',
  appVersion: '3.0.0',
  osVersion: 'iOS 17.1'
});

设置单个设备属性

// 仅设置单个属性
AdStage.events.setDeviceProperty('appVersion', '2.1.1');
AdStage.events.setDeviceProperty('model', 'Custom PWA');
AdStage.events.setDeviceProperty('platform', 'React Native');
AdStage.events.setDeviceProperty('osVersion', '14.0');
AdStage.events.setDeviceProperty('category', 'tablet');

各平台设置示例

// iOS 应用
AdStage.events.setDeviceInfo({
  category: 'mobile',
  platform: 'iOS',
  model: 'iPhone 15 Pro',
  appVersion: '2.1.0',
  osVersion: '17.1.1'
});
 
// Android 应用
AdStage.events.setDeviceInfo({
  category: 'mobile',
  platform: 'Android',
  model: 'Galaxy S24',
  appVersion: '2.1.0',
  osVersion: '14'
});
 
// 桌面 Web
AdStage.events.setDeviceInfo({
  category: 'desktop',
  platform: 'Windows',
  model: 'Chrome Browser',
  appVersion: '2.0.5',
  osVersion: '11'
});
 
// 平板
AdStage.events.setDeviceInfo({
  category: 'tablet',
  platform: 'iPadOS',
  model: 'iPad Pro',
  appVersion: '2.1.0',
  osVersion: '17.1'
});

📊 查询设备信息

确认最终设备信息

// 最终设备信息（自动检测 + 用户设置合并）
const deviceInfo = AdStage.events.getDeviceInfo();
console.log(deviceInfo);
/*
{
  category: 'mobile',      // 自动检测或用户设置
  platform: 'iOS',        // 由用户设置覆盖
  model: 'iPhone 15 Pro',  // 用户设置
  appVersion: '2.1.1',    // 用户设置
  osVersion: '17.1.1'     // 自动检测或用户设置
}
*/

仅确认用户设置的信息

// 仅确认用户自行设置的信息
const userProvided = AdStage.events.getUserDeviceInfo();
console.log('사용자 제공 정보:', userProvided);
// { appVersion: '2.1.1', model: 'iPhone 15 Pro' }

确认设备信息

// 确认当前设备信息（自动检测 + 用户设置合并）
const deviceInfo = AdStage.events.getDeviceInfo();
console.log('최종 디바이스 정보:', deviceInfo);
 
// 仅确认用户设置的信息
const userProvidedInfo = AdStage.events.getUserDeviceInfo();
console.log('사용자 제공 정보:', userProvidedInfo);
 
// 详细的调试信息不通过单独的 API 提供
// 如有需要，请在浏览器控制台中直接查看 navigator 对象
console.log('User Agent:', navigator.userAgent);
console.log('Platform:', navigator.platform);
console.log('Language:', navigator.language);

🔄 自动检测 vs 手动设置

自动检测的工作方式

// SDK 自动检测的信息
// 1. 服务器端渲染（SSR）环境：
//    { category: 'other', platform: 'SSR', model: 'SSR', osVersion: 'SSR' }
 
// 2. 浏览器环境：
//    - User-Agent 中匹配 /tablet|ipad/ 模式 → category: 'tablet'
//    - DeviceInfoCollector.isMobile() true → category: 'mobile'
//    - 默认值 → category: 'desktop'
//    
//    - 将 DeviceInfoCollector.getPlatform() 的结果映射为事件 API 所用的值：
//      'ios' → 'iOS', 'android' → 'Android', 
//      'web' → 'Mobile Web', 'desktop' → 'Desktop Web'
//    
//    - model 与 osVersion 使用 navigator.platform 的值
 
// 自动检测的示例结果（在 iPhone 上）：
const autoDetected = AdStage.events.getDeviceInfo();
/*
{
  category: 'mobile',
  platform: 'iOS', 
  model: 'MacIntel',      // navigator.platform 的值
  osVersion: 'MacIntel'   // navigator.platform 的值（可能不准确）
}
*/

手动设置的建议事项

// 为获得准确信息，建议手动设置以下属性：
 
// 1. appVersion - 应用的实际版本
AdStage.events.setDeviceProperty('appVersion', '2.1.0');
 
// 2. model - 准确的设备型号名称
AdStage.events.setDeviceProperty('model', 'iPhone 15 Pro');
 
// 3. osVersion - 准确的 OS 版本
AdStage.events.setDeviceProperty('osVersion', '17.1.1');
 
// 4. platform - 混合应用的情况
AdStage.events.setDeviceProperty('platform', 'React Native');

🎯 各平台实现指南

React Native 应用

import { Platform } from 'react-native';
import DeviceInfo from 'react-native-device-info';
 
// 在 React Native 中设置准确的设备信息
async function setupDeviceInfo() {
  const deviceInfo = {
    category: Platform.isPad ? 'tablet' : 'mobile',
    platform: Platform.OS === 'ios' ? 'iOS' : 'Android',
    model: await DeviceInfo.getModel(),
    appVersion: await DeviceInfo.getVersion(),
    osVersion: await DeviceInfo.getSystemVersion()
  };
  
  AdStage.events.setDeviceInfo(deviceInfo);
}

PWA（Progressive Web App）

// 在 PWA 中设置设备信息
function setupPWADeviceInfo() {
  // 反映 PWA 特性的设置
  AdStage.events.setDeviceInfo({
    category: 'mobile', // 或根据实际设备设置
    platform: 'Mobile Web',
    model: 'PWA App',
    appVersion: '3.0.0', // PWA 版本
    osVersion: 'Unknown' // 在浏览器中无法获取准确的 OS 版本
  });
}
 
// 检测已安装的 PWA
if (window.matchMedia('(display-mode: standalone)').matches) {
  setupPWADeviceInfo();
}

混合应用（Ionic、Capacitor）

import { Capacitor } from '@capacitor/core';
import { Device } from '@capacitor/device';
 
// 在 Capacitor 应用中设置设备信息
async function setupCapacitorDeviceInfo() {
  if (Capacitor.isNativePlatform()) {
    const info = await Device.getInfo();
    
    AdStage.events.setDeviceInfo({
      category: info.platform === 'ios' && info.model.includes('iPad') ? 'tablet' : 'mobile',
      platform: info.platform === 'ios' ? 'iOS' : 'Android',
      model: info.model,
      appVersion: info.appVersion,
      osVersion: info.osVersion
    });
  }
}

🔧 设备信息管理

重置与重新设置

// 仅重置用户设置的设备信息（自动检测的信息保留）
AdStage.events.clearDeviceInfo();
 
// 只想移除特定属性时
AdStage.events.setDeviceProperty('appVersion', undefined);
AdStage.events.setDeviceProperty('model', undefined);

应用更新时的处理

// 应用版本更新时
function handleAppUpdate(newVersion) {
  AdStage.events.setDeviceProperty('appVersion', newVersion);
  
  // 发送应用更新事件
  AdStage.events.track('app_updated', {
    previous_version: getCurrentVersion(),
    new_version: newVersion,
    update_type: 'automatic'
  });
}

条件式设置

// 仅在特定条件下设置设备信息
function conditionalDeviceSetup() {
  // 仅在原生应用中设置
  if (window.cordova || window.PhoneGap) {
    AdStage.events.setDeviceInfo({
      category: 'mobile',
      platform: 'Cordova',
      model: 'Hybrid App',
      appVersion: getAppVersion()
    });
  }
  
  // 仅在 PWA 环境中设置
  if ('serviceWorker' in navigator) {
    AdStage.events.setDeviceProperty('platform', 'PWA');
  }
}

📈 基于设备的分析

与事件结合使用

// 设备信息会自动包含在所有事件中
AdStage.events.track('screen_view', {
  screen_name: 'product_detail',
  product_id: 'prod_123'
});
 
// 服务器接收到的数据中会包含已设置的设备信息：
// {
//   eventName: 'screen_view',
//   device: {
//     category: 'mobile',
//     platform: 'iOS',
//     model: 'iPhone 15 Pro',
//     appVersion: '2.1.0',
//     osVersion: '17.1.1'
//   },
//   params: { screen_name: 'product_detail', product_id: 'prod_123' }
// }

按平台进行功能分支

// 利用设备信息进行功能分支
function handlePlatformSpecificFeature() {
  const deviceInfo = AdStage.events.getDeviceInfo();
  
  if (deviceInfo.category === 'mobile') {
    // 移动端专用功能
    enableMobileGestures();
    AdStage.events.track('mobile_feature_enabled', {
      feature: 'gestures',
      platform: deviceInfo.platform
    });
  } else if (deviceInfo.category === 'desktop') {
    // 桌面端专用功能
    enableKeyboardShortcuts();
    AdStage.events.track('desktop_feature_enabled', {
      feature: 'keyboard_shortcuts',
      platform: deviceInfo.platform
    });
  }
}

🛠️ 调试与验证

验证设备信息

// 在开发模式下验证设备信息
if (process.env.NODE_ENV === 'development') {
  const deviceInfo = AdStage.events.getDeviceInfo();
  
  console.log('현재 디바이스 정보:', deviceInfo);
  console.log('사용자 설정 정보:', AdStage.events.getUserDeviceInfo());
  console.log('브라우저 정보:', {
    userAgent: navigator.userAgent,
    platform: navigator.platform,
    language: navigator.language
  });
  
  // 确认必需信息
  if (!deviceInfo.appVersion) {
    console.warn('앱 버전이 설정되지 않았습니다.');
  }
}

确认信息一致性

// 平台信息一致性检查
function validateDeviceInfo() {
  const deviceInfo = AdStage.events.getDeviceInfo();
  
  // 确认是否存在平台为 iOS 但 category 为 desktop 等不一致情况
  if (deviceInfo.platform === 'iOS' && deviceInfo.category === 'desktop') {
    console.warn('디바이스 정보 불일치: iOS 플랫폼에 desktop 카테고리');
  }
  
  // 确认应用版本格式
  if (deviceInfo.appVersion && !/^\d+\.\d+\.\d+/.test(deviceInfo.appVersion)) {
    console.warn('앱 버전 형식이 올바르지 않습니다:', deviceInfo.appVersion);
  }
}

🚀 后续步骤

了解利用设备信息的高级功能：

用户属性管理：用户资料与属性管理
事件跟踪：跟踪用户行为事件
各平台优化：各平台性能优化

设备信息管理

目录