Contents
クイックスタート（短縮手順）
ここでは最短で公式サンプルを実機で起動するための要点を示します。
Unity を使う手順を中心に、ADB コマンドと最低限の AndroidManifest 例を掲載します。初回導入を短時間で終えたい開発者向けです。
30分で公式サンプルを起動する最短手順（サンプル名・ADB・Manifest）
最小手順で公式サンプルをインポートしてビルド、ADBでインストール・ログ確認まで行います。
- XREAL Developer に登録して SDK 3.0 をダウンロードする（公式ポータルに従う）。
- Unity（推奨：LTS）で新規プロジェクトを作成する（3D テンプレート）。
- 公式の.unitypackage または AAR/UPM をインポートする（Assets/Plugins/Android に AAR を置く場合はマニフェストマージを確認）。
- Player Settings を設定する（IL2CPP、ARM64 を有効にする等。具体例は後述）。
- サンプルシーンを開き、必要なランタイム許可（カメラ等）をリクエストするロジックを組み込む。
- ビルドして実機へインストールする（例コマンドは下記）。
- adb logcat で動作ログを取得し、簡単に動作確認する。
実行に使う代表的な ADB コマンド例（Mac/Linux の場合）：
|
1 2 3 4 5 6 7 8 9 |
adb devices adb install -r path/to/app-release.apk adb uninstall com.example.xrealapp adb logcat -v time > device.log # PID フィルタ（adb バージョンに依存） adb logcat --pid=$(adb shell pidof com.example.xrealapp) # Windows の場合（PowerShell） adb logcat -v time | findstr com.example.xrealapp |
最低限の AndroidManifest（Unity プロジェクトでは Assets/Plugins/Android/AndroidManifest.xml）例：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.xrealapp"> <uses-permission android:name="android.permission.CAMERA" /> <uses-permission android:name="android.permission.RECORD_AUDIO" /> <uses-permission android:name="android.permission.INTERNET" /> <application android:label="@string/app_name" android:usesCleartextTraffic="false"> <activity android:name="com.unity3d.player.UnityPlayerActivity" android:exported="true"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity> </application> </manifest> |
開発開始時の優先対応（推奨順）
初動で優先的に対応すべき事項を順に示します。
- XREAL 表記を統一し（"XREAL" を使用）、ドキュメントやコード内の表記ゆれを直す。
- まず公式サンプルを一つビルドして実機で起動する（動作確認が最優先）。
- 使用予定のデバイス仕様（リフレッシュレートやチップ）については公式技術仕様で“要確認”とする。
- EULA・商用利用条件・クラウドアンカーのデータ保持・リージョン制約は法務確認を行う。
導入：目的と想定読者
このガイドは XREAL SDK 3.0 を用いて、ハンドトラッキングやスペーシャルアンカーなどを含むプロトタイプを実機で短時間に動かすことを目的としています。
対象は Unity／Android／Unreal の基礎を持ち、実機での検証や配布経験がある開発者です。段階的に「動かす→実装する→最適化する」の流れで説明します。
要約（目的→手順→注意点）
このセクションの要旨を簡潔に示します。
- 目的：最短でサンプルを実機で動かし、主要機能の挙動を確認する。
- 手順：SDK取得→サンプルインポート→ビルド→実機検証。
- 注意点：デバイス固有の性能・ファームウェア差や SDK とデバイスの互換性は必ず確認する。
XREAL SDK 3.0 の概要と対応デバイス
SDK 3.0 は空間コンピューティング基盤としてハンドトラッキング、スペーシャルアンカー（ローカル／クラウド）、デプスメッシュ、センサーフュージョン等を提供します。各機能はデバイス依存の挙動を持つため、機種ごとの検証が重要です。製品ごとの周波数や専用チップに関する数値は公式仕様で必ず“要確認”してください。
要約（目的→手順→注意点）
このセクションの要点をまとめます。
- 目的：主要機能と互換性の概観を把握する。
- 手順：機能一覧の理解→対応機種の確認→サンプルで動作確認。
- 注意点：ROG XREAL R1 の 240Hz 対応やチップ名などの数値は変わる可能性があるため、公式仕様ページを参照して確認すること（要確認）。
主な機能（短い説明）
以下は代表的な機能と簡単な説明です。
- ハンドトラッキング：関節位置・回転・信頼度を返す。
- スペーシャルアンカー：位置の永続化（ローカル／クラウド）。
- デプスメッシュ：オクルージョンや空間検出に使う深度メッシュ。
- セッション管理／センサーフュージョン：トラッキングの安定化を支援する。
開発前チェックリスト：環境・アカウント・ライセンス
開発開始前に揃えるべき環境とアカウント、ライセンス上の注意点を整理します。準備を適切に行うことで初期トラブルを大幅に減らせます。
ハードウェア／OS／ドライバ
ここではハード・OS・ドライバ周りの確認項目を列挙します。
- 開発 PC：Windows 10/11 または macOS（ビルド負荷に応じて十分な RAM/GPU を推奨）。
- ターゲットデバイス：ファームウェアを最新に更新し、開発者オプションで USB デバッグを有効化。
- ドライバ：Windows では USB ドライバ、ADB ドライバをインストール。ワイヤレス ADB を使う場合はネットワーク設定を確認。
推奨ツールと具体バージョン（例）
ツールのバージョンは SDK ドキュメントを最優先で確認してください。以下は実務でよく使う目安です。
- Unity：LTS 系を推奨（例：Unity 2021.3 / 2022.3 LTS）。
- Android：Android Studio の最新安定版、NDK（Unity に合わせたバージョン）、Gradle（対応バージョン）。
- Android SDK レベル（目安）：minSdkVersion = 26、targetSdkVersion = 33（サービス要件に合わせて“要確認”）。
- Unreal：Unreal Engine 5 系（5.0+）。
※ 上記数値は目安です。SDK ドキュメントで必須最小値を確認してください（要確認）。
アカウントとライセンスの注意点
アカウントやライセンス関連で必ず確認すべき事項です。
- XREAL Developer アカウント：SDK ダウンロード、デバイス登録、ドキュメント参照のために必要。
- Google Play デベロッパーアカウント：配布や内部テスト時に必要。64-bit 対応等の要件に注意。
- クラウドアンカー等外部サービス：API キー、認証情報、データ保持期間とリージョン制約を確認。
- EULA／商用利用：SDK の再配布条件や商用利用の可否は必ず確認し、必要なら法務に相談する。
セットアップ：Unity / Android / Unreal（最短で動かす手順）
ここでは公式サンプルを最短でビルドして実機で確認するための具体手順を示します。Unity の手順を詳細に、Android ネイティブと Unreal は要点をまとめます。
要約（目的→手順→注意点）
各セットアップの要点をまとめます。
- 目的：最小設定でサンプルを動かす。
- 手順：SDK インポート→PlayerSettings 調整→マニフェスト確認→ビルド→インストール。
- 注意点：ABI（arm64）とランタイム許可、マニフェストマージに注意する。
Unity（最短手順）
最小手順で「インポート→設定→ビルド→実機確認」までを説明します。以下の手順は GUI 操作が中心です。
- Unity で新規プロジェクトを作成（3D、LTS 推奨）。
- 公式 .unitypackage または UPM/AAR をインポートする。AAR を直接使う場合は Assets/Plugins/Android に配置。
- Player Settings（Edit → Project Settings → Player）で次を設定する。
- Scripting Backend：IL2CPP
- Target Architectures：ARM64 を含める（Google Play の 64-bit 要件対応）
- Minimum API Level：SDK 指示に従う（目安：26）。
- Target API Level：インストールしている最新 SDK（例：33、要確認）。
- AndroidManifest は Assets/Plugins/Android/AndroidManifest.xml に置く。マージ衝突がある場合は xmlns:tools を使って調整する。
- 簡易的なランタイム許可要求の Unity スクリプト例（カメラ権限）：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
using UnityEngine; using UnityEngine.Android; public class PermissionRequester : MonoBehaviour { void Start() { if (!Permission.HasUserAuthorizedPermission(Permission.Camera)) { Permission.RequestUserPermission(Permission.Camera); } } } |
- Build Settings → Android → Build And Run。デバッグ時は Development Build と Script Debugging を有効にすると Unity Profiler が使えます。
- インストール後は adb logcat でログを確認する。
Android ネイティブ（要点）
Android Studio / Gradle で AAR や Maven 配布を使う場合の要点です。
- app/build.gradle に依存を追加（ローカル AAR の例）：
|
1 2 3 4 |
dependencies { implementation(name: 'xreal-sdk-3.0.0', ext: 'aar') // 実際の名前は配布物に従う } |
- AndroidManifest のマージ問題は tools:replace や tools:node="merge" で解決する。ルートに xmlns:tools を追加することを忘れない。
- defaultConfig に minSdkVersion / targetSdkVersion を設定する（例：min 26 / target 33、要確認）。
- JNI/NDK を使う場合は ABI（arm64-v8a 等）に対応したビルドを行う。
Unreal（要点）
Unreal での利用時の注意点です。
- SDK プラグインを Project/Plugins に配置し、有効化する。
- Project Settings でパッケージ名・権限（カメラ等）を設定する。
- Packaging は arm64 を含める設定にする。Blueprint または C++ から SDK ラッパーを呼び出す。
- Cooking/Packaging に時間がかかるため、段階的にテストを行う。
実機検証・実装ポイント・トラブルシュート
実機デバッグの基本ワークフローと、主要機能別の実装ポイント、代表的なトラブルとその対処法を示します。現場で即使える手順とログ解析例を優先します。
要約（目的→手順→注意点）
実機検証で抑えるべき要点を簡潔に示します。
- 目的：ログ取得と再現手順で原因を特定する。
- 手順：ADB 接続→logcat 取得→Profiler で計測→問題共有。
- 注意点：パッケージ名、SDK バージョン、デバイスモデル、ファームウェア情報を必ず添える。
実機デバッグワークフロー
実機でのログ取得や接続手順です。短いワークフローを示します。
- 接続：端末の開発者オプションで USB デバッグを有効化し、adb devices で確認。初回は端末側で RSA 承認を許可する。
- ログ取得：adb logcat -v time > device.log で全ログを保存。パッケージ名でフィルタする場合は grep/findstr 等を使う。
- Unity：Development Build を有効にして Unity Profiler をアタッチする。
- 低レベル解析：Perfetto / systrace でシステムトレースを取得する（CPU/GPU スケジューリング解析）。
ログフィルタ例：
|
1 2 3 4 5 6 |
# パッケージ名でフィルタ（Linux/Mac） adb logcat -v time | grep com.example.xrealapp # PID でフィルタ（adb のバージョンによる） adb logcat --pid=$(adb shell pidof com.example.xrealapp) |
主要機能別の実装ポイント（ハンドトラッキング／アンカー／デプスメッシュ）
機能ごとの実務的な注意点と実装ヒントを示します。
- ハンドトラッキング
- 取るべきデータ：関節位置・回転・信頼度（confidence）。信頼度でデータの採否を制御する。
- 安定化：指数移動平均などのローパスフィルタや補間を用いる。ジェスチャ判定は閾値＋ヒステリシスでノイズを抑える。
-
座標変換：デバイス座標→ワールド座標の変換を明示的に行う。セッションの基準点を設計する。
-
スペーシャルアンカー
- 基本：アンカー作成→ID 取得→ローカル保存またはクラウドアップ。復元時は ID で再配置する。
- 設計：ワールド原点とアンカーの相対関係を明確化し、リローカライズ時の変換ロジックを用意する。
-
クラウド利用：認証／キー管理、リトライ、タイムアウト処理、データ保持・リージョン制約の確認が必要（法務確認推奨）。
-
デプスメッシュ（オクルージョン）
- 実装：深度メッシュを GPU に渡し、深度テストやステンシルを使ってオクルージョン処理する。
- 品質対策：メッシュのノイズ除去や穴埋め、必要箇所のみ高解像度更新を行う。
- 性能：更新頻度を制御し、視界内の重要領域を優先する。
よくあるトラブルと代表的な対処例（抜粋）
代表的なエラーとその対処手順を示します。
- インストール失敗（ABI／署名）
- 典型エラー：INSTALL_FAILED_NO_MATCHING_ABIS / INSTALL_FAILED_UPDATE_INCOMPATIBLE。
-
対処：ターゲット ABI に arm64-v8a を含める。既存の旧版を adb uninstall com.example.xrealapp で削除して再インストールする。keystore が一致しているか確認する。
-
UnsatisfiedLinkError（ネイティブライブラリ不足）
- 典型エラー：java.lang.UnsatisfiedLinkError: dalvik.system.PathClassLoader ... could not find "libXXX.so"。
-
対処：AAR または APK に対応 ABI の .so が含まれているか確認。Unity では Plugins/Android/libs/arm64-v8a に配置されているか確認する。
-
権限エラー（SecurityException）
- 典型エラー：java.lang.SecurityException: Permission denied: require android.permission.CAMERA。
-
対処：Manifest に uses-permission を追加し、ランタイムで Permission.RequestUserPermission を呼び出してユーザーに許可を求める。
-
ProGuard / R8 による問題
- 対処：SDK が提供する ProGuard ルールを適用する、または必要なクラスを -keep する。具体的なルールは SDK のドキュメントに従う。
パフォーマンス・配布・法務（運用上の注意）
運用段階に移る前の最適化、測定、配布、法務面でのチェック項目を整理します。クラウドサービスのデータ保持や地域制約は必ず確認してください。
要約（目的→手順→注意点）
運用前に押さえるべきポイントをまとめます。
- 目的：安定した UX を提供するために負荷と法務要件を管理する。
- 手順：パフォーマンスを計測→最適化→署名・配布→法務チェック。
- 注意点：クラウドアンカー等の外部サービスはデータ保持・リージョン制約があるため、事前に仕様と契約条項を確認する。
パフォーマンス計測と最適化
計測指標と実際の最適化手法を示します。
- 主要指標：フレームタイム（平均／p99／p99.9）、CPU/GPU 使用率、ドローコール数、メモリ割当、GC 頻度、サーマルスロットリング。
- ツール：Unity Profiler、Android Studio Profiler、Perfetto/systrace、GPU ベンダーのプロファイラ。
- 最適化例：Dynamic Resolution、レンダースケールの動的調整、不要なポスト処理の削減、シングルパスステレオレンダリングの活用。
- 240Hz / 専用チップ：高リフレッシュ率は消費電力と処理負荷が増すため、動的な解像度調整や低負荷モードのフェールバックを実装する。チップ固有の最適化は公式ガイドを参照して実装する（要確認）。
配布・署名・法務（プライバシー・データ管理）
配布前に確認すべき署名・ストア申請・法務の実務ポイントです。
- 署名と 64-bit 対応：keystore の管理を厳格に行い、Google Play の 64-bit 要件に対応する。versionCode の運用を決める。
- ストア申請：カメラやセンサー利用の目的を明記し、プライバシーポリシーを用意する。内部テストや段階的公開を活用する。
- データ保護：カメラや生体に関わるデータは最小化し、暗号化して送信する。テレメトリは匿名化して収集する。
- EULA／商用利用：SDK の EULA、クラウドアンカー提供側の利用規約、データ保持ポリシー、データの地域（リージョン）制約を法務と確認することを必須とする。
参考リソース（公式優先）
公式ドキュメントを最優先に参照し、補助的にコミュニティ記事やレポートを利用してください。以下は分類した代表的な参照先です。
公式ドキュメント（優先）
- XREAL 公式サイト（製品・開発者ポータル）：https://www.xreal.com/us （SDK ダウンロードや技術仕様は公式ポータルを優先して参照してください）
- Android 開発ドキュメント（マニフェスト、権限、Gradle）：https://developer.android.com
- Unity ドキュメント（Android ビルド、Permissions、IL2CPP）：https://docs.unity3d.com
※ 製品スペック（リフレッシュレートやチップ名など）は時期により変化します。数値の確認は公式の技術仕様ページやリリースノートで“要確認”としてください。
補助資料（コミュニティ記事・個人レポート）
- Unity 実践記事（参考）：Zenn 等の実装記事（補助情報として活用）。
- 個人ブログや報告記事：実機レポートは参考になりますが、公式情報ではないため注意して利用してください（補助情報）。
- メディア記事（製品レビュー等）：スペックの確認は公式に戻すこと。
まとめ
最初は公式サンプルを一つ動かして環境と接続を確かめ、その後にハンドトラッキングやアンカー、デプスメッシュを順に実装・検証する流れを推奨します。導入段階での優先事項は（1）SDK バージョン固定とサンプルでの動作確認、（2）デバイス仕様の公式確認（要確認）、（3）EULA とクラウドサービスのデータ保持／リージョン制約に関する法務確認です。実務ではログ（adb logcat）と Profiler を利用して問題を再現できる形で共有し、段階的に最適化と公開手順を進めてください。
主要アクション（短いチェックリスト）：
- 公式 SDK を取得してサンプルをビルドし実機で起動する。
- PlayerSettings：IL2CPP、ARM64、minSdkVersion（目安 26）、targetSdkVersion（要確認）を設定する。
- Manifest に必要権限を宣言し、ランタイムで許可を要求するコードを準備する。
- 代表的なエラー（ABI ミスマッチ、UnsatisfiedLinkError、権限エラー）に対する対処手順を用意する。
- EULA／プライバシー／クラウドサービスのデータ保持条件を法務と確認する。