디바이스 정보 관리

디바이스 정보를 수집하고 관리하여 플랫폼별 사용자 경험 최적화와 정확한 분석을 수행할 수 있습니다.

📱 디바이스 정보 개요

지원되는 디바이스 속성

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'
});
 
// 웹앱/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'
});
 
// 데스크톱 웹
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);
  }
}

🚀 다음 단계

디바이스 정보를 활용한 고급 기능을 알아보세요:

사용자 속성 관리: 사용자 프로필 및 속성 관리
이벤트 추적: 사용자 행동 이벤트 추적
플랫폼별 최적화: 플랫폼별 성능 최적화

디바이스 정보 관리

목차