ランタイム リソース オーバーレイのトラブルシューティング

ランタイム リソース オーバーレイ（RRO）が Android Automotive の実装で意図したとおりに動作しない原因のトラブルシューティングを行う際は、このコンテンツをご利用ください。

Android での RRO について詳しくは、ランタイム リソース オーバーレイ（RRO）をご覧ください。logcat の出力には常に注意しておくようにしてください。プロセス全体でどのような処理が行われているかについて適切な情報が得られます。

ステップ 1: RRO を一覧表示する

RRO を一覧表示するには:

  1. 次のコマンドを実行します。

    adb shell cmd overlay list --user current

    次のような出力が表示されます。

    com.android.systemui
[ ] com.android.theme.icon_pack.rounded.systemui
[ ] com.android.theme.icon_pack.filled.systemui
[ ] com.android.theme.icon_pack.circular.systemui

com.android.permissioncontroller
--- com.android.permissioncontroller.googlecarui.rro

  2. RRO が一覧に表示されていることを確認します。次のインジケーターは、RRO ステータスを示します。

    インジケーター RRO ステータス
    [ ] インストールされ、有効にする準備が整いました。
    [X] インストールされ、有効になりました。
    --- インストールされましたが、エラーがあります。

    オーバーレイするターゲットのパッケージ名の下に RRO が表示されていない場合、RRO はインストールされていません。

ステップ 2: RRO を有効または無効にする

RRO がインストールされている場合:

  1. RRO を有効（または無効）にするには、次のコマンドを使用します。

    adb shell cmd overlay [enable/disable] --user current [your RRO package name]

ステップ 3: RRO がインストールされていることを確認する

RRO がデバイスにインストールされていることを確認する場合や、RRO が有効になっていない原因をトラブルシューティングするには、次の手順を行います。

  1. 次のコマンドを実行します。

    adb shell cmd overlay dump [your RRO package name]

    以下のような出力が表示されます。

    com.android.car.rotaryplayground.googlecarui.rro:0 {
  mPackageName...........: com.android.car.rotaryplayground.googlecarui.rro
  mUserId................: 0
  mTargetPackageName.....: com.android.car.rotaryplayground
  mTargetOverlayableName.: car-ui-lib
  mBaseCodePath..........: /product/overlay/googlecarui-com-android-car-rotaryplayground/googlecarui-com-android-car-rotaryplayground.apk
  mState.................: STATE_MISSING_TARGET
  mIsEnabled.............: true
  mIsMutable.............: true
  mPriority..............: 10
  mCategory..............: BypassIdMapV1
}
com.android.car.rotaryplayground.googlecarui.rro:10 {
  mPackageName...........: com.android.car.rotaryplayground.googlecarui.rro
  mUserId................: 10
  mTargetPackageName.....: com.android.car.rotaryplayground
  mTargetOverlayableName.: car-ui-lib
  mBaseCodePath..........: /product/overlay/googlecarui-com-android-car-rotaryplayground/googlecarui-com-android-car-rotaryplayground.apk
  mState.................: STATE_MISSING_TARGET
  mIsEnabled.............: true
  mIsMutable.............: true
  mPriority..............: 10
  mCategory..............: BypassIdMapV1
}

  2. RRO をインストールした 1 人または複数のユーザーを特定します。上記の例では、RRO がユーザー 0 とユーザー 10 で利用できます（上のコードブロックの mUserId の値を参照してください）。

  3. 希望するユーザーで RRO を有効（または無効）にするには、ステップ 2 に進みます。

  4. mState の値を確認するには、次の値を確認します。

    • STATE_ENABLED と STATE_ENABLED_IMMUTABLE。RRO は有効になっており、ターゲットに適用されています。

    • STATE_MISSING_TARGET。ターゲットがインストールされていません。

    • STATE_NO_IDMAP。AndroidManifest.xml、overlays.xml、または overlayable.xml のファイルの設定方法に問題があります。adb logcat を使用してログを実行し、キーワード idmap を検索してエラーを特定します。ステップ 4 と 5 をご覧ください

    • STATE_UNKNOWN。OverlayManagerService に問題があります。

ステップ 4: AndroidManifest.xml を確認する

