A Developer's Checklist for Migrating Mobile Apps Between Android Skins

Hook — Why migrating between Android skins is a silent project risk

You're shipping an OS upgrade, OEM partners are pushing new skins, and suddenly a handful of users report navigation glitches, truncated layouts, and background tasks that never run. For engineering and release teams this is familiar: Android skin differences (One UI, MIUI, ColorOS, OriginOS, etc.) introduce subtle breakages that surface only after wide rollouts. This checklist is a practical, developer-first guide to preparing apps for OEM skin differences during OS upgrades in 2026 — concrete items you can act on today.

The 2026 context you need to know

Through late 2024–2025 OEMs increased UI and runtime customization: custom gesture mappings, aggressive battery heuristics, and alternative system UI composition. In early 2026 you can expect:

• Wider adoption of dynamic refresh rates and variable density scaling across devices (60–144Hz and runtime density changes).
• Stricter privacy and permission flows (continuing Project Mainline modularization and scoped APIs).
• OEMs shipping forks that change default nav patterns and quick settings tile behavior.
• Tooling improvements: Firebase Test Lab and Play Console pre-launch reports added more OEM-specific checks in 2025–2026, but they don’t catch every skin-level quirk.

Tip: treat a major OEM skin update like a micro-OS upgrade — test broadly and automate aggressively.

How to use this checklist

Use this as a release checklist embedded into your migration sprint. Split items into: Code & API, UI & DPI, Navigation & Input, Background & Power, Testing, and Rollout. Each checklist item includes why it matters, what to change, and test patterns.

Pre-migration audit

• Inventory: collect third-party SDKs, reflection usage, native libraries, and any private API access. Use automated scanners (grep for com.android.internal, reflection of hidden fields/methods).
• Targeting: confirm compileSdk, targetSdk, and minSdk in Gradle. For 2026, targetSdk should be the most recent stable Android release your app supports; prepare feature flags for behavior changes tied to targetSdk bumps.
• Permissions map: list all runtime and background permissions, and note which ones changed flows since Android 11–14. Verify your app’s UX for new temporary and one-time permissions.

APIs to avoid or replace (concrete list)

Avoid brittle or OEM-dependent APIs. Replace with stable AndroidX or documented platform APIs.

• Hidden/internal APIs (com.android.internal.*) — They break across OEM skins and Android builds. Replace with public SDK equivalents or AndroidX helpers.
• Reflection to access private fields/methods — Hidden API enforcement is stricter in many OEM builds. Use documented APIs or AIDL where appropriate.
• Direct writes to settings (Settings.System/Global) — Many OEMs restrict writes; use Intent-based flows or Settings panels provided by the platform (Settings.ACTION_APPLICATION_DETAILS_SETTINGS, Settings.Panel APIs).
• AlarmManager for long-running/deferrable work — Prefer WorkManager or JobScheduler for reliability across OEM battery managers.
• Accessing external storage via file paths — Use Scoped Storage and Storage Access Framework (SAF). File paths break across OEMs and Android versions.
• Assuming system UI elements (navigation bar, status bar heights) — Use WindowInsets and WindowInsetsController APIs instead of hard-coded sizes.
• Package visibility queries without filters — Android 11+ restricts queries; declare queries in your manifest or use intent-based discovery.

What to use instead (short guide)

