跪拜 Guibai
← Back to the summary

One App, Five ROMs, Five Ways to Die: 8 Real Android Compatibility Traps from a Chinese Health Team

Origin: A Null Pointer That Couldn't Be Traced

Last November, operations forwarded a complaint: "The Healthy Nanjing app crashes on some Android phones as soon as it opens."

First instinct was a version issue. We checked crash logs; Bugly showed:

java.lang.NullPointerException: Attempt to invoke virtual method 'java.lang.String com.xxx.util.DeviceInfo.getChannel()' on a null object reference

Device distribution: Huawei Mate 60, Xiaomi 14, OPPO Find X7, vivo X100, Honor Magic6 — all five vendors hit.

My first reaction was "we wrote bad code." So we dutifully inspected the code, spent three hours, and found nothing.

Then a senior colleague said: "Are these five models all the newest? Have they all just received system updates?"

I paused, checked the device info version numbers in the crash logs. All were the latest ROMs each vendor had pushed.

This is the first thing I want to tell you: on domestic Android, the first suspect for "intermittent issues on a certain model" isn't the model — it's a system update just pushed to that model. Five vendors each updated, and all five crashed on the same null pointer. These can't be five independent bugs. It's a common problem that five systems simultaneously amplified.

The root cause later turned out: all five new ROMs changed the Provider loading order during Application initialization. A third-party SDK read channel info in ContentProvider.onCreate, but channel info was written by another initializer only after Application.onCreate. On old ROMs the order happened to be correct; on the new ROMs it was flipped.

This pitfall taught me: domestic Android compatibility is essentially not "adapt to five vendors" — it's "adapt to five sets of lifecycle philosophies."


First, the Underlying Model — Otherwise Everything After Is Mysticism

Before any concrete adaptation, you need a cognitive framework. What kills your app isn't one thing; it's three layers stacked. Many teams only handle the first layer and then get repeatedly slapped by layers two and three.

Layer 1: Android system power-saving mechanisms (Doze / App Standby)
         All vendors have it; behavior is predictable; can be bypassed with WorkManager / AlarmManager
                ↓
Layer 2: Vendor battery and process management (each vendor has different strategies, and they change with versions)
         This is the real battlefield: kills without warning, no callbacks, no logs
                ↓
Layer 3: Vendor app distribution and compliance systems (background location, associated starts, secondary permission toggles)
         This layer isn't system behavior; it's "permission." If the user doesn't give it, you simply can't use it.

On top of that, one factor runs through all three layers: no GMS in China. Everything you see online as "overseas best practices" — if it depends on FCM, Play Services, or Firebase — must be replaced on domestic devices. This isn't optional.

One more thing must be clear: Huawei/Honor is already an independent target platform. On HarmonyOS NEXT / HarmonyOS 5, apps are native HarmonyOS packages (ArkTS + ArkUI), not APKs. Huawei's docs (updated 2026-05-27) state explicitly: NEXT apps are globally only available for smartwatches; other device classes are limited to mainland China. Old models (EMUI and earlier) still have an Android compatibility layer; new models do not.

So "supporting Huawei" in 2026 must be split into two completely different projects.

With this framework, let's go through each pitfall.


Pitfall 1: Background Process Killed — Five Vendors, Five Ways to Die

Symptoms

User feedback is usually vague: "After the app is in background for a while, data disappears when I reopen it," "messages don't arrive," "sync stops."

We once counted online feedback by brand. The conclusion was harsh:

Vendor Death Method Typical Survival Time Callback?
Huawei / Honor "App Launch Management" has auto-start / associated-start disabled by default 1–2 minutes after screen off No
Xiaomi / Redmi Auto-start + associated-start + battery strategy "Smart" (pick one) 30 seconds – 3 minutes after screen off No
OPPO / OnePlus "Smart Freeze" directly kills background services, even foreground services 1–3 minutes after screen off No
vivo / iQOO Background high-power management + startForegroundService interception Variable, random No
Native Android Doze / App Standby bucket degradation Hours Yes

Why Vendors Do This

This is the most under-discussed but most important part of any compatibility article.

Vendors' motivation isn't "targeting your app"; it's whole-device battery life and benchmark scores. Phone makers sell hardware. If a user compares the same OPPO against another brand and battery life is off by 5%, sales suffer. To achieve that goal, the system layer must do two things:

  1. Freeze as many background processes as possible to save memory, CPU, and power.
  2. Make "user-granted permission" the only path to background survival — because if the user taps "Allow," the user won't complain to the vendor when something breaks, and the vendor has no reason to be aggressive anymore.

So you see a counter-intuitive phenomenon: the more aggressive a vendor's strategy, the vaguer the official documentation. It's essentially "preventing you (the developer) from stealing battery," not a feature that's promised externally. If you look through Xiaomi's developer docs, you won't find "Auto-start management will kill your app."

Understanding this layer turns many "bugs" into "expected behavior." You can't convince the system; you can only request permission or work around it.

Our Handling Process

