| name | android-platform |
| description | This skill should be used when the user asks about "Android permissions", "runtime permissions", "camera permission", "storage permission", "notifications", "Photo Picker", "Credential Manager", "Predictive Back", "per-app language", "Baseline Profiles", "Android 16", "adaptive layouts", "Android crash", "Gradle sync fails", "build error", "ANR", "ProGuard", "R8", "Android emulator", or mentions requesting permissions, using platform APIs, troubleshooting Android errors, or dealing with crashes and build failures. Provides permissions guidance, modern platform features, and troubleshooting for Android development. |
| version | 1.0.0 |
| tags | ["android","permissions","platform","troubleshooting","debugging"] |
| allowed-tools | ["Read"] |
Android Platform
Overview
Guide users through Android platform features, runtime permissions, and troubleshooting. Cover modern APIs that replace older approaches, permission best practices, and common error resolution. Emphasis on current best practices — many online tutorials teach deprecated patterns.
Disclaimer: This skill provides educational guidance for learning Android development. For production apps handling sensitive user data, payment processing, authentication, or security-critical features, consult a professional Android developer or security auditor.
Runtime Permissions Decision Tree
Before requesting a permission, check if you actually need it:
Do I need this capability?
├── Camera → REQUEST_PERMISSION (CAMERA)
├── Location → REQUEST_PERMISSION (ACCESS_FINE_LOCATION or COARSE)
├── Pick a photo/video → USE Photo Picker (no permission needed!)
├── Read/write media → USE MediaStore API (scoped storage, no permission needed for own files)
├── Read all files → AVOID if possible; REQUEST_PERMISSION (READ_MEDIA_IMAGES etc.) if needed
├── Notifications (API 33+) → REQUEST_PERMISSION (POST_NOTIFICATIONS)
├── Bluetooth (API 31+) → REQUEST_PERMISSION (BLUETOOTH_CONNECT)
└── Contacts, Calendar, etc. → REQUEST_PERMISSION (specific permission)
Permission Request Flow
- Check if the feature is essential — if optional, offer degraded experience without it
- Explain why before requesting — users grant permissions at higher rates when they understand the reason
- Use
ActivityResultContracts.RequestPermission() (not the deprecated onRequestPermissionsResult)
- Handle denial gracefully — show explanation, offer alternative, never block the app
- Handle "Don't ask again" — direct user to Settings with a clear explanation
Modern Platform Features
Features that replace older approaches — present with rolling API requirements:
| Feature | Min API | What It Replaces | Why It Matters |
|---|
| Photo Picker | 19 (backported) | READ_EXTERNAL_STORAGE for media selection | No permission needed; scoped, privacy-preserving |
| Credential Manager | 23 (backported) | SmartLock, legacy login flows | Passkeys, passwords, federated sign-in in one API |
| Predictive Back | 34+ (opt-in, default on API 35+) | onBackPressed() override | System back gesture shows preview; breaks apps that don't handle it |
| Per-app Language | 33+ | Manual locale switching | System-managed language per app |
| Baseline Profiles | 24+ | No equivalent | 15-50% cold start improvement; profiles compiled AOT |
| Scoped Storage | 29+ (enforced 30+) | WRITE_EXTERNAL_STORAGE | App-specific dirs without permission; MediaStore for shared media |
| Foreground Service Types | 34+ | Untyped foreground services | Must declare type (camera, location, etc.) in manifest |
| Adaptive Layouts | Recommended for all | Fixed orientation lock | Can't restrict orientation on large screens (Android 16+) |
Predictive Back — Important Note
Predictive Back is on by default starting API 35. Apps that override onBackPressed() or use FLAG_ACTIVITY_CLEAR_TOP carelessly will break. To prepare:
- Use
OnBackPressedCallback instead of overriding onBackPressed()
- Enable
android:enableOnBackInvokedCallback="true" in the manifest to test
- Compose Navigation handles this correctly by default
Troubleshooting Quick Reference
| Error / Symptom | Likely Cause | Fix |
|---|
Gradle sync failed | Version mismatch, missing SDK | Check references/troubleshooting.md |
Unresolved reference after adding dependency | Missing Gradle sync | Sync Gradle files |
| App crashes on rotation | State not in ViewModel | Move state to ViewModel + StateFlow |
NetworkOnMainThreadException | Network call on Main thread | Use Dispatchers.IO in repository |
| Compose preview blank | Missing @Preview parameter defaults | Add default parameter values |
INSTALL_FAILED_OLDER_SDK | Device API < minSdk | Lower minSdk or use newer device |
| Emulator won't start | Hardware acceleration disabled | Enable VT-x/AMD-V in BIOS |
Could not find :compose-bom | Missing Google Maven repository | Add google() to repositories block |
| R8/ProGuard strips needed class | Missing keep rule | Add -keep rule for the class |
java.lang.OutOfMemoryError during build | Insufficient Gradle heap | Increase org.gradle.jvmargs in gradle.properties |
Security Awareness
Flag these areas for professional review — they're beyond educational scope:
- Authentication & user data — Use Credential Manager for basic login; complex auth (OAuth, HIPAA data) needs professional review
- Payment processing — Use Google Play Billing Library; never handle raw payment data
- Encryption — Use Jetpack Security (EncryptedSharedPreferences, EncryptedFile) for local secrets
- Network security — Enable certificate pinning for sensitive APIs; use Network Security Config
- API keys — Never commit to source control; use
local.properties or BuildConfig injection
References
references/permissions-guide.md — Runtime permissions patterns with complete code examplesreferences/platform-features.md — Credential Manager, Predictive Back, Photo Picker, Baseline Profiles deep divesreferences/troubleshooting.md — Common errors, Gradle failures, crash debugging, emulator fixes
