Android for React Native developers

react-native · folio

In one line: android/ is an ordinary Gradle project embedding a JS bundle: AGP compiles Kotlin/Java (R8 shrinks it), the NDK builds C++ per ABI, the manifest merger combines every library’s manifest, you sign with an upload key and Play re-signs. Most Android “RN bugs” are manifest, permission, SDK-level or R8 problems.

Download PDF Print view LaTeX source

Android for React Native developers — figure 1

Gradle, SDK levels, Play rules

  • Three SDK numbers: minSdk = oldest device that installs; compileSdk = APIs you can call; targetSdk = which new behaviours you opt into.
  • Play target API: since 31 Aug 2026 new apps and updates must target API 36 (Wear/Automotive 35, TV/XR 34; extension to 1 Nov 2026 on request); existing apps below 35 stop reaching new users on newer Android.
  • 16 KB pages: targets Android 15+ must support 16 KB-page 64-bit devices (Android guide: updates blocked from 1 Feb 2027). AGP 8.5.1+/NDK r28+ align by default; RN is compliant since 0.77 — check third-party .so in APK Analyzer.
  • Toolchain: JDK 17; AGP comes via RN’s Gradle plugin; 0.87 adds AGP 9 (android.builtInKotlin=false, android.newDsl=false). Since 0.82 newArchEnabled=false is ignored.

Manifest

  • Merged: every library adds its manifest — read Android Studio’s Merged Manifest tab; drop an unwanted permission with tools:node="remove".
  • android:exported must be explicit on any component with an intent filter (Android 12+), else the app won’t install. Launcher activity: true.
  • Template MainActivity: singleTask (deep links reuse it), adjustResize, configChanges (rotation keeps the React root). App Links: autoVerify + /.well-known/assetlinks.json.

Example — manifest + permission

<uses-permission android:name="android.permission.CAMERA"/>
<activity android:name=".MainActivity" android:exported="true"
  android:launchMode="singleTask"
  android:windowSoftInputMode="adjustResize">
  <intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW"/>
    <category android:name="android.intent.category.DEFAULT"/>
    <category android:name="android.intent.category.BROWSABLE"/>
    <data android:scheme="https" android:host="example.com"/>
  </intent-filter></activity>
<!-- JS: await PermissionsAndroid.request(PERMISSIONS.CAMERA)
     'granted' | 'denied' | 'never_ask_again' -> openSettings -->

Runtime permissions

  • Dangerous permissions (Android 6+) need manifest and a runtime request: check → rationale (shouldShowRequestPermissionRationale) → request. POST_NOTIFICATIONS is runtime since Android 13.
  • Android 11+: Deny twice = “don’t ask again” — the dialog never shows, send users to Settings. “Only this time” for location/camera/mic; unused apps get permissions auto-reset. Re-check on every resume.

Back, edge-to-edge, R8, signing

  • BackHandler: listeners run LIFO; return true consumes; none → default back. An open Modal blocks BackHandler — use onRequestClose.
  • Target 36: predictive back on by default, onBackPressed not called, KEYCODE_BACK not dispatched (BackHandler still works for most cases; opt-out enableOnBackInvokedCallback="false"); edge-to-edge can’t be opted out — use safe-area insets.
  • R8 keeps only what it sees: reflection, JNI, JSON-by-field-name need -keep class … / @Keep.
  • Signing: keytool -genkeypair … -validity 10000 → upload key; passwords in ̃/.gradle/gradle.properties, not git. Play App Signing holds the real key, so a lost upload key can be reset.

Build errors → fix

  • SDK location not found → ANDROID_HOME / local.properties. Java version errors → JDK 17 (JAVA_HOME).
  • Duplicate class … in modules → two versions of one library: align/exclude. Incompatible Kotlin metadata → align Kotlin versions.
  • INSTALL_FAILED_UPDATE_INCOMPATIBLE → different signing key: uninstall. Unable to load script → adb reverse tcp:8081 tcp:8081.
  • Release-only ClassNotFoundException → keep rules. Stale native build → ./gradlew clean, delete app/.cxx.

Traps

  • The template’s release uses the debug keystore — replace it before shipping.
  • Bumping targetSdk “just for Play” — it switches on new behaviour (back, edge-to-edge); test it like a feature.

Remember

min = who installs · compile = what you call · target = how you behave. You sign uploads; Play signs installs.

Report a problem ·Discuss this folio