AndroidManifest.xml を確認するには:

  1. targetName と targetPackage を確認します。

    android:targetName には、ターゲット アプリで定義されているオーバーレイ可能なグループと同じ値を指定する必要があります。これは、オーバーレイをターゲットとする場合にのみ必須です。

    android:targetPackage は常に必須であり、ターゲット アプリのパッケージ名を含める必要があります。

  2. RRO が静的である（または静的でない）ことを確認します。静的 RRO は、起動時にデフォルトで有効になっています。動的 RRO は、起動時にデフォルトでは有効になっていません。動的 RRO を有効にするその他の方法については、ランタイム リソース オーバーレイ（RRO）をご覧ください。

  3. 静的 RRO の優先度を確認します（動的 RRO の優先度は常に Integer.MAX_VALUE に設定されており、適用される順序は有効になるタイミングに基づいて決まります）。

    複数の RRO が同じターゲットに適用される場合があります。優先度の高い RRO が最後に適用されます。0～10 の範囲で、10 の優先度が最も高く、0 の優先度が最も低くなります。

ステップ 5: overlays.xml を確認する

この確認は、Android 11 以降のみに適用されます。

  1. overlays.xml を確認して、オーバーレイするすべてのリソースがこのファイルで定義されていることを確認します。たとえば、次の overlays.xml について考えてみます。

    <overlay>
    <item target="string/app_name" value="@string/overlaid_app_name" />
</overlay>

  2. 以下を確認する必要があります。

    • ターゲット アプリに app_name という名前の string リソースが存在する。
    • RRO に overlaid_app_name という名前の string リソースが存在する。

  3. ターゲットに overlayable.xml ファイルがある場合は、そのファイルに app_name が含まれていることを確認してください。AndroidManifest.xml ファイルで正しい targetName を使用していることを確認してください（ステップ 4）。

    例:

    <overlay>
<item target="layout/car_ui_base_layout_toolbar" value="@layout/car_ui_base_layout_toolbar" />
<item target="id/car_ui_toolbar_background" value="@id/car_ui_toolbar_background" />
<item target="attr/layout_constraintTop_toBottomOf" value="@attr/layout_constraintTop_toBottomOf" />
</overlay>

ステップ 6: idmap をダンプする

この段階で、RRO に関するすべての問題が解決しているはずです。次に、RRO の idmap をダンプして、どのようにリソースが解決されているか、なぜ予想とは異なる値に解決しているかを調べます。

  1. デバイスの idmap へのパスを調べるには:

    adb shell
su
ls data/resource-cache

  2. ファイルの内容をダンプするには:

    idmap2 dump --idmap-path [path to your RRO idmap file]

    出力は次のようになります。出力には、RRO のどの ID がターゲット内のどの ID にマッピングされているか、およびオーバーレイされたリソースの名前が表示されます。

    target apk path : /system/priv-app/CarMediaApp/CarMediaApp.apk
