Android のシンボル

Unity はアプリケーションのデバッグに役立つパッケージを生成できます。このパッケージに含まれているシンボルファイルには、Unity のネイティブライブラリ用のデバッグメタデータがあります。シンボルファイル内のシンボルテーブル (.symtab) という実行ファイルセクションは、アクティブなメモリアドレスをメソッド名などの使用可能な情報に変換します。この変換プロセスをシンボリケーションといいます。シンボルパッケージを Google Play Console にアップロードして、人間が読めるスタックトレースを Android Vitals ダッシュボードに表示できます。

実行ファイル (ELF) セクションの詳細は、Wikipedia を参照してください。

以下のライブラリ用のシンボルファイルを生成することができます。

• libmain: 最初の Unity エンジンのロードロジックに関連します。シンボルファイルはプリコンパイルされます。

• libunity: Unity のエンジンコード:

  • Strip Engine Code プロパティが無効の場合、シンボルファイルはプリコンパイルされます。
  • Strip Engine Code プロパティが有効の場合、ビルドプロセス中にシンボルファイルがコンパイルされます。

• libil2cpp: C# スクリプトが含まれています。

  • プロジェクトをエクスポートしない場合、Unity がビルドプロセス中にシンボルファイルをコンパイルします。
  • プロジェクトをエクスポートする場合、Gradle がシンボルファイルをコンパイルします。

Gradle がその他のシンボルファイルを生成します。

アプリケーションのビルド形式に応じて、Unity は 2 つの方法でシンボルファイルを生成します。

• apk または aab の zip ファイルとして生成できます。
• シンボルファイルを aab に直接埋め込みます。Unity は apk にはシンボルファイルを埋め込みません。

UserBuildSettings.DebugSymbols.format API を使用して、シンボルパッケージの形式を設定します。

シンボルファイルの種類

Unity は Gradle の debugSymbolLevel プロパティを使用してシンボルファイルを生成します。シンボルファイルには 2 種類あります。

• Public: シンボルテーブルセクションを含む小さなファイル。詳細は、パブリックシンボル を参照してください。
• Debugging: パブリックシンボルファイルに含まれるすべての情報と、より詳細なデバッグに使用できる完全なデバッグ情報が含まれています。詳細は、デバッグシンボル を参照してください。

UserBuildSettings.DebugSymbols.level を使用して、必要な種類のシンボルファイルを生成します。

注意デフォルトでは、Gradle は .so.sym または .so.dbg 拡張子を持つシンボルファイルを生成します。デジタル配信サービスによっては、これらの拡張子が認識されず、.so 拡張子を持つファイルが必要です。そのような場合は、Unity.Android.Types.DebugSymbolFormat.LegacyExtensions API を使用して、.so 拡張子を持つシンボルファイルを作成します。

UserBuildSettings.DebugSymbols.format = DebugSymbolFormat.IncludeInBundle | DebugSymbolFormat.Zip | DebugSymbolFormat.LegacyExtensions;

パブリックシンボル

パブリックシンボルファイルには、関数のアドレスを人間が読める文字列に解決する情報が含まれています。これらのファイルにデバッグ情報は含まれません。そのため、パブリックシンボルファイルは デバッグシンボル ファイルよりも小さくなります。

デバッグシンボル

デバッグシンボルファイルには、完全なデバッグ情報とシンボルテーブルセクションが含まれています。このファイルを以下の目的に使用できます。

• スタックトレースを解決し、ソースコードが利用可能なアプリケーションをデバッグすることができます。
• アプリケーションにネイティブデバッガーを取り付け、コードをデバッグします。

注意デバッグシンボルを利用できない場合、Unity はビルド時に パブリックシンボル ファイルをプロジェクトに配置します。libmain と libunity のライブラリにデバッグシンボルは利用できないため、Unity は常にパブリックファイルを生成します。

カスタムシンボル

シンボルファイルを追加するように Unity に指示できます。これが役に立つのは、共有ライブラリを使用していて、アプリケーションがクラッシュしたときに、ローカルデバッガーと Google Play で共有ライブラリのスタックトレースを解決する場合です。

カスタムシンボルファイルを追加するように Unity に指示する手順は以下のとおりです。