First step was building a ROM detection layer. We wrote RomDetector, not relying on Build.MANUFACTURER (on Honor, does that return "HONOR" or "HUAWEI"? On Xiaomi's international version, what does it return?), but on system properties:

object RomDetector {
    fun getRomType(): RomType {
        // Xiaomi
        getSystemProperty("ro.miui.ui.version.name")?.let {
            return RomType.XIAOMI
        }
        // Huawei
        getSystemProperty("ro.huawei.build.display.id")?.let {
            return RomType.HUAWEI
        }
        // OPPO
        getSystemProperty("ro.build.version.opporom")?.let {
            return RomType.OPPO
        }
        // vivo
        getSystemProperty("ro.vivo.os.version")?.let {
            return RomType.VIVO
        }
        // Honor (judged separately, must not merge into Huawei)
        getSystemProperty("ro.build.version.honor")?.let {
            return RomType.HONOR
        }
        return RomType.OTHER
    }
}

Note "detect system properties, not package name" — we switched after hitting a pitfall. Early on we used Build.MANUFACTURER == "Xiaomi", and on some customized versions of Xiaomi HyperOS it returned null, causing all judgments to fail. Properties like ro.miui.ui.version.name are much more stable.

Second step was a separate guidance flow for each vendor. Here's a hard constraint: don't expect one set of logic to work for all.

Third step: don't treat keep-alive as the only solution. Our final approach was: give up the obsession with "process alive forever," change to "process dies but recovers."

Specifically:

  1. Persist all state locally — process death doesn't lose data (this is already mandatory, but many teams trip here).
  2. Design all critical operations to be idempotent — re-execution doesn't produce dirty data.
  3. Use WorkManager + AlarmManager as fallback, not self-written while(true) loops + startService for keep-alive.

On the third point, we want to emphasize a counter-intuitive experience: many "keep-alive solutions" online (Cactus, dual-process daemon, JobScheduler infinite loops) are essentially fighting the system. The cost is power consumption, battery drain, ANR rate, and review risk. We measured: running a dual-process daemon on a Xiaomi phone added 11%–14% extra battery drain in 24 hours, and it can fail at any time after a system update.

The only reliable keep-alive is: hand the work to system-approved executors (vendor push channels, WorkManager, AlarmManager), and then do user guidance properly.

Experience Share

Our understanding of background keep-alive went through three stages:

Stage one: thought there was a universal solution → searched a bunch of open-source libraries → each failed on every vendor. Stage two: thought user guidance would solve it → found guidance page conversion is only 3%–7%, and the system can reset settings at any time. Stage three: accepted that "being killed" is the norm, and changed architecture to "survive being killed."

Now when we launch a feature needing background capability (like health data scheduled sync, medication reminders), the flow is fixed in three steps:

  1. Can we use push to wake it? → If yes, don't keep alive; use vendor channel push.
  2. Can't push, but can we use system scheduler? → Use WorkManager + setRequiredDelay, with AlarmManager.setExactAndAllowWhileIdle as fallback.
  3. Neither works (must be resident, e.g., Bluetooth collection)? → Only then use a foreground service + guide user to add whitelist.

The order cannot be reversed. We've seen too many teams jump straight to dual-process daemon when the business didn't need it.

Another easily missed thing: after guiding the user to whitelist, you must verify it actually took effect. User selecting "Unrestricted" under Xiaomi's "Battery" doesn't mean the switch under "Auto-start Management" is on. These are two independent switches. Huawei's "App Launch Management" has three independent switches.

Our self-check script logic: after adding to whitelist, let the app sit with screen off for 30 minutes, then actively check the local data's last-updated timestamp — if it hasn't updated, the whitelist didn't take effect, not "the service is broken."

This self-check script has saved us from at least 3 online incidents.


Pitfall 2: Push Channel — The Most Expensive Pitfall

Symptoms

User: "Appointment reminders aren't arriving." Developer: "I get them in local testing." Operations: "Xiaomi users especially are complaining."

This is the classic testing environment giving you false assurance. On your own phone, the app is in the foreground, the long connection is alive, push arrives instantly. When the user locks the screen for 5 minutes, the process dies, the long connection drops, and the message never arrives.

Why

The push chain is:

Your server → Push platform → Device

If using third-party push (JPush, Getui, Umeng, Tencent XinGee), the middle layer relies on a TCP long connection maintained by your own app process. Process dies, connection drops, server can't find device, message discarded.

If using vendor channels (Huawei HMS Push / Xiaomi MiPush / OPPO Push / vivo Push / Honor Push / Meizu Push), messages are delivered on behalf of the system process, regardless of whether your app process is alive.

That's the entire difference. One sentence: vendor channel means the system delivers for you; third-party channel means you deliver yourself.

The industry's rule of thumb: without vendor channels, delivery rate on domestic ROMs is 30%–60%; with all connected, 90%+. (This is a long-term engineering statistic, not an official promise; exact numbers vary by SDK and business shape, but the magnitude is reliable.)

Another key fact: FCM is unusable in China. Even if your client integrates Firebase Messaging, servers inside China can't connect to FCM. So "use FCM to cover the whole world" works overseas but dies domestically.

Our Handling Process

When first connecting vendor channels, we hit three very typical pitfalls:

Pitfall A: Package name / signature mismatch, token never registers.

Each vendor SDK requires you to create an app in their developer console; the package name and signing certificate fingerprint must be exactly identical to the final APK. We used debug signature for test builds and release signature for release builds, so Huawei's HMS token was never obtained on release builds, with only a "token acquisition failed" and an error code, no specific reason — very hard to trace.

We turned this into a build-time check: a Gradle script automatically reads the current variant's signing fingerprint, compares against each vendor console configuration, and fails the build if mismatched. This check has saved us more than once.

Pitfall B: The "master switch" for third-party aggregate push wasn't turned on.

We used JPush as a unified channel; JPush supports forwarding to vendor channels. But JPush's console must manually configure each vendor's AppKey / Secret. If you miss one, that vendor's devices are dead. The symptom is extremely subtle: JPush console shows "sent successfully," because from JPush's perspective it did succeed — but it only forwarded to the vendor channel, which rejected because the AppKey was wrong.

A trick for diagnosing this: look at the vendor SDK's callback logs, not the push platform's status. JPush's "success" doesn't mean delivery.

Pitfall C: Notification permission and Channel silent failures.

Android 8.0+ notifications must be bound to a Channel; notifications without a Channel simply don't show. Android 13+ requires runtime POST_NOTIFICATIONS; if the user denies, notifications are silently dropped, with no callback. On Xiaomi we saw one app working on a test device (Android 12) but never receiving on a user device (Android 14) — simply because the permission wasn't requested.

There's an even sneakier one: some vendor ROMs have "notification smart management / do-not-disturb" that auto-collapse notifications or delay delivery after screen lock. A user checking settings would understand instantly, but the guidance copy needs to say it.

Our Final Push Architecture

┌─────────────────────────────────────────────┐
│  Message tiering (not all messages go through push)  │
│   L1 high timeliness (appointment reminders, emergency) → must use vendor channel │
│   L2 normal timeliness (health report generated) → vendor channel + pull │
│   L3 non-timeliness (promotions, marketing) → avoid disturbing user │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│  Channel routing (distributed by token type)           │
│   Huawei token  → HMS Push API                  │
│   Xiaomi token  → MiPush API                    │
│   ...                                        │
│   Other token  → third-party long connection          │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│  Degradation chain                                     │
│   Vendor channel fail → third-party channel → pull on app start      │
│                → Extreme case: SMS (L1 only)          │
└─────────────────────────────────────────────┘

That last "SMS fallback" is reserved for L1 messages. For a health/medical app, missing an appointment or medication reminder can be a real health event. Paying for one SMS for that message is worth it, but only for L1 — if everything SMS-falls back, users will uninstall.

Experience Share

The maintenance cost of vendor channels is severely underestimated.

Integration is one day; maintenance is three years. Every year each vendor upgrades SDKs, requires new configs, changes token acquisition. Also, documentation quality among the five vendors is uneven — Xiaomi and OPPO docs often just say "see official docs."

Our current practice: write a unified PushChannel abstraction layer; business only knows PushChannel.send(msg), all vendor SDK differences are hidden inside adapters. The adapter interface is unified into three methods: register(), getToken(), send(). Upgrading one vendor's SDK then only touches one file.

Another easy-to-miss point: tokens expire; they need regular refresh and re-reporting. We saw a user who changed phones while the server kept sending to a dead token, wasting quota. Device reset, user logout, system upgrade can all change a token.


Pitfall 3: Overlay / Background Pop-up Permission — Triple-Gate Check

This pitfall ranks second in subtlety but first in debugging difficulty.

Symptoms

W/WindowManager: Permission denied for window type 2002

Or users say: "The floating window disappears right after opening," "Tapping a notification to enter the app won't show the login dialog."

Why It's So Hard

Because Settings.canDrawOverlays(context) returning true doesn't mean you can actually show. Vendors add two more gates on top:

Layer Check Content How to Pass
System-level canDrawOverlays() Jump to ACTION_MANAGE_OVERLAY_PERMISSION
Vendor-level ROM-private secondary switch Jump to vendor-private settings page + guide user manually
Runtime Whether addView gets intercepted No solution, only try

The second layer is the most troublesome. Xiaomi requires three switches simultaneously: show floating window, auto-start, battery optimization whitelist — all must be on. vivo's startForegroundService interception and OPPO's "Smart Freeze" killing Service all happen at this layer.

The third layer is the worst: MIUI has a special logic — even if you have overlay permission, if the user has swiped the app away from recent tasks, MiuiWindowManagerService still intercepts your WindowManager.addView. The log only shows that Permission denied for window type 2002 line, with no other clue.

Many teams draw a wrong conclusion here: "Xiaomi has a bug." It's not a bug; Xiaomi is expressing a product decision: you shouldn't keep populating windows after the user has "closed" you.

Our Handling Process

We gave up the "one-time detection + one-time jump" approach and switched to three-stage detection:

// Stage 1: system-level
val systemGranted = Settings.canDrawOverlays(context)

// Stage 2: vendor-level (reflect to read vendor private Provider)
fun isMiuiOverlayGranted(): Boolean {
    return try {
        val uri = Uri.parse("content://miui/permission/overlay")
        context.contentResolver.query(uri, null, null, null, null)
            ?.use { it.moveToFirst(); it.getInt(0) == 1 }
    } catch (e: Exception) { false }
}

// Stage 3: runtime (actually try a minimal window)
fun canRealAddOverlay(): Boolean {
    return try {
        val view = View(context).apply { setBackgroundColor(Color.TRANSPARENT) }
        val params = WindowManager.LayoutParams(
            1, 1, WindowManager.LayoutParams.TYPE_APPLICATION_OVERLAY, FLAG_NOT_FOCUSABLE, FLAG_LAYOUT_NO_LIMITS
        )
        wm.addView(view, params)
        wm.removeView(view)
        true
    } catch (e: Exception) { false }  // BadTokenException / SecurityException
}

Stage three is key. Stages one and two are "I guess you're allowed"; stage three is "I verified it actually works." If stage three fails, there's a gate we haven't detected, and we must show the user a guidance Dialog with screenshots, not pretend "authorized."

The guidance Dialog should include: current status explanation → specific path → screenshot → "got it". We found screenshot-bearing guidance completes at 2x+ the rate of text-only; users don't get lost in settings pages.

A Detail You Must Remember

Don't create overlay windows in background Activity. Huawei EMUI 11+ requires the Overlay window to be tied to a foreground Activity token; creating from a background Service gets killed directly, and with no logs. Once we spent a whole day on this; we finally added logs in ActivityLifecycleCallbacks and discovered the window was discarded the instant the Service created it.

The correct approach: use applicationContext for the WindowManager's Context, but create at the moment the Activity is visible, and call setVisibility(GONE) instead of removeView in onActivityPaused.

Experience Share

This pitfall taught us: permission guidance isn't a UI problem; it's a state-machine problem.

We now model every permission that needs guidance as an explicit state:

Not requested → Requested but not granted → System granted but vendor not granted → Fully usable

Each state maps to different UI: if not requested, show no guidance (let the user request when they actually need the feature); only after requested and vendor hasn't granted, show the screenshot guidance.

Many apps' problem is showing a bunch of permission guidance upfront and scaring users away. Once a user rejects, you've permanently lost that user.


Pitfall 4: WebView Compatibility — Kernel Version and System Version Are Not the Same

Symptoms

Why

This is the most counter-intuitive pitfall because many people assume "WebView version = system version."

Actually: Android System WebView is an independent APK (com.android.webview or com.google.android.webview), updated separately through the app store, completely decoupled from system upgrades. So:

So you see "the same Android version can have WebView kernels several major versions apart across vendors," and "the same device can behave differently a month later."

Our Handling Process

First step: don't guess; do runtime capability detection.

At startup, run a probe script and store the result locally:

(function () {
  var ua = navigator.userAgent;
  var m = ua.match(/Chrome\/(\d+)/);
  return JSON.stringify({
    chromiumVersion: m ? parseInt(m[1], 10) : 0,
    hasPromise: typeof Promise !== 'undefined',
    hasCSSGrid: typeof CSS !== 'undefined' && CSS.supports &&
                CSS.supports('display', 'grid'),
    hasFlex: typeof CSS !== 'undefined' && CSS.supports &&
              CSS.supports('display', 'flex'),
    hasWeakRef: typeof WeakRef !== 'undefined',
    hasIntersectionObserver: typeof IntersectionObserver !== 'undefined'
  });
})()

Use feature detection, not UA sniffing. UA strings can be spoofed, changed, and are unreliable. We initially used UA to detect Huawei, and when Huawei changed its UA format once, we missed it.

Second step: write the degradation path into code.

// Write without polyfills: use callbacks, don't touch Promise
function fetchData(url, onSuccess, onError) {
  var xhr = new XMLHttpRequest();
  xhr.open('GET', url, true);
  xhr.onreadystatechange = function () {
    if (xhr.readyState !== 4) return;
    if (xhr.status >= 200 && xhr.status < 300) {
      onSuccess(JSON.parse(xhr.responseText));
    } else {
      onError(new Error('HTTP ' + xhr.status));
    }
  };
  xhr.send();
}

Our team rule: H5-side code must run on Chromium 74 (the low-end WebView percentile from our online data). This constraint forces business code to avoid new syntax, which is far more reliable than adding polyfills afterward — polyfills have size, and they often break at strange edges.

Third step: the Cookie-loss pitfall deserves its own discussion.

Login state loss is the most common complaint and the hardest to trace because it's "sometimes good, sometimes bad."

The causes we identified are multi-layered:

Our solution: don't store login state in cookies. Maintain your own token, store it in localStorage or pass it through a JavascriptInterface to native. That refactor took us a week, and after that login state issues never recurred.

Fourth step: Android 14+ kills the WebView process.

Android 14 strengthened WebView render process management. Users reported "large-scale white screens and crashes after Android 14 upgrade." In /data/data/package/app_webview/ logs, you can see the render process killed.

Two measures for us:

  1. All resources over HTTPS to reduce chances of plaintext traffic interruptions.
  2. Give WebView its own process (android:process=":webview") to avoid the main process being killed along with it. This isn't a silver bullet but significantly reduces the ratio of "whole-page white screen" turning into "whole-app crash."

Experience Share

The lesson from WebView: you can never cover it with testing.

Because the user's WebView version is a variable you don't control. Our countermeasures:

The last one is a lifeline for UX. White screen is despair; a reload button is hope.


Pitfall 5: Privacy Compliance — The Top Reason for Review Rejection

This pitfall isn't technical, but it blocks your release, and rejection reasons often leave you puzzled.

Symptoms

Huawei review rejects with very specific reasoning:

"Before the user agrees to the privacy policy, your application requests XXX"

Or:

"The app requests camera permission immediately after launch"

Why (There's a Counter-Intuitive Mechanism)

According to Huawei's official June 2026 analysis of the top 8 privacy compliance rejection issues, the number one reason is always: obtaining personal information or permissions before the user agrees to the privacy policy.

The reasoning is obvious, but you might not realize how subtle it is:

The reviewer's automated log scanning looks at the entire application process lifecycle. From the moment the process starts to the moment the user taps "Agree," any reading of device identifiers, sensors, media, or files is deemed a violation — whether it's your own business code or implicit triggers inside a third-party SDK.

The key phrase is "implicit triggers inside a third-party SDK."

A real case we hit: a HarmonyOS project where the business code was completely correct, the privacy dialog was written, and we confirmed users couldn't enter the home page without agreeing. Still rejected. We used commented-code binary search to find the culprit — the EntryAbility's onCreate initialized some system Kit, and the framework preloaded capabilities and read device info during initialization, before the privacy dialog.

We hadn't changed a single line of our own code; it was the framework.

An even more common one: analytics SDKs. Many apps initialize Umeng/JPush/Sensors in Application.onCreate, and the SDK uploads device info during initialization. The developer wrote no collection code, but network requests were already sent.

This explains why some developers get rejected repeatedly and can't find the problem themselves. Because the problem really isn't in the code you wrote.

Our Handling Process

First step: make "before agreement" a hard boundary.

We set an iron rule:

Before the user taps "Agree," the app is "dead." No network requests, no device-info reads, no third-party SDK initialization.

We enforce this by moving all SDK initialization out of Application.onCreate into an explicit PrivacyGate.init(context), called only after user consent.

class HealthApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        // Only the most basic initialization that doesn't involve personal information
        AppContext.init(this)
        // Note: no third-party SDK initialization here
    }
}