• WindowInsetsCompat / WindowInsetsController for insets and immersive mode. (See: https://developer.android.com/reference/androidx/core/view/WindowInsetsCompat)
• Jetpack WindowManager / Window Size Classes for foldable and multi-window handling. (https://developer.android.com/window)
• WorkManager for deferred and guaranteed background work. (https://developer.android.com/topic/libraries/architecture/workmanager)
• AndroidX Navigation and OnBackPressedDispatcher for consistent back behavior.
• Scoped Storage APIs and SAF for file access.

DPI, density, and display handling checklist

OEM skins often add display scaling toggles, letterboxing, or runtime display-density changes. Avoid breakage by supporting a full matrix of densities and sizes.

1. Use dp/sp and resource qualifiers

   Never hardcode pixels. Use dp for layout and sp for text. Provide alternative layouts for large screens using res/values-sw600dp and other sw qualifiers.

2. Handle runtime density changes

   Recent OEMs allow users to change display size in Settings which can scale the density at runtime. Listen for configuration changes (fontScale/density) and rebuild views or use onConfigurationChanged appropriately. Avoid caching size-dependent bitmaps.

3. Support dynamic refresh rates

   Respect the display's preferred mode. For animation-critical flows, request a specific refresh rate via Window attributes but allow fallbacks—do not assume 60Hz. Test on 90/120/144Hz panels.

4. Adaptive icons and multiple densities for drawables

   Provide vector drawables where possible; fallback PNGs for critical bitmaps across density buckets (mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi).

5. Foldable and large-screen rules

   Use Jetpack WindowManager to detect posture and layout accordingly. Respect resizableActivity in the manifest and handle multi-window mode.

Navigation & input: patterns that break across skins

OEMs implement custom gestures or change the system-provided navigation rail. Your app should adapt, not assume.

• Don't assume a visible back/up button — Use the OnBackPressedDispatcher and AndroidX Navigation component so your back handling works regardless of gesture or three-button mode.
• Handle insets for gesture navigation — For gesture navigation, the bottom inset is often smaller but gestures can conflict with horizontal-swipe UIs. Use WindowInsetsCompat to adjust touch targets.
• Avoid full-screen edge swipes for core app interactions — If you require horizontal edge swipes, provide an alternative or require an affordance to avoid colliding with system gestures on some skins.
• Navigation bars can be repositioned or hidden — Avoid layout assumptions for their location; anchor UI elements to safe insets.

Example: safe back handling (Kotlin)

class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    val navController = findNavController(R.id.nav_host)
    onBackPressedDispatcher.addCallback(this) {
      if (!navController.popBackStack()) {
        finish()
      }
    }
  }
}

Background work and power management

OEM skins are the most aggressive source of background restrictions. In 2025–26 many manufacturers expanded heuristics that hibernate apps after short idle periods.

• Use WorkManager for deferrable tasks and foreground services for time-critical tasks. Avoid assuming long-lived background services will survive OEM optimizers.
• Document a user-facing guide — For critical apps, provide an onboarding screen explaining how to whitelist the app in common OEM battery managers (Xiaomi, Oppo, vivo, Samsung). Include direct deep-links to the OEM settings screens when possible.
• Handle Doze and App Standby — Use AlarmManager.setExactAndAllowWhileIdle sparingly and prefer WorkManager with appropriate constraints.
• Background location and foreground services — Verify your notification UX and permission flows for foreground location access and background location permission prompts; OEMs sometimes change the notification prominence rules.

OEM-specific behaviors to check

While you can't test every fork, prioritize these OEM differences:

• Navigation gesture remapping — Some skins add back gestures that differ from AOSP gestures.
• Quick Settings and tile APIs — Tiles can behave differently when OEMs wrap them in custom Quick Settings UIs.
• Theme & dark mode overrides — Some OEMs force dark mode or invert colors at the system level. Respect the platform night mode and test color contrast.
• Keyboard and IME behavior — Custom IMEs can deliver different insets or animation timings; test text fields across popular keyboards.
• OEM file managers and document providers — Test SAF flows across common file provider implementations to avoid crashes when users pick files from OEM providers.

Compatibility testing matrix (practical)

Create a device matrix covering these dimensions — automate where possible:

• Baseline: Google Pixel (AOSP-ish behavior)
• Top OEMs by market share and divergence: Samsung (One UI), Xiaomi/Redmi (MIUI), OnePlus (OxygenOS/ColorOS convergence), Oppo (ColorOS), vivo (OriginOS), Realme, HONOR, ASUS
• Form factors: phone, phablet, foldable, tablet
• Density and refresh rate variants
• Android versions targeted by your app (e.g., Android 13–15 if applicable)

Tools and suggestions:

• Firebase Test Lab and AWS Device Farm — schedule automated Espresso/UiAutomator runs for smoke tests on real OEM devices.
• Play Console Pre-launch Reports — catch crashes and accessibility issues across devices.
• Local device farm or partner devices — test interactive flows, gestures, and OEM settings whitelisting.
• Use emulators for quick DPI and orientation permutations, but don’t rely solely on them for OEM quirks.

CI/CD integration and automation

Embed these checks into your pipeline:

• Static analysis: detect reflection and hidden API usage, flag direct settings writes, and ensure use of AndroidX substitutes.
• Unit tests for configuration changes — simulate density/font/locale changes.
• Instrumented UI tests for gesture-sensitive screens, run on Firebase Test Lab matrix as part of pre-release checks.
• Automated metrics collection on canary releases — aggregate ANRs, crashes, battery, and render jank by OEM and skin.

Rollout, monitoring, and rollback

• Staged rollouts per OEM — Use the Play Console to stagger releases and monitor OEM-specific metrics. If you see a spike in crashes on a given OEM skin, halt that cohort.
• Feature flags — Gate risky behavior (native hooks, new background flows, density-sensitive layouts) behind remote flags so you can disable on-the-fly per OEM segment.
• Telemetry tags — Tag crash reports and vitals with device manufacturer, model, and skin version. This lets you triage skin-specific regressions quickly.
• Rollback plan — Have a documented, quick rollback path in Play Console and ensure your backend can handle older client versions if you must roll back client changes.

Practical tests and acceptance criteria (quick checklist)

1. Critical flows pass on at least one device per OEM tier (login, payment, file pick, background sync).
2. No crashes attributable to hidden API or reflection calls in 100% of tested OEM devices.
3. Layouts pass visual QA at three density extremes and on foldable posture changes.
4. Background jobs complete within expected windows on at least 80% of tested OEMs; document required user whitelisting steps for the rest.
5. Back navigation works with gesture nav and three-button nav without unexpected app exits or duplicated screens.

Developer tips and tricks

• Prefer vector drawables and avoid rasterizing text into images.
• Keep a short OEM reference doc for support teams with device-specific troubleshooting steps (battery whitelist steps, settings deep-links).
• When possible, test using a GSI (Generic System Image) to reproduce AOSP behavior, then contrast with OEM images to isolate skin effects.
• Log system insets and configuration changes in debug builds to detect unexpected OEM-inserted configuration differences quickly.

Case study: shipping an OS upgrade with minimal fallout (example)

At a mid-sized fintech in late 2025 we prepared for a major OS+skin rollout across top markets. Actions we took:

• Ran a static scan and removed two reflection usages; replaced with AndroidX equivalents.
• Instrumented UI tests to simulate 4 density scalings and foldable posture; found a broken onboarding screen on one vendor due to an unexpected bottom inset — fixed by WindowInsets handling.
• Added an onboarding modal that linked to OEM battery whitelist deep-links for three vendors; reduced “background sync fails” support tickets by 62% in first week.
• Deployed a staged rollout with per-OEM telemetry; paused rollout for a specific skin when crash rate exceeded threshold, patched and resumed 48 hours later.

Further reading and references

• WindowInsets guide — Android Developers
• WorkManager — AndroidX
• Supporting Different Screens — Android Developers
• Activity lifecycle and configuration changes
• Firebase Test Lab

Actionable takeaways — checklist you can apply in one sprint

• Remove hidden API/reflection usage; replace with AndroidX where possible.
• Switch background work to WorkManager and verify foreground services with proper notifications.
• Implement WindowInsets-based layout handling and test for gesture nav vs 3-button nav.
• Provide density and sw-layout resources; test on 3 density extremes and a foldable.
• Instrument per-OEM telemetry, use staged rollouts, and prepare a rollback path and feature flags.

Closing: a short checklist to copy to your sprint board

• Static scan: hidden APIs/reflection — REMOVE
• UI: WindowInsets/InsetsCompat — IMPLEMENT
• Work: WorkManager, foreground notifications — VERIFY
• Resources: vectors + sw qualifiers + densities — ADD
• Testing: Firebase Test Lab + 1 device per OEM tier — SCHEDULE
• Release: staged rollout + telemetry + feature flags — PLAN

Call to action

Migration projects succeed when they’re repeatable. Save time: download a pre-filled migration checklist and OEM troubleshooting templates you can plug into your sprint board. If you manage developer workflows, try pasty.cloud to share and embed troubleshooting snippets, manifest diffs, and test commands securely with your team during the rollout — sign up for a 14‑day trial and get the checklist PDF included.

Related Reading

• How to model cost for large-scale analytics: ClickHouse use cases and pricing patterns
• How ‘Arirang’ Could Reframe BTS’ Global Narrative — Politics, Identity and Reunions on Tour
• Platform Migration Playbook: How Streamers and Esports Orgs Can Use Bluesky to Diversify Audiences
• DIY Olive Oil Beauty Launchpad: Create Pro-Level Face Oils and Cleansers at Home
• Montpellier for Families: Country-Style Villas and Kid-Friendly Amenities