「首次運行」判斷是新用戶引導、隱私政策彈窗、默認配置初始化、埋點上報的前置條件。Android 通過 SharedPreferences 持久化標識位實現,但面臨多進程、數據清理、版本升級、多設備同步等複雜場景。本文提供生產級實現方案,覆蓋基礎版、版本感知版、多進程安全版、雲端同步版。
public class FirstRunDetector {
private static final String PREFS_NAME = "app_first_run";
private static final String KEY_FIRST_RUN = "is_first_run";
private static final String KEY_VERSION_CODE = "last_version_code";
private final SharedPreferences prefs;
public FirstRunDetector(Context context) {
prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE);
}
/** 檢查並標記首次運行 (非線程安全) */
public boolean checkAndMarkFirstRun() {
boolean isFirst = prefs.getBoolean(KEY_FIRST_RUN, true);
if (isFirst) {
prefs.edit().putBoolean(KEY_FIRST_RUN, false).apply();
}
return isFirst;
}
/** 僅檢查不標記 */
public boolean isFirstRun() {
return prefs.getBoolean(KEY_FIRST_RUN, true);
}
/** 手動重置 (測試/調試用) */
public void reset() {
prefs.edit().clear().apply();
}
}
// 使用
FirstRunDetector detector = new FirstRunDetector(this);
if (detector.checkAndMarkFirstRun()) {
showOnboardingGuide();
trackEvent("first_launch");
}
public class VersionAwareFirstRunDetector {
private static final String PREFS_NAME = "app_first_run_v2";
private static final String KEY_VERSION_CODE = "last_known_version_code";
private static final String KEY_FIRST_RUN_PREFIX = "first_run_v";
private final SharedPreferences prefs;
private final int currentVersionCode;
public VersionAwareFirstRunDetector(Context context) {
prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE);
currentVersionCode = BuildConfig.VERSION_CODE;
}
/** 檢查指定版本的首次運行 */
public boolean isFirstRunForVersion(int versionCode) {
return prefs.getBoolean(KEY_FIRST_RUN_PREFIX + versionCode, true);
}
/** 標記指定版本已運行 */
public void markVersionRun(int versionCode) {
prefs.edit().putBoolean(KEY_FIRST_RUN_PREFIX + versionCode, false).apply();
}
/** 檢查當前版本首次運行 (升級後自動為 true) */
public boolean checkAndMarkCurrentVersionFirstRun() {
int lastVersion = prefs.getInt(KEY_VERSION_CODE, -1);
boolean isFirst = (lastVersion != currentVersionCode);
if (isFirst) {
prefs.edit()
.putInt(KEY_VERSION_CODE, currentVersionCode)
.putBoolean(KEY_FIRST_RUN_PREFIX + currentVersionCode, false)
.apply();
}
return isFirst;
}
/** 獲取所有版本首次運行狀態 (用於功能引導分組) */
public Map getAllVersionFirstRunStatus() {
Map map = new HashMap<>();
Map all = prefs.getAll();
for (Map.Entry entry : all.entrySet()) {
if (entry.getKey().startsWith(KEY_FIRST_RUN_PREFIX)) {
try {
int ver = Integer.parseInt(entry.getKey().substring(KEY_FIRST_RUN_PREFIX.length()));
map.put(ver, (Boolean) entry.getValue());
} catch (NumberFormatException ignored) {}
}
}
return map;
}
}
問題:SharedPreferences 非進程安全,多進程 (主進程 + :push/:webview/:service) 並發讀寫會導致數據丟失、ANR。
// 1. 定義 Provider
public class FirstRunProvider extends ContentProvider {
private static final String AUTHORITY = "com.example.app.firstrun";
private SharedPreferences prefs;
@Override public boolean onCreate() {
prefs = getContext().getSharedPreferences("app_first_run_mp", Context.MODE_PRIVATE);
return true;
}
@Override public Bundle call(String method, String arg, Bundle extras) {
if ("checkAndMark".equals(method)) {
boolean isFirst = prefs.getBoolean("is_first_run", true);
if (isFirst) {
prefs.edit().putBoolean("is_first_run", false).apply();
}
Bundle result = new Bundle();
result.putBoolean("result", isFirst);
return result;
}
return null;
}
// 其他 CRUD 方法...
@Nullable @Override public Cursor query(@NonNull Uri uri, @Nullable String[] p, @Nullable String s, @Nullable String[] s1, @Nullable String s2) { return null; }
@Nullable @Override public String getType(@NonNull Uri uri) { return null; }
@Nullable @Override public Uri insert(@NonNull Uri uri, @Nullable ContentValues cv) { return null; }
@Override public int delete(@NonNull Uri uri, @Nullable String s, @Nullable String[] s1) { return 0; }
@Override public int update(@NonNull Uri uri, @Nullable ContentValues cv, @Nullable String s, @Nullable String[] s1) { return 0; }
}
// 2. Manifest 註冊 (android:exported="false" 內部使用)
//
// 3. 客戶端調用 (任意進程)
public boolean checkFirstRunCrossProcess(Context context) {
Bundle result = context.getContentResolver().call(
Uri.parse("content://com.example.app.firstrun"),
"checkAndMark", null, null
);
return result != null && result.getBoolean("result", false);
}
public class FileLockFirstRun {
private final File lockFile;
private final File flagFile;
public FileLockFirstRun(Context context) {
File dir = context.getFilesDir();
lockFile = new File(dir, ".first_run_lock");
flagFile = new File(dir, ".first_run_flag");
}
public boolean checkAndMarkFirstRun() {
FileChannel channel = null;
FileLock lock = null;
try {
channel = new RandomAccessFile(lockFile, "rw").getChannel();
lock = channel.lock(); // 阻塞直到獲取獨佔鎖
boolean isFirst = !flagFile.exists();
if (isFirst) {
// 原子寫入
try (FileOutputStream fos = new FileOutputStream(flagFile)) {
fos.write("1".getBytes());
}
}
return isFirst;
} catch (IOException e) {
Log.e("FirstRun", "Lock failed", e);
return true; // 保守策略:視為首次
} finally {
if (lock != null) try { lock.release(); } catch (IOException ignored) {}
if (channel != null) try { channel.close(); } catch (IOException ignored) {}
}
}
}
public class CloudFirstRunSync {
private final FirebaseRemoteConfig remoteConfig;
private final FirstRunDetector localDetector;
public CloudFirstRunSync(Context context) {
remoteConfig = FirebaseRemoteConfig.getInstance();
localDetector = new FirstRunDetector(context);
}
public void syncFirstRunStatus() {
// 1. 獲取雲端配置:是否強制重置首次運行 (如重大改版)
boolean forceReset = remoteConfig.getBoolean("force_first_run_reset");
if (forceReset) {
localDetector.reset();
}
// 2. 上報本地首次運行狀態 (匿名用戶 ID)
boolean isFirst = localDetector.isFirstRun();
if (isFirst) {
FirebaseAnalytics.getInstance(context).logEvent("first_launch",
new Bundle().putString("device_id", getAnonymousId()));
}
}
}
| 場景 | 推薦方案 | 關鍵點 |
|---|---|---|
| 單進程、簡單需求 | 基礎版 SharedPreferences | apply() 異步寫入、MODE_PRIVATE |
| 版本升級需重新引導 | 版本感知版 | 記錄 versionCode、按版本隔離標識 |
| 多進程 (推送、WebView、Service) | ContentProvider 方案 | 跨進程 IPC、系統保證原子性、exported=false |
| 極簡依賴、無 Provider | 文件鎖方案 | RandomAccessFile + FileLock、阻塞式、性能較差 |
| 多設備同步體驗 | 雲端同步 + 本地緩存 | Remote Config 控制、Analytics 上報、匿名 ID 關聯 |
首次運行判斷看似微不足道,實則關係用戶首體驗、運營轉化、數據準確性。建議項目啟動時接入 版本感知 + 多進程安全 版本,預留雲端同步接口,為後續精細化運營奠基。