// Called after privacy consent
object PrivacyGate {
    fun init(context: Context) {
        AnalyticsTracker.init(context)      // analytics
        PushManager.init(context)            // push
        CrashReporter.init(context)         // crashes
        // ...
    }
}

Second step: track down indirect dependencies.

This is the easiest to miss. You explicitly declare 5 SDKs in build.gradle, but transitive dependencies might bring in 8 more. You need to:

  1. Go through all build configs and dependency files
  2. Run ./gradlew :app:dependencies to get the full dependency tree
  3. Check each SDK's privacy documentation to confirm what it collects
  4. Cross-check against the privacy policy item by item

We turned this into a CI script that runs automatically at each release, outputting "SDKs introduced in this version and their data collection declarations," and diffs against the previous version. A new SDK without a matching privacy declaration fails the CI.

This step often brings surprises. We once found an image-loading library (imported as AAR) had a built-in analytics module that the app never noticed.

Third step: note that SDK upgrades can change collection behavior.

Different versions of the same SDK may collect different data. After upgrading an SDK, re-check the privacy statement. We tied "SDK upgrade" and "privacy policy review" into a single checklist item; no update means no merge.

Experience Share

Privacy compliance is essentially "the burden of proof is on you."

The reviewer uses automated scanning + manual spot checks. You need to do not "prove I'm clean," but "make the scanner find nothing."

