はじめに (対象読者・この記事でわかること)

本記事は、Flutter でモバイルアプリを開発しているエンジニア、もしくはこれから始めようと考えている初心者を対象としています。特に FlutterFire の master ブランチにあるサンプルコード を Android Studio 上でビルドし、実機またはエミュレータで動作させたい方に最適です。この記事を読むことで、以下ができるようになります。

  • FlutterFire の環境構築手順と、必要なプラグインのインストール方法
  • Android Studio でサンプルプロジェクトをクローンし、適切にビルド・実行する一連の流れ
  • ビルド時に遭遇しやすいエラー（Google‑services.json の欠如や AndroidX の不整合など）への対処法

執筆のきっかけは、公式サンプルが「動かすだけで完了」ではなく、環境依存のトラブルが多く報告されている点に注目したためです。実務で即座に Firebase 機能を検証したい方の助けになることを願っています。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。

  • Flutter の基本操作（flutter doctor、flutter run など）
  • Android Studio のインストールと基本的なプロジェクト操作
  • Firebase コンソールへのアクセス権限（プロジェクト作成ができること）

FlutterFire master サンプルの概要と必要性

FlutterFire は、Flutter アプリと Google の Firebase サービス（Authentication、Firestore、Analytics など）をシームレスに結びつける公式プラグイン群です。公式リポジトリ（flutter/plugins）の flutterfire_master ブランチには、最新の API 変更を取り入れた実装例が多数掲載されています。

このサンプルは、「Firebase Core」「Authentication」「Firestore」 を組み合わせたシンプルな TODO アプリとして提供されており、次のような学習効果があります。

  1. プラグインのバージョン管理：pubspec.yaml に記載された最新の依存関係を確認できる。
  2. Firebase 設定ファイルの扱い：google-services.json（Android）や GoogleService-Info.plist（iOS）の配置場所と内容を実践的に学べる。
  3. プラットフォーム固有の設定：Android の android/app/build.gradle や Xcode の Runner 設定を通じて、ネイティブ側の調整が必要な理由を体感できる。

実際に手元でサンプルが動作すれば、「Flutter だけでなく、Firebase も本格的に使える」 という自信が得られ、プロジェクトへの応用が容易になります。

Android StudioでFlutterFire masterサンプルを実行する手順

以下では、0 からサンプルをクローンし、Android Studio でビルド・実行するまでの具体的なステップを紹介します。各ステップは実際に手を動かしながら確認できるよう、コマンド例やスクリーンショット想定の説明も交えます。

ステップ1　環境の事前確認と Flutter SDK の最新化

  1. Flutter が正しくインストールされているか確認
    bash flutter doctor -v
    出力に Android toolchain、Android Studio、Connected device が全て ✓ であることを確認します。警告が出た場合は、指示に従い SDK のインストールやパス設定を行います。

  2. Flutter の最新版へアップデート
    bash flutter upgrade
    これにより、FlutterFire の最新プラグインがサポートする SDK バージョンと同期できます。

  3. Android Studio のプラグインを最新化
    - Preferences > Plugins → Flutter と Dart が最新か確認し、必要に応じてアップデート。

ステップ2　サンプルリポジトリの取得とプロジェクト構成の確認

  1. GitHub から flutterfire_master のサンプルをクローン
    bash git clone https://github.com/FirebaseExtended/flutterfire.git cd flutterfire # master ブランチをチェックアウト git checkout master # 目的のサンプルディレクトリへ移動 cd examples/todo_app

  2. 依存パッケージの取得
    bash flutter pub get
    ここで firebase_core, cloud_firestore, firebase_auth などが pubspec.yaml に基づいて自動的にダウンロードされます。

  3. Android 用設定ファイルの配置
    - Firebase コンソールで新規プロジェクト（例: flutterfire-todo）を作成し、Android アプリを追加。パッケージ名は com.example.todo_app がデフォルトです。
    - google-services.json をダウンロードし、android/app/ ディレクトリに配置します。重要：ファイル名はそのままで、拡張子や場所を変更しないこと。

  4. Gradle 設定の追記
    android/build.gradle の dependencies セクションに以下を追加（プラグインが既に入っているはずですが、念のため確認）:
    gradle classpath 'com.google.gms:google-services:4.3.15'
    android/app/build.gradle の末尾に apply plugin: 'com.google.gms.google-services' を記述します。

ステップ3　Android Studio でプロジェクトを開く

  1. Android Studio の起動 → File > Open → todo_app ディレクトリを指定。
  2. 初回起動時に Gradle Sync が自動で走りますが、エラーが出た場合は File > Invalidate Caches / Restart を試してください。
  3. エミュレータまたは実機の接続：Android Virtual Device (AVD) を作成し、Google Play サポートがあるイメージを選択。実機の場合は USB デバッグを有効化し、デバイスを認識させます。

ステップ4　ビルド＆実行

  1. メイン画面右上の Run ボタン（緑の三角）または Shift + F10 を押してビルド開始。
  2. ビルドが成功すると、エミュレータ上に TODO アプリが起動し、Firebase Authentication の匿名ログインが自動で行われ、Firestore にサンプルデータが保存されます。
  3. コンソールログで Firebase initialized のメッセージが確認できれば成功です。

ハマった点やエラー解決

発生したエラー 原因 解決策
Could not find google-services.json android/app/ に配置忘れ、またはファイル名が違う 正しい場所にファイルを置き、名前を変更せずに google-services.json とする
androidx.annotation:annotation のバージョン不整合 Firebase 플러그인が要求する AndroidX ライブラリとプロジェクトの compileSdkVersion が合っていない android/app/build.gradle の compileSdkVersion と targetSdkVersion を 33 以上に上げ、gradle.properties に android.useAndroidX=true と android.enableJetifier=true を追加
FirebaseException: Could not initialize Firebase google-services.json の package_name が android/app/src/main/AndroidManifest.xml の <manifest package="..."> と不一致 Firebase コンソールで設定したパッケージ名と同一になるよう AndroidManifest を修正
UNSUPPORTED_OPERATION (Firestore) Firestore のセキュリティルールがデフォルトで allow read, write: if false; になっている Firebase コンソール > Firestore > ルールを allow read, write: if true; に一時的に変更し、テストが終わったら適切に制限する

解決策の実践例

例えば google-services.json が見つからないエラーが出た場合、以下の手順で即座に対処できます。

Bash

# 1. プロジェクトルートに移動
cd ~/flutterfire/examples/todo_app/android/app

# 2. 正しい場所にファイルがあるか確認
ls -l google-services.json
# もし無ければ、Firebase コンソールから再ダウンロード

# 3. Gradle のクリーンビルドを実行
cd ../../..
flutter clean
flutter pub get
flutter run

このように ファイルの配置ミス と キャッシュのクリア が主な対処法となります。

まとめ

本記事では、FlutterFire の公式サンプルを Android Studio で実行するまでの 環境構築、リポジトリ取得、ビルド手順、そして よくあるエラーとその解決策 を体系的に解説しました。

  • Flutter と Firebase の連携に必要な設定ファイル（google‑services.json） の正しい配置
  • AndroidX と Gradle のバージョン整合性 がビルド成功の鍵
  • エラー対応表 による迅速なトラブルシューティング

これらをマスターすれば、サンプルアプリだけでなく、実際のプロジェクトでも Firebase の各種サービスをスムーズに組み込める 自信が得られます。次回は、Authentication のカスタム UI 実装や、Firestore の高度なクエリ例について深掘りする予定です。

参考資料