overlay apk path : /product/overlay/googlecarui-com-android-car-media/googlecarui-com-android-car-media.apk
0x7f040008 -> 0x7f010000 bool/car_ui_toolbar_logo_fills_nav_icon_space
0x7f040009 -> 0x7f010001 bool/car_ui_toolbar_nav_icon_reserve_space
0x7f04000b -> 0x7f010002 bool/car_ui_toolbar_tab_flexible_layout
0x7f04000c -> 0x7f010003 bool/car_ui_toolbar_tabs_on_second_row
0x7f09006c -> 0x7f020000 id/car_ui_base_layout_content_container
0x7f090073 -> 0x7f020001 id/car_ui_recycler_view
0x7f090074 -> 0x7f020002 id/car_ui_scroll_bar
0x7f090075 -> 0x7f020003 id/car_ui_scrollbar_page_down
0x7f090076 -> 0x7f020004 id/car_ui_scrollbar_page_up
0x7f090077 -> 0x7f020005 id/car_ui_scrollbar_thumb
0x7f090078 -> 0x7f020006 id/car_ui_scrollbar_track
0x7f09007a -> 0x7f020007 id/car_ui_toolbar_background
0x7f09007e -> 0x7f020008 id/car_ui_toolbar_logo
0x7f090084 -> 0x7f020009 id/car_ui_toolbar_menu_items_container
0x7f090085 -> 0x7f02000a id/car_ui_toolbar_nav_icon
0x7f090086 -> 0x7f02000b id/car_ui_toolbar_nav_icon_container
0x7f090087 -> 0x7f02000c id/car_ui_toolbar_progress_bar
0x7f090089 -> 0x7f02000d id/car_ui_toolbar_row_separator_guideline
0x7f09008d -> 0x7f02000e id/car_ui_toolbar_search_view_container
0x7f09008f -> 0x7f02000f id/car_ui_toolbar_subtitle
0x7f090092 -> 0x7f020010 id/car_ui_toolbar_tabs
0x7f090093 -> 0x7f020011 id/car_ui_toolbar_title
0x7f090094 -> 0x7f020012 id/car_ui_toolbar_title_container
0x7f090095 -> 0x7f020013 id/car_ui_toolbar_title_logo
0x7f090096 -> 0x7f020014 id/car_ui_toolbar_title_logo_container
0x7f0c0024 -> 0x7f030000 layout/car_ui_base_layout_toolbar
0x7f0c0035 -> 0x7f030001 layout/car_ui_recycler_view
0x7f0c0038 -> 0x7f030002 layout/car_ui_toolbar
0x7f0c003f -> 0x7f030003 layout/car_ui_toolbar_two_row

特定のリソースを検索してマッピング状況を確認するには、次のコマンドを使用します。

adb shell cmd overlay lookup --verbose --user 10 com.android.car.ui.paintbooth com.android.car.ui.paintbooth:color/widget_background

出力はリソースの最終値です。

#ff7986cb

また、apk からレイアウト ファイルをダンプして、上記の出力と一致するように解決された ID を表示することもできます。

aapt2 dump xmltree $OUT/system/priv-app/sharedlibraryclient/sharedlibraryclient.apk --file res/layout/activity_main.xml

次のような出力が返されます。

N: android=http://schemas.android.com/apk/res/android (line=2)
  N: app=http://schemas.android.com/apk/res-auto (line=2)
    N: lib=http://schemas.android.com/apk/com.android.car.ui.sharedlibrary.test (line=2)
      E: androidx.constraintlayout.widget.ConstraintLayout (line=2)
        A: http://schemas.android.com/apk/res/android:layout_width(0x010100f4)=-1
        A: http://schemas.android.com/apk/res/android:layout_height(0x010100f5)=-1
          E: TextView (line=19)
            A: http://schemas.android.com/apk/res/android:layout_width(0x010100f4)=-2
            A: http://schemas.android.com/apk/res/android:layout_height(0x010100f5)=-2
            A: http://schemas.android.com/apk/res/android:text(0x0101014f)=@0x020f0000
            A: http://schemas.android.com/apk/res-auto:layout_constraintBottom_toBottomOf(0x7f0200fb)=0
            A: http://schemas.android.com/apk/res-auto:layout_constraintLeft_toLeftOf(0x7f02010e)=0
            A: http://schemas.android.com/apk/res-auto:layout_constraintRight_toRightOf(0x7f020112)=0
            A: http://schemas.android.com/apk/res-auto:layout_constraintTop_toTopOf(0x7f020118)=0
          E: com.android.car.ui.sharedlibrary.test.MyRecyclerView (line=28)
            A: http://schemas.android.com/apk/res/android:layout_width(0x010100f4)=-2
            A: http://schemas.android.com/apk/res/android:layout_height(0x010100f5)=-2
            A: http://schemas.android.com/apk/com.android.car.ui.sharedlibrary.test:implClass="HelloWorld!" (Raw: "HelloWorld!")
          E: com.android.car.ui.sharedlibraryclient.CustomView (line=34)
            A: http://schemas.android.com/apk/res/android:layout_width(0x010100f4)=-2
            A: http://schemas.android.com/apk/res/android:layout_height(0x010100f5)=-2
            A: http://schemas.android.com/apk/res-auto:implClass2(0x7f0200e8)="HelloWorld!!" (Raw: "HelloWorld!!")