Huawei provides three self-check tools; we recommend using all:

But know these tools' limits: what they scan out are hard violations; the things that actually trigger rejection are often things tools can't see.

Another easy-to-miss point: don't repeatedly pop up dialogs immediately after a user denies permission. The correct approach is a degraded prompt: "Camera permission is needed to take photos. You can enable it in settings." Let the user decide. Repeated pop-ups are bad UX and the reviewer may treat it as harassment.


Pitfall 6: Five App Stores, Five Review Standards

This pitfall doesn't cause crashes, but it directly slows your release cadence, and fixing it is draining.

Symptoms

The same APK:

Differences by Vendor (2026)

Huawei AppGallery

Xiaomi App Store

OPPO / vivo App Store

Tencent App Store (Yingyongbao)

Common Thresholds (These Get You Every Time)

Our Handling Process

We turned all qualifications into a five-channel difference comparison table placed at the top of the project wiki. We review against it before each submission.

This table looks like (simplified):

Check Item Huawei Xiaomi OPPO/vivo Tencent App Store
Software copyright name+entity+version all match consistent with filing/listing name must have must have
APP filing number required required required required
ICP filing number required required required required
ICP commercial license needed if paid/ads same same same
EDI multi-merchant required multi-merchant required multi-merchant required multi-merchant required
Security assessment report social/news categories — — always required
Privacy policy page reachable reachable manual spot-check reachability reachable
Pure Mode validation validates unregistered blocks — — —

