plan-4ging

2026/03/21

unity #android#gradle#logcat#unity

ビルド・プロジェクト設定

環境セットアップ

Unity Hub → Installs → 対象 version → Add Modules
　→ Android Build Support：☑︎
　→ Android SDK & NDK Tools：☑︎
　→ OpenJDK：☑︎

Player Settings

File → Build Settings → Player Settings → Android タブ
設定項目概要推奨値
Package Nameアプリの一意識別子com.会社名.アプリ名
Versionユーザー向けバージョン表示1.0.0
Bundle Version Codeストア管理用の整数値リリースごとに必ず増加
Minimum API Level要求する最低限の API Level
Target API Levelターゲット API Level
Scripting Backendコード実行方式IL2CPP
Target Architectures対象 CPU アーキテクチャARM64 必須

Scripting Backend：Mono vs IL2CPP

MonoIL2CPP
ビルド速度速い遅い
実行速度普通速い
用途開発中本番リリース

デバッグ方法

ログ出力

// 本番ビルドでのログ制御（条件付きコンパイル）
public static class GameLogger
{
    [System.Diagnostics.Conditional("DEVELOPMENT_BUILD")]
    [System.Diagnostics.Conditional("UNITY_EDITOR")]
    public static void Log(string message)
    {
        // Development Build 以外では呼び出し自体がコンパイル時に除去される
        Debug.Log(message);
    }
}

ログ確認（Logcat）

実機デバッグの基本となる、Android システム全体のログを出力・確認するツール
Unity の Debug.Log も出力される

Android Logcat パッケージ（推奨）

Unity Editor 上で Logcat を確認できる
フィルタ・カラー分類などが使えてデバッグ効率が大幅に上がる

Package Manager → Unity Registry → Android Logcat を追加
Window → Analysis → Android Logcat

adb（Android Debug Bridge）

USB デバッグを有効にした実機を接続して以下のコマンドを使う

# デバイスの接続確認
adb devices
# Logcat のリアルタイム出力
adb logcat
# Unity のログのみフィルタ（タグで絞り込む）
adb logcat -s Unity
# 特定のパッケージのみ表示（Android 7.0 以降）
adb logcat --pid=$(adb shell pidof -s com.yourcompany.yourapp)
# ログをファイルに保存
adb logcat -s Unity > unity_log.txt
# ログレベルでフィルタ（E=Error W=Warn I=Info D=Debug V=Verbose）
adb logcat *:E

クラッシュ時のデバッグ

tombstones を確認する

# クラッシュ時のトゥームストーン（詳細クラッシュログ）を確認
adb bugreport > bugreport.zip
# → zip を展開して tombstones フォルダを確認

# IL2CPP のクラッシュは symbolicate が必要
# ビルド時に生成される symbols.zip を保管しておく
# → Firebase Crashlytics に symbols をアップロードするとシンボル付きスタックトレースが見られる

配布方法（APK/AAB）

APK（Android Package）

Android アプリの従来の配布形式
1ファイルにすべてのアーキテクチャ・リソースが含まれる

AAB（Android App Bundle）

Google Play での配布専用の形式
Google Play がデバイスに合わせて最適な APK を生成して配信する

# keystore の生成
keytool -genkey ...

ビルドシステム

Gradle

Android ビルドシステム
Unity が Android 向けにビルドする際、内部的に Gradle を使って APK / AAB を生成する

Unity C# コード
　↓ IL2CPP でネイティブコードに変換
Android プロジェクト（Java / Kotlin / C++）を生成
　↓ Gradle がコンパイル・パッケージング
APK / AAB を生成

Gradle ファイルの場所と構成

Unity プロジェクトの Assets/Plugins/Android/ 以下にカスタム Gradle ファイルを置くことで設定を上書きできる

Assets/Plugins/Android/
　├ mainTemplate.gradle      ← アプリのメイン設定
　├ gradleTemplate.properties ← Gradle のプロパティ設定
　├ launcherTemplate.gradle   ← ランチャー設定
　└ baseProjectTemplate.gradle ← プロジェクト全体設定
// mainTemplate.gradle の例
// 依存ライブラリの追加
dependencies {
    implementation 'com.google.firebase:firebase-analytics:21.5.0'
    implementation 'com.google.android.gms:play-services-ads:22.6.0'
    // **DEPS**  ← Unity が自動追記するため消さない
}

android {
    defaultConfig {
        // **APPLICATIONID** は Unity が自動置換
        applicationId "**APPLICATIONID**"
        minSdkVersion **MINSDKVERSION**
        targetSdkVersion **TARGETSDKVERSION**

        // マルチデックス対応（メソッド数が上限を超える場合）
        multiDexEnabled true
    }
}

Android 権限・パーミッション管理

パーミッション種類

種別概要対応
通常権限インターネットアクセスなどAndroidManifest.xmlに宣言（自動付与）
危険権限カメラ・位置情報・マイクなどAndroidManifest.xmlに宣言 + 実行時にユーザーへの許可ダイアログが必要

AndroidManifest.xml 設定

Unity の Assets/Plugins/Android/AndroidManifest.xml に配置する

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <!-- 通常権限（自動付与） -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

    <!-- 危険権限（実行時ダイアログが必要） -->
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

    <application>
        <!-- ... -->
    </application>
</manifest>

注意点

ビルド関連

ARM64 を忘れる

  • Target Architectures に ARMv7（32bit）のみ指定すると Google Play の 64bit 要件に違反してリジェクトされる
  • ARM64 を必ず含める（ARMv7 は削除）

Bundle Version Code の重複

  • Google Play は同じ Bundle Version Code のアップロードを拒否する
  • CI/CD でビルドごとに自動インクリメントする仕組みを作る

Development Build のまま本番アップロード

  • Development Build が ON だと
    • パフォーマンスが低下する
    • Profiler 接続用のポートが開いたまま
  • 本番ビルドは必ず Development Build を OFF にする
    • File → Build Settings を開く
    • 画面下部の「Development Build」チェックボックスを OFF にする
    • Build を実行する

Gradle 関連

Gradle バージョンの競合

  • Unity のバージョンアップに伴い対応 Gradle バージョンが変わる
  • 外部プラグインの要求バージョンと競合してビルドが通らないことがある
  • まず Unity の推奨 Gradle バージョンを確認してから baseProjectTemplate.gradleの classpath を調整する

マルチデックス（MultiDex）問題

  • 依存ライブラリが増えるとメソッド数が上限を超えて “Cannot fit requested classes in a single dex file” エラーが出る

  • mainTemplate.gradleにmultiDexEnabled trueを追加する

  • https://developer.android.com/build/multidex?hl=ja

minifyEnabled によるクラス削除

実機デバッグ関連

USB デバッグが有効になっていない

  • 開発者オプション → USB デバッグ を ON にする必要がある

adb で複数デバイスが繋がっている場合

  • adb devices で SERIAL を確認して adb -s SERIAL logcat のように指定する

Logcat が大量のログで埋もれる

  • Unity タグでフィルタするか、Android Logcat パッケージの Filter 機能でパッケージ名指定フィルタを活用する

実機とエミュレータでの挙動の違い

  • GPU・メモリ・センサーの挙動は実機と異なる場合がある
  • パフォーマンステストは必ず実機で行う

参考

Back