06-admob-setup.md

AdMob 設定指南

1. 帳號設定

• 在 Google AdMob 建立帳號。
• 註冊您的應用程式 (Android 與 iOS)。
• 為您的應用程式建立廣告單元：橫幅廣告 (Banner)、插頁式廣告 (Interstitial)、獎勵廣告 (Rewarded)、原生廣告 (Native) 及應用程式開啟廣告 (App Open)。

2. 控制台/儀表板設定

• 記下 Android 與 iOS 的應用程式 ID (App ID)。
• 記下每種廣告格式的廣告單元 ID。
• 在 AdMob 介面中新增測試裝置，以防止開發期間帳號遭停權。

3. SDK 安裝

pubspec.yaml 依賴項目

dependencies:
  google_mobile_ads: latest

平台設定

Android (AndroidManifest.xml)：

<meta-data
    android:name="com.google.android.gms.ads.APPLICATION_ID"
    android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>

iOS (Info.plist)：

<key>GADApplicationIdentifier</key>
<string>ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy</string>

4. 程式碼整合

import 'package:google_mobile_ads/google_mobile_ads.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await MobileAds.instance.initialize();
  
  // 為測試人員註冊測試裝置
  RequestConfiguration configuration = RequestConfiguration(
    testDeviceIds: ['YOUR_TEST_DEVICE_ID']
  );
  MobileAds.instance.updateRequestConfiguration(configuration);
  
  runApp(MyApp());
}

5. 基於角色的廣告顯示

此測驗題庫應用程式實作了根據使用者角色條件渲染廣告的機制：

• Guest / Pending：顯示正式版廣告。
• InternalTester / PublicTester：顯示測試廣告 (使用測試用廣告單元 ID)。
• Viewer / Admin：不顯示廣告。

6. 必要的環境變數

7. 常見問題排除

• 廣告未顯示：檢查您在開發期間是否使用測試廣告單元 ID。新應用程式的正式版廣告可能需要幾天的時間才會開始放送。
• 啟動時應用程式崩潰：確保 AndroidManifest 和 Info.plist 中有加入 APPLICATION_ID 中繼資料標籤。

07-crashlytics-shake-setup.md

Crashlytics & Shake 設定指南

1. Crashlytics 設定

• Firebase Console：確保您的 Firebase 專案已啟用 Crashlytics。
• 設定 FlutterError.onError 與 PlatformDispatcher.instance.onError，分別用來捕捉框架層與非同步的錯誤。

2. Shake SDK 設定

• 帳號設定：在 Shake 建立帳號。
• 建立應用程式：在 Shake 儀表板新增應用程式，以取得 Client ID 與 Client Secret。
• Shake 提供搖一搖回報錯誤功能，以及直接從應用程式介面收集使用者回饋。

3. SDK 安裝

pubspec.yaml 依賴項目

dependencies:
  firebase_crashlytics: latest
  shake_flutter: latest

4. 程式碼整合

為了防止啟動時發生 ANR (應用程式無回應)，請透過延遲回呼 (Callback) 來初始化 Shake。

import 'package:shake_flutter/shake_flutter.dart';
import 'package:firebase_crashlytics/firebase_crashlytics.dart';

void initErrorTracking() {
  // 捕捉 Flutter UI 錯誤
  FlutterError.onError = (errorDetails) {
    FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
  };
  
  // 捕捉非同步錯誤
  PlatformDispatcher.instance.onError = (error, stack) {
    FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
    return true;
  };

  // 延遲初始化 Shake
  WidgetsBinding.instance.addPostFrameCallback((_) {
    Shake.start(
      'YOUR_SHAKE_CLIENT_ID',
      'YOUR_SHAKE_CLIENT_SECRET'
    );
  });
}

5. 統一的 ErrorReportService

建立一個統一的服務來處理自訂的非致命錯誤日誌紀錄，並附加背景資訊 (例如：使用者 ID、測驗連線階段 ID)。若在回答關於 IP 位址或路由器的題目時發生畫面渲染錯誤，可透過此服務記錄狀態。

class ErrorReportService {
  Future<void> logError(String message, {String? userId}) async {
    await FirebaseCrashlytics.instance.log(message);
    if (userId != null) {
      await FirebaseCrashlytics.instance.setUserIdentifier(userId);
    }
    // 若適用，將資訊轉發至 Shake
  }
}

6. 必要的環境變數

7. 常見問題排除

• Shake 未出現：確認您在實體裝置上測試 Shake，因為模擬器可能無法準確觸發動作事件。
• 缺少堆疊追蹤 (Stack traces)：確保 dSYMs (iOS) 或 ProGuard 映射檔 (Android) 已正確上傳至 Firebase Crashlytics。

08-ai-api-setup.md

AI API 與裝置端 AI 設定指南

1. 雲端 AI API (Gemini / Claude / OpenAI)

• 從各 AI 供應商的儀表板取得您的 API 金鑰。
• 安全性：絕不要將您的 API 金鑰提交到 git。請將它們儲存在 secrets.json 檔案中。
• 在 AiTutorService 中設定 REST 端點。

ApiKeyService 整合

使用 FlutterSecureStorage 在裝置上管理金鑰。

class ApiKeyService {
  final _storage = const FlutterSecureStorage();
  
  Future<void> saveApiKey(String key) async {
    await _storage.write(key: 'ai_api_key', value: key);
  }
  
  Future<String?> getApiKey() async {
    return await _storage.read(key: 'ai_api_key');
  }
}

API 金鑰輪替

安全地輪替金鑰，避免服務中斷：

1. 在供應商儀表板產生新金鑰。
2. 更新您的 CI/CD 流程中的環境變數。
3. 將新金鑰部署至 Edge Functions 或伺服器。
4. 在 24 小時後撤銷舊金鑰。

2. 裝置端模型 (Gemma 4 LiteRT-LM)

此應用程式使用裝置端 AI 模型作為離線時的備用方案，確保使用者隨時都能存取練習題與認證考試的詳細解析，例如關於子網路劃分或是交換器設定的問題。

模型設定

• 模型檔案：gemma-4-E2B-it.litertlm (約 1.7GB)。
• 將模型檔案託管在 CDN 上，或在應用程式初始設定階段透過 HuggingFace 下載。
• 系統需求：LiteRT-LM 需要 Android 最低 SDK 版本為 30。

SDK 安裝

pubspec.yaml 依賴項目

dependencies:
  flutter_gemma: latest

程式碼設定

import 'package:flutter_gemma/flutter_gemma.dart';

Future<void> initOnDeviceAi() async {
  // 確保本機已有模型檔案
  final modelPath = await downloadModelIfNotExists();
  
  await FlutterGemmaPlugin.instance.init(
    modelPath: modelPath,
    useGpu: true, // 偏好使用 GPU 後端
  );
}

3. 必要的環境變數

4. 常見問題排除

• LiteRT-LM 崩潰：確保裝置支援 GPU 後端。如有必要，請切換至 CPU 模式。
• API 金鑰外洩：如果 API 金鑰不慎被推送到版本控制，請立即在供應商儀表板中將其撤銷並進行金鑰輪替。