Android 首次啟動引導頁實現：SharedPreferences 正確用法與常見坑

需求

App 首次安裝啟動顯示引導頁，之後每次啟動直接進入主頁。

核心邏輯

1. 啟動頁讀取 `SharedPreferences` 標記位 `isFirst`。
2. `true` → 跳轉引導頁；`false` → 跳轉主頁。
3. 引導頁「完成」按鈕點擊時，將 `isFirst` 寫入 `false` 並提交。

常見錯誤與修正

❌ 錯誤 1：`final boolean isFirst` 導致無法更新

final boolean isFirst = prefs.getBoolean("isFirstIn", true);
// 後續在 GuideActivity 修改 prefs，但 isFirst 已是編譯期常量，不會重新讀取

修正：不要用 `final` 修飾讀取的布林值，或在 `onResume` / 決策瞬間**即時讀取**。

❌ 錯誤 2：`MODE_MULTI_PROCESS` 已棄用且不可靠

Android 多進程模式下 `SharedPreferences` 一致性無保障。單進程 App 直接用 `Context.MODE_PRIVATE`。

❌ 錯誤 3：引導頁寫入未 `apply()`/`commit()`

editor.putBoolean("isFirstIn", false);
editor.apply(); // 必須調用，否則不生效

標準實作代碼

1. 啟動頁

public class SplashActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // 無需 setContentView，直接決策跳轉
        SharedPreferences sp = getSharedPreferences("app_config", MODE_PRIVATE);
        boolean isFirst = sp.getBoolean("is_first_launch", true);

        Intent intent = new Intent(this, isFirst ? GuideActivity.class : MainActivity.class);
        startActivity(intent);
        finish();
    }
}

2. 引導頁「立即體驗」按鈕點擊

btnStart.setOnClickListener(v -> {
    SharedPreferences sp = getSharedPreferences("app_config", MODE_PRIVATE);
    sp.edit().putBoolean("is_first_launch", false).apply();
    startActivity(new Intent(this, MainActivity.class));
    finish();
});

進階：使用 DataStore (Jetpack 現代方案)

新專案建議用 Preferences DataStore，協程流式 API、主執行緒安全、自動處理異步寫入：

// 依賴: implementation "androidx.datastore:datastore-preferences:1.0.0"
val Context.dataStore: DataStore by preferencesDataStore(name = "app_config")

// 讀取
val isFirstFlow = dataStore.data.map { it[booleanPreferencesKey("is_first_launch")] ?: true }

// 寫入
scope.launch { dataStore.edit { it[booleanPreferencesKey("is_first_launch")] = false } }

總結檢查清單

• [ ] 啟動頁**即時讀取** SP，無 `final` 快取。
• [ ] 引導頁點擊**確實調用 `edit().putBoolean().apply()`**。
• [ ] 使用 `MODE_PRIVATE`，避免 `MODE_MULTI_PROCESS`。
• [ ] 新專案優先考慮 DataStore。