The value of this table isn't getting it right once; it's turning "rejection" from "accident" into "predictable."

We also templated the submission materials — each version update, the privacy policy page version, SDK list, and permission list are auto-generated; humans only check the diff. Hand-maintaining these materials is the classic "one line skipped when busy," then rejection.

Experience Share

On app stores, the most counter-intuitive advice: don't aim for one-time pass; aim for "rejection reasons are predictable."

We counted our 2025 rejection records:

67% of rejections are "low-level errors," not "strict review." I calculated that if we templated materials and used checklists, that 67% drops to zero.


Pitfall 7: Intent Broadcast Interception and Vendor SDK Internal Behavior

This pitfall's characteristic: you don't know it exists until one day all vendors break at once.

Symptoms

We have a "health data sync" feature that uses BOOT_COMPLETED broadcast to pull data after boot. It worked fine on native Android and early ROMs. One day users reported: this feature failed simultaneously on all five vendors.

Why

Two causes, both subtle.

First: vendors are tightening implicit broadcasts.

After Android 8.0, most implicit broadcasts are restricted. Vendors added a self-start whitelist on top — even if you declare a <receiver>, the system won't allow your app to be pulled up at boot.

Xiaomi has explicit policy: some key Intent broadcasts are intercepted, your receiver never gets them.

