adstage
Web SDK事件

裝置資訊管理

透過收集並管理裝置資訊，可針對各平台最佳化使用者體驗並進行精準的分析。

📱 裝置資訊概述

支援的裝置屬性

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);
  }
}

🚀 後續步驟

了解運用裝置資訊的進階功能：

上一頁

使用者屬性管理

下一頁

自訂事件

目錄

📱 裝置資訊概述支援的裝置屬性混合式收集方式🔧 裝置資訊設定設定全部裝置資訊設定個別裝置屬性各平台設定範例📊 查詢裝置資訊確認最終裝置資訊僅確認使用者設定的資訊確認裝置資訊🔄 自動偵測 vs 手動設定自動偵測的運作方式手動設定的建議事項🎯 各平台實作指南React Native 應用程式PWA（Progressive Web App）混合式應用程式（Ionic、Capacitor）🔧 裝置資訊管理重設與重新設定應用程式更新時的處理條件式設定📈 以裝置為基礎的分析與事件搭配運用依平台分支功能🛠️ 偵錯與驗證驗證裝置資訊確認資訊一致性🚀 後續步驟