Flutterチュートリアル:アプリを最新のV2 Android埋め込みに移行する完全ガイド

Flutterの初期から開発に携わっている方なら、バージョン1.12以前の時代に作成されたプロジェクトを1つや2つお持ちかもしれません。その場合、プロジェクトで「Pub get」を実行するたびに、以下のようなメッセージを目にしたことがあるでしょう。

This app is using a deprecated version of the Android embedding.
To avoid unexpected runtime failures, or future build failures, try to migrate this app to the V2 embedding.

警告には移行手順を記載した公式ドキュメント(Upgrading pre-1.12 Android projects)へのリンクが添えられていますが、ドキュメントだけでは「何を」「どこで」変更すればよいのか分かりにくいことがあります。

本記事では、FlutterアプリケーションをV2 Embeddingに移行し、この警告を完全に解消するための手順を一つずつ丁寧に解説していきます。

自動移行 – 手軽な方法

まず知っておいてほしいのは、アプリを簡単に作り直せるのであれば、この移行作業自体を省略できるという点です。具体的にはどういうことでしょうか。

アプリケーションのコードが複雑でない場合、libフォルダ内のファイルを保存しておき、flutter createコマンドで新しいプロジェクトを作成すればOKです。こうして作成されたプロジェクトはすでにV2 Embeddingへ移行済みなので、あとはlibフォルダのコードをコピー&ペーストするだけで完了します。

ただし、プロジェクトが複雑な場合、たとえばプラットフォーム固有のコードを含むパッケージであるようなケースでは、手動での移行の方が適しています。

手動移行 – 以下の手順に従ってください

1. アプリ内のMainActivity.kt(または .java)ファイルを開きます。
2. 固有のロジックが記述されていない限り、ファイル内の内容をすべて削除し、クラス宣言だけを残します。
3. すべてのimport文を削除し、次の1行のみを残します。

import io.flutter.embedding.android.FlutterActivity;

最終的なファイルは以下のようになります。

import io.flutter.embedding.android.FlutterActivity;
public class MainActivity extends FlutterActivity { 
 // ここには何も書かない
}

1. AndroidManifest.xmlファイルを開き、applicationタグ内のname属性を${applicationName}に変更します。以下のようになります。

<application 
 android:name="${applicationName}"> 
 .... 
</application>

1. applicationタグ内に、次のmeta-dataを追加します。

<meta-data 
 android:name="flutterEmbedding" 
 android:value="2" />

1. 特定のスプラッシュ画面の挙動が必要な場合は、スプラッシュ画面用のmetaタグを削除します。

<meta-data android:name="io.flutter.app.android.SplashScreenUntilFirstFrame" android:value="true" />

1. 続いてstyles.xmlファイルを開き、お好みのdrawableでLaunchThemeを設定します。

<?xml version="1.0" encoding="utf-8"?>
<resources> 
 <style name="LaunchTheme" parent="@android:style/Theme.Black.NoTitleBar"> <item name="android:windowBackground">@drawable/launch_background
 </item> 
 </style>
</resources>

以上の変更をすべて適用すると、AndroidManifest.xmlは次のようになります。

<manifest xmlns:android="https://schemas.android.com/apk/res/android" package="PACKAGE_NAME">
<application 
 android:name="${applicationName}" 
 android:label="APPLICATION_LABEL" 
 android:icon="@mipmap/ic_launcher"> 
 <activity 
 android:name=".MainActivity"
 android:exported="true" 
 android:launchMode="singleTop" android:theme="@style/LaunchTheme" android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode" android:hardwareAccelerated="true" android:windowSoftInputMode="adjustResize"> 
 <intent-filter> 
 <action android:name="android.intent.action.MAIN"/> <category android:name="android.intent.category.LAUNCHER"/> 
 </intent-filter> 
 </activity> 
 <meta-data 
 android:name="flutterEmbedding" 
 android:value="2" /> 
</application>
</manifest>

AndroidXへの対応

さらに、古いサポートライブラリの代わりにAndroidXライブラリを使用するよう、プロジェクトの移行が必要になる場合もあります。アプリをビルドして実行すると、次のような警告が表示されます。

Your app isn't using AndroidX. To avoid potential build failures, you can quickly migrate your app by following the steps on https://goo.gl/CP92wY.

この問題の修正は非常に簡単です。Android StudioにはAndroidXへの移行機能が標準で組み込まれているためです。

まず、FlutterアプリケーションのAndroidフォルダをスタンドアロンプロジェクトとして開きます。

メニューバーから [Refactor] → [Migrate to AndroidX] を選択します。

AndroidXへ移行するためのドロップダウンメニュー

その後、プロジェクトのコピーを保存するよう求められるので、保存を済ませると移行処理が自動的に実行されます。

発生する可能性のあるエラー

移行作業の途中で、アプリのビルド時にいくつかのエラーに遭遇することがあります。代表的なものは以下の3つです。

• Unable to get mutable Windows environment variable map(変更可能なWindows環境変数マップを取得できません)
• cvc-complex-type.2.4.a: Invalid content was found starting with element 'base-extension'. One of '{layoutlib}' is expected(要素'base-extension'以降のコンテンツが無効です。'{layoutlib}'が想定されています)
• Warning: This version only understands SDK XML versions up to 2 but an SDK XML file of version 3 was encountered...(このバージョンはSDK XMLバージョン2までしか認識できませんが、バージョン3のSDK XMLファイルが検出されました)

最初の2つのエラーは互いに関連しており、同じ根本原因から発生しています。原因は、プロジェクトが古いバージョンのGradleでセットアップされていることであり、Gradleのアップグレードが必要です。

対応するには、以下の手順に従います。

1. FlutterアプリケーションのAndroidフォルダをスタンドアロンプロジェクトとして開きます。
2. [File] → [Project Structure] をクリックします。

Project Structureを選択するドロップダウンメニュー

1. Gradleのバージョンをより新しいものに変更し、現在使用中のAndroid Studioのバージョンと一致させます。

AGPとGradleの設定画面

また、[Tools] → [AGP Upgrade Assistant] からAGP Upgrade Assistantを利用して、同じ作業を行うことも可能です。

AGP Upgrade AssistantでAGPをアップグレードするドロップダウンメニュー

3つ目の問題は警告ですが、古いバージョンのAndroid SDK Toolsが原因である可能性があります。SDK Toolsを最新版に更新することで解決できます。

以上の手順を完了すれば、プロジェクトは完全に移行され、スムーズにコンパイルおよび実行できるはずです。

無料でプログラミングを学びましょう。freeCodeCampのオープンソースカリキュラムは、40,000人以上の人々を開発者としての就職へと導いてきました。ぜひ今すぐ始めてみてください。