デバイス情報の管理

デバイス情報を収集・管理することで、プラットフォームごとのユーザー体験の最適化と正確な分析を行えます。

📱 デバイス情報の概要

サポートされるデバイス属性

AdStage SDK は次のデバイス情報を収集します：

// デバイス情報の構造
{
  category: 'mobile' | 'desktop' | 'tablet' | 'other',  // デバイスカテゴリ
  platform: string,    // プラットフォーム情報（iOS、Android、Windows など）
  model: string,        // デバイスのモデル名
  appVersion: string,   // アプリのバージョン
  osVersion: string     // OS のバージョン
}

ハイブリッド収集方式

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

🚀 次のステップ

デバイス情報を活用した高度な機能をご覧ください：

ユーザー属性の管理：ユーザーのプロフィールと属性の管理
イベントトラッキング：ユーザー行動イベントのトラッキング
プラットフォーム別の最適化：プラットフォーム別のパフォーマンス最適化

デバイス情報の管理

目次