1. Project ウィンドウで、.so ファイル拡張子を持つプラグインを選択します。
2. Inspector で Platform settings セクションを見つけます。
3. シンボルファイルと互換性のある CPU アーキテクチャに CPU を設定します。
4. Shared Library Type を Symbol に設定します。

Unity はシンボルパッケージを生成するたびに、シンボルパッケージにシンボルファイルを追加します。

C# スクリプトのカスタムシンボルファイルを加えるように Unity に指示するには、UnityEditor.Android 名前空間に以下の API を加えます。以下の API は CPU と Shared Library Type をそれぞれ設定します。

• PluginImporter.SetAndroidCPU
• PluginImporter.SetAndroidSharedLibraryType

注意シンボルファイル名は、シンボルファイルの対象となる共有ライブラリの名前と一致する必要があります。例えば、共有ライブラリの名前が mylibrary.so の場合、シンボルファイルの名前も mylibrary.so である必要があります。ファイル名の衝突を避けるために、シンボルファイルと共有ライブラリは別々のディレクトリに置く必要があります。

重要:シンボルファイルが最新であり、実行ファイルコードを含む共有ライブラリと互換性のあることを確認してくだい。そうしないと、ローカルデバッガーと Google Play で共有ライブラリのコードのスタックトレースを解決できません。

シンボルパッケージの生成

アプリケーションのシンボルパッケージ生成を有効にするには、2 つの方法があります。

• Build Settings ウィンドウを使用する。
• UserBuildSettings.DebugSymbols.level API と UserBuildSettings.DebugSymbols.format API を使用する。

Build Settings ウィンドウでシンボルパッケージの生成を有効にするには、次の手順に従います。

1. Build Profiles ウィンドウを開きます (メニュー: File > Build Profiles)。

2. Android プラットフォームを選択します。

3. Debug Symbols を以下のいずれかに設定します。

   • 一般公開
   • デバッグ

4. Symbols output options を .zip に設定します。

シンボルパッケージの生成を有効にしてから、プロジェクトをビルドすると、.zip ファイルが生成されます。このファイルは、libmain と libunity のライブラリ用のシンボルファイルを含みます。scripting backend を IL2CPP に設定すると、.zip には libil2cpp ライブラリ用のシンボルファイルも含まれるようになります。Unity は、このシンボルパッケージを出力ディレクトリ内に置きます。

Android Build Settings で Export Project を有効にすると、Unity はプロジェクトをビルドしません。代わりに、Unity は Android Studio のプロジェクトをエクスポートし、libmain と libunity のシンボルを生成して、出力ディレクトリの unityLibrary/symbols/<architecture>/ 内に配置します。Android Studio からエクスポートしたプロジェクトをビルドすると、Gradle が libil2cpp シンボルファイルを生成し、libmain と libunity のシンボルファイルとともに unityLibrary/symbols/<architecture>/ ディレクトリ内に配置します。

Google Play コンソールでのシンボルの使用

埋め込まれたシンボル

Android App Bundle (aab) を生成する場合は、シンボルを aab に直接埋め込み、Google Play にアップロードすることができます。

注意Unity はシンボルを apk に埋め込みません。この場合、シンボルを含む zip ファイルを別途アップロードする必要があります。

UserBuildSettings.DebugSymbols.level = DebugSymbolLevel.SymbolTable;
UserBuildSettings.DebugSymbols.format = DebugSymbolFormat.IncludeInBundle;

Zip で圧縮されたシンボル

Zip で圧縮されたシンボルパッケージを生成するには、以下のコードを使用します。

UserBuildSettings.DebugSymbols.level = DebugSymbolLevel.SymbolTable;
UserBuildSettings.DebugSymbols.format = DebugSymbolFormat.Zip | DebugSymbolFormat.LegacyExtensions;

アプリケーションを Google Play にアップロードしたら、パブリックシンボル の zip パッケージをアップロードできます。この方法については、Google のドキュメント クラッシュのスタックトレースの難読化を解除する、シンボリケートする を参照してください。

注意Google Play は、シンボルパッケージをアップロードする前のアプリケーションのクラッシュはシンボリケートしません。