Second: vendor SDK initialization order.

That earlier null pointer crash had its root cause in ContentProvider.onCreate running before Application.onCreate. This is explicitly documented in Android's official docs — ContentProvider initializes before Application. But many third-party SDKs don't know (or know but don't handle it), and they read channel info and device IDs in ContentProvider.onCreate.

Five new ROMs each adjusted Provider loading strategy or added their own Provider, exposing this ordering problem.

Our Handling Process

For the broadcast interception:

We gave up relying on BOOT_COMPLETED and switched to triple trigger:

  1. BOOT_COMPLETED (may fail, kept as one fallback)
  2. On app start, check local data's last sync time; if beyond threshold, do a catch-up sync (most reliable)
  3. Vendor push channel sends a custom "time to sync" message (most timely, unaffected by process aliveness)

Item 2 is key. Don't rely on "the system will call me"; rely on "when I start, I check if I owe work."

We patternized this into a generic SyncScheduler:

object SyncScheduler {
    fun onAppStart() {
        val last = PreferenceStore.lastSyncTime
        if (System.currentTimeMillis() - last > SYNC_INTERVAL) {
            SyncWorker.enqueue(context)  // via WorkManager, idempotent
        }
    }
}

For SDK initialization order:

We did one thing: centralized all third-party SDK initialization into a single file with comments explaining dependency order.

/**
 * SDK initialization order (read before changing)
 *
 * 1. ChannelInitializer  —— must be first; its written channel info is read by other SDKs
 * 2. PrivacyGate         —— any collection SDK can only initialize after user agrees to privacy policy
 * 3. Other business SDKs —— depend on 1 and 2
 *
 * Never initialize SDKs directly in Application.onCreate.
 * 2026-03: Xiaomi/Huawei/OPPO/vivo new ROMs changed Provider loading order,
 * causing ChannelInitializer to be placed later, resulting in null pointer crash.
 */

This file's value isn't the code; it's the "archaeological record." When someone asks six months later "why is this ordered here," the comment has the answer. Otherwise you'd have to comment out code in binary search to reproduce that crash.

Experience Share

Keep a record for every "inexplicable behavior."

Our project now has a KNOWN_ISSUES.md, each entry records three things: symptom, root cause, verification method. Examples:

## Xiaomi MIUI 14+: auto-start management jump must use startActivityForResult
- Symptom: using ActivityResultLauncher to jump doesn't return authorization result
- Root cause: MIUI's permission page doesn't return through standard Result callback after jump
- Verification: adb shell am start -n com.miui.securitycenter/...

## Huawei EMUI 11+: creating Overlay from background Service gets killed without logs
- Symptom: floating window disappears within 5 seconds of app going background, no logcat output
- Root cause: Overlay requires a foreground Activity token
- Verification: print Activity visibility status before and after addView

This file has saved us many times. Every online incident, first step is to check whether this doc has a similar record. If it does, 10 minutes to locate; if not, start from scratch.


Pitfall 8: Foldables, High Refresh Rate, and Android 16 Behavior Changes

This pitfall comes from "new features" — you must track them, but whether you hit them depends on luck.

Foldables: Crash on the Moment of Unfolding

We tested on Mate X series and saw:

IndexOutOfBoundsException at ...ViewGroup.measureVertical

The trigger is tricky: the moment of unfold/fold.

On unfold, DPI and screen size change within one layout pass. If your layout code caches the previous size in onMeasure or uses fixed pixel values, it computes wrong during this "size mutation."

There's also the 60Hz → 120Hz switch issue: if you compute animation time using a fixed frame rate instead of real timestamps, you'll see obvious tearing on high refresh screens.

Our handling:

  1. All layouts use dp/sp; no hardcoded px in code.
  2. Use WindowMetricsCalculator or WindowInsets to get current size, read every time, don't cache.
  3. Animations use System.nanoTime() time difference instead of assumptions like "16ms per frame."
  4. Listen for foldable form changes with onConfigurationChanged / WindowLayoutInfo, don't guess with screenWidth / 2.

Android 16 (API 36): It's Not About the Version Number, It's About Behavior

Google Play timeline: from August 31, 2026, new apps and updates must target API 36; existing apps also have a November window.

But what matters isn't whether you can submit; it's that behavior changes after submission.

Edge-to-edge is forced by default, with no opt-out. After targeting API 36, system bars no longer auto-inset. If your layout uses fixed margins/padding to avoid status bar and navigation bar, it will be visually broken. You must explicitly handle WindowInsets.

Predictive back is mandatory. Code still using onBackPressed() will have broken animations or even navigation flow errors; must migrate to OnBackPressedDispatcher.

Foreground service rules keep tightening. From Android 15, dataSync type foreground services have a runtime limit; from Android 16, background jobs started from a foreground service must respect their own runtime quotas (including jobs created by WorkManager and DownloadManager). If WorkManager isn't running on an Android 16 device, check here first.

Another subtle change: after targeting API 35, the exemption for SYSTEM_ALERT_WINDOW apps starting foreground services from background is narrowed. Previously the exemption was broader; now you must have a current visible overlay window to pull up a foreground service from background. This directly affects the overlay solution in Pitfall 3 — if your overlay service is "woken from background," it breaks when target is raised.

Our Handling Process

First, a note: don't treat targetSdk as a compliance checkbox.

Our 2026 approach:

  1. Do the retarget a quarter early, not right on August 31.
  2. Roll out in phases (Play Console percentage release), so the targetSdk 36 version and the old version are online simultaneously, enabling direct crash rate and ANR rate comparison.
  3. Slice crash and ANR data by targetSdk version, not just OS version.
  4. Set a delta threshold alert: if targetSdk 36 crash rate exceeds old version by a threshold, auto-alert.

Item 3 is key. Many teams group crash rate by Android version; when the SDK upgrades, you can't attribute online issues to it.

On the dependency chain pitfall: raising targetSdk to 36 isn't a one-line Gradle change. You must also upgrade AGP, Kotlin, AndroidX libraries, and all third-party SDKs. The third-party SDK part is the most time-consuming, and you can't change your own code to bypass it. A project that hasn't upgraded dependencies in a year will hit four or five walls in a row.


Behind the Thinking: Why Do We Keep "Hitting" Pitfalls Instead of "Preventing" Them?

Let me talk about methodology, which might be more valuable than any specific pitfall.

Compatibility Is Not "Tested" — It's "Designed"

That senior colleague's line stuck with me: "This kind of compatibility isn't found by 'checking'; it's found by 'crashing into it.'"

It took us years to accept: you can't exhaust all combinations of models × system versions × vendor policies. That's an astronomical number.

So what do we do? Three answers:

First, prioritize with data, don't do aimless full regression.

Pull a table from the crash platform: group by model, compute "crash rate ÷ market share of that model".

If a model's crash rate is 8x its share → immediately raise to P0 audit level

This is far more effective than "run through 200 devices," and concentrates limited manpower where it matters.

Second, maintain a credible real-device matrix, not just "buy more phones."

Our current matrix selection:

Tier Model Coverage Target
P0 Xiaomi 14 (latest HyperOS) Largest user base + newest system policy
P0 Huawei Mate 60 (HarmonyOS 4.x) Huawei's Android compatibility layer
P0 Huawei Mate 60 Pro (HarmonyOS NEXT) Native HarmonyOS, independent target platform
P0 OPPO Find X7 (ColorOS 15) Smart Freeze policy
P1 vivo X100 (Funtouch 15) Background high-power + startForegroundService interception
P1 Honor Magic6 (MagicOS 9) Honor independent policy
P1 Some low-end model (Android 11, WebView not updated) WebView capability floor

Note row 3. Huawei HarmonyOS NEXT and Huawei's Android compatibility layer are two completely different test targets; we prepare a separate device for this.

Third, hand the "low-risk but high-volume" parts to automation.

UI layout overlapping, truncation at different DPI — these can be run on cloud real devices at low cost. We concentrate manual effort on deep behavior validation on P0 devices.

But More Importantly: We Turn "Pitfalls" into "Assets"

I think this is the most shareable point.

Every time an online issue occurs, we force three actions:

  1. Write into KNOWN_ISSUES.md (symptom / root cause / verification)
  2. Write a runnable detection script or unit test
  3. Write into the compatibility matrix's verification checklist, so the next release automatically runs it

These three mean: we only step on the same pitfall once.

A real example. The "five ROMs crashing on Provider init order" bug — after fixing, we did:

Item 3 is key. If you only "fix" it, the next person adding an SDK will still trip. We need to make it impossible to trip again.

A Counter-Intuitive Conclusion

After doing all this, I found we actually spend less time on "specific vendor compatibility."

Because pitfalls went from "unknown" to "known," from "hours of debugging each time" to "10 minutes of doc lookup."

The cost of compatibility is not in fixing; it's in discovery and memory. Fixing a known problem is usually dozens of lines; discovering it, locating it, remembering it, and preventing recurrence is where the real time burns.


The Engineering Assets We've Accumulated

Here's what we actually use now. These can't be copied wholesale, but you can follow the pattern.

1. Compatibility Matrix Document (COMPATIBILITY.md)

Not a model spec table; it's a "which behavior does what on which device" table:

Capability Xiaomi 14 / HyperOS Huawei / HarmonyOS 4 OPPO / ColorOS 15 vivo / Funtouch 15
Background Service needs auto-start+associated-start+battery whitelist needs "App Launch Management" three toggles "Smart Freeze" kills foreground services startForegroundService intercepted
Vendor Push MiPush token normal HMS token needs agconnect config OPPO Push needs AppKey vivo Push needs api_key
Overlay needs three toggles needs foreground Activity token generic Intent intercepted needs manual guidance
Implicit broadcast partial interception tightened tightened tightened
WebView Chromium follows store updates Huawei self-developed kernel Chromium Chromium

2. ROM Adapter Layer (RomAdapter)

Unifies vendor differences; business code contains no if (isXiaomi):

interface RomAdapter {
    fun getRomType(): RomType
    fun isAutoStartEnabled(): Boolean
    fun openAutoStartSettings(activity: Activity)
    fun isIgnoringBatteryOptimizations(context: Context): Boolean
    fun openBatteryOptimizationSettings(activity: Activity)
    fun isOverlayFullyGranted(context: Context): Boolean
    fun openOverlaySettings(activity: Activity)
}

Key design principle: vendor detection is centralized in RomDetector; vendor jumps are in each adapter; business layer is completely unaware.

3. Pre-Release Self-Check Script (SelfCheckRunner)

Runs after app startup, reports results to your own monitoring:

[SelfCheck] rom=MIUI_HyperOS
[SelfCheck] autostart=GRANTED
[SelfCheck] batteryOpt=IGNORED
[SelfCheck] notification=GRANTED
[SelfCheck] overlay=NOT_REQUIRED
[SelfCheck] pushToken=huawei(HMS):OK mi(Xiaomi):OK oppo:OK vivo:OK

This report saves 80% of debugging time when users complain "messages not arriving." User sends a screenshot, we know instantly which toggle is off.

4. Compatibility Test Checklist (COMPAT_CHECKLIST.md)

Must run before every release; each item has a clear pass criterion:

- [ ] ROM detection correct (5 P0 devices, output matches expectation)
- [ ] Auto-start/associated-start guidance (can jump to correct page when not authorized)
- [ ] Background survival (after 30 min screen off, local data timestamp updated)
- [ ] Vendor push (message still delivered after killing process, 3 tests each on 5 vendors)
- [ ] Overlay (still exists after authorizing and backgrounding for 10 seconds)
- [ ] Privacy compliance (no network requests before consent, verified via Charles capture)
- [ ] WebView (full flow passes on Chromium 74 environment)
- [ ] Android 16 edge-to-edge (no page occlusion)
- [ ] Foldable unfold/fold no crash

5. Crash Attribution Rules

In Crashlytics, use ROM type + targetSdk version as custom dimensions, not model name.

// Report with these two dimensions
crash.setCustomKey("rom_type", RomDetector.getRomType().name)
crash.setCustomKey("target_sdk", BuildConfig.TARGET_SDK.toString())

That way you can answer the question "is it Xiaomi's problem or mine."


Finally

Looking back at these eight pitfalls, they seem unrelated, but underneath is the same logic:

Every pitfall in domestic Android is driven by a vendor's explicit product decision or business goal. Power saving, battery life, benchmark scores, app store ecosystems, privacy compliance thresholds — these goals determine how the system treats your process, your permissions, your push.

You can't convince the system. You can only:

  1. Know what it's defending against, so you can predict when it will act
  2. Request permission through official channels, instead of fighting the system
  3. Design architecture where "dead but alive" works, instead of betting the process stays alive
  4. Turn every pitfall into an executable detection, so it changes from "incident" to "state"

Point 4 is most often skipped but highest value. Fixing a bug solves today; turning a bug into detection and process solves next year.

If you're also doing domestic Android adaptation, feel free to share your more absurd pitfalls in the comments. I'm most curious about the ones not found in official docs, only by crashing into them — like a vendor's ROM version that, because of some push, changed one of your system API behaviors, and the docs never mentioned it.

Those are the real "found by crashing" pitfalls.


Note: The menu paths, Intents, and vendor private APIs mentioned in this article change with ROM versions; when implementing, verify against the target device's actual version. Our team's practice: all vendor-related code is in one directory; ROM upgrades only touch that directory.