ponshu-room-lite/docs/DISTRIBUTION_API_KEY_SETUP.md

# 配布用 Gemini API キー設定ガイド

このガイドは、知人配布用 APK に埋め込む **専用 Gemini API キー** を発行・設定する手順書です。

## なぜ専用キーが必要か

開発用キー（`lib/secrets.local.dart` に設定済み）をそのまま配布 APK に使うと:
- APK を逆コンパイルすれば誰でもキーを抽出できる
- あなたのクォータ（無料枠）を知らない第三者に使い尽くされる可能性がある
- キーを無効化すると開発環境も壊れる

**解決策**: 配布専用キーを発行し、Androidパッケージ名で制限する。

---

## 手順

### 1. Google Cloud Console で新しい API キーを発行

1. [Google AI Studio](https://aistudio.google.com/) にアクセス
2. 右上のメニューから「Get API key」→「Create API key in new project」
   - または既存プロジェクトに追加: 「Create API key」→ プロジェクト選択
3. 発行されたキーをメモ（`AIzaSy...` 形式）

### 2. API キーに制限を設定

[Google Cloud Console API 認証情報ページ](https://console.cloud.google.com/apis/credentials) にアクセス:

1. 作成したキーをクリック → 「キーを編集」
2. **API の制限**:
   - 「キーを制限する」を選択
   - 「Generative Language API」のみ選択
3. **アプリケーションの制限**:
   - 「Android アプリ」を選択
   - 「アイテムを追加」をクリック
   - パッケージ名: `com.posimai.ponshu_room_lite`
   - SHA-1 証明書フィンガープリント: （後述）
4. 保存

### 3. リリース署名の SHA-1 フィンガープリントを取得

配布 APK はリリースキーストアで署名する必要があります。

**キーストアが未作成の場合（Windowsコマンドプロンプト）:**

```cmd
keytool -genkeypair -v -keystore android\app\ponshu_release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias ponshu_key
```

パスワードを設定し、組織情報を入力。

> ⚠️ **パスワードは安全な場所に記録してください。紛失するとアプリの更新ができなくなります。**

**SHA-1 の取得（Windowsコマンドプロンプト）:**

```cmd
keytool -list -v -keystore android\app\ponshu_release.jks -alias ponshu_key
```

出力の `SHA1:` 行をコピーして Google Cloud Console に貼り付ける。

### 4. key.properties にパスワードを設定

`android/key.properties` を新規作成（このファイルは .gitignore に含まれています）:

```properties
storePassword=あなたが設定したパスワード
keyPassword=あなたが設定したパスワード
keyAlias=ponshu_key
storeFile=ponshu_release.jks
```

### 5. build.gradle.kts にリリース署名を設定

`android/app/build.gradle.kts` を以下のように変更:

```kotlin
import java.util.Properties

// key.properties からリリース署名情報を読み込み
val keyPropertiesFile = rootProject.file("key.properties")
val keyProperties = Properties()
if (keyPropertiesFile.exists()) {
    keyProperties.load(keyPropertiesFile.inputStream())
}

android {
    // ... 既存設定 ...

    signingConfigs {
        if (keyPropertiesFile.exists()) {
            create("release") {
                keyAlias = keyProperties["keyAlias"] as String
                keyPassword = keyProperties["keyPassword"] as String
                storeFile = file(keyProperties["storeFile"] as String)
                storePassword = keyProperties["storePassword"] as String
            }
        }
    }

    buildTypes {
        getByName("release") {
            signingConfig = if (keyPropertiesFile.exists()) {
                signingConfigs.getByName("release")
            } else {
                signingConfigs.getByName("debug")
            }
            isMinifyEnabled = false
            isShrinkResources = false
        }
    }
}
```

> key.properties が存在しない場合は自動的に debug 署名にフォールバックします。

### 6. 配布 APK のビルド

```cmd
flutter build apk --release ^
  --dart-define=GEMINI_API_KEY=AIzaSy...(配布用キー) ^
  --obfuscate ^
  --split-debug-info=build\debug-info
```

- `--obfuscate`: クラスや関数名を難読化し、逆コンパイル時に解析されにくくする
- `--split-debug-info`: デバッグシンボルを APK 本体から分離して保存（APK サイズ削減）
  - `build\debug-info` フォルダは git 管理外でよい（ローカルに保持しておく）

出力ファイル: `build\app\outputs\flutter-apk\app-release.apk`

> 難読化なしの簡易ビルド（動作確認用）:
> ```cmd
> flutter build apk --release --dart-define=GEMINI_API_KEY=AIzaSy...(配布用キー)
> ```

### 7. Pro版のビルド（オプション）

Pro版機能を有効化したAPKをビルドする場合（パッケージ名は `com.posimai.ponshu_room_lite` のまま変わりません）:

```cmd
flutter build apk --release ^
  --dart-define=GEMINI_API_KEY=AIzaSy...(配布用キー) ^
  --dart-define=IS_PRO_VERSION=true ^
  --obfuscate ^
  --split-debug-info=build\debug-info
```

---

## 配布方法

### Google Drive 経由（推奨）
1. `app-release.apk` を Google Drive にアップロード
2. 共有リンクを知人に送付
3. 受信者は Android の「設定 > セキュリティ > 提供元不明のアプリ」を有効化してインストール

### LINE で直接送信
1. APKファイルをLINEのトーク画面にドラッグ＆ドロップ
2. 受信者がファイルをタップしてインストール

### adb 直接転送（テスト時）
```cmd
adb install build\app\outputs\flutter-apk\app-release.apk
```

---

## API クォータ管理

| 設定 | 推奨値 | 説明 |
|------|--------|------|
| 1日あたりのリクエスト上限 | 100〜200 | Google Cloud Console → API → クォータで設定 |
| 無料枠 | 1,500回/日 | Gemini 2.5 Flash 無料枠 |

Google Cloud Console で **アラート** を設定しておくことを推奨:
- 「APIs & Services」→「Gemini API」→「クォータ」→「アラートの設定」

---

## チェックリスト

- [ ] 配布用 API キーを Google AI Studio で発行
- [ ] API 制限: Generative Language API のみ
- [ ] アプリ制限: `com.posimai.ponshu_room_lite` の SHA-1
- [ ] リリースキーストア（`ponshu_release.jks`）を作成
- [ ] `android/key.properties` にパスワードを設定
- [ ] キーストアと key.properties が `.gitignore` に含まれていることを確認
- [ ] `flutter build apk --release --dart-define=GEMINI_API_KEY=<配布用キー> --obfuscate --split-debug-info=build\debug-info` で APK ビルド
- [ ] テスト端末でインストール・動作確認

---

**Last Updated**: 2026-02-16