Choose by task, not by settings label
| User task | Prefer investigating |
|---|---|
| Attach one photo | System photo picker |
| Import one PDF | Document picker through the Storage Access Framework |
| Browse a media library as a core feature | MediaStore with the required current access model |
| Store the app's own cache | App-specific storage |
| Manage many unrelated shared files | All-files eligibility only when genuinely justified |
The photo picker and storage overview offer narrower alternatives to blanket access.
Support limited access
On supported Android versions, users can grant selected media rather than the whole collection. Code should not interpret an incomplete query result as data loss or demand unrestricted access merely to continue.
Keep the UI aligned with the granted scope. Offer a way to select additional items when the feature needs them, and refresh access state when returning to the app.
Work with URIs safely
Use the returned URI and its granted access, not a guessed file path. Check MIME type and content where appropriate, bound memory usage and handle canceled selection. If the app needs long-lived access, follow the provider and API's documented persistable-grant behavior rather than assuming every URI lasts forever.
Keep permissions version-aware
Granular media permissions apply differently from legacy external-storage declarations. A copied manifest containing every old and new permission can over-request access without fixing the actual code path.
Document the supported API ranges and test each meaningful branch, including denial and revocation.
Review the release with APKLint
APKLint can help identify broad storage or media declarations in the merged manifest. It cannot tell whether a selected URI is still readable or whether the gallery UI handles partial access correctly. Those checks belong in the feature's runtime tests, including large files, remote providers and a user canceling the picker.
Map an attachment, a gallery and a cache separately
An application can have three file-related features with different requirements: attaching one photo to a message, browsing a media collection and caching its own thumbnails. Do not assign all three the broadest permission used by any one feature. Model the attachment through user selection, investigate the appropriate media access for the gallery and keep generated cache data in app-specific storage.
The storage overview explains these categories. The partial photo and video access guidance adds a critical gallery case: the user can allow only selected media on supported versions. Your query and UI must reflect that scope rather than treating the rest of the library as deleted.
Refresh a gallery after the user changes the selection
Start with two accessible photos, then let the user add another through the supported reselection flow. Refresh the accessible data and ensure that the new item appears without duplicating the original two. Next remove or revoke access to one item and confirm that an old cached tile cannot be opened as though permission still exists.
Keep cached metadata and current read access separate. A thumbnail generated earlier can remain visible after access changes, but it does not authorize reopening the original. Decide how the UI should invalidate or label stale entries, and handle the resolver failure even when a preceding capability check appeared positive.
For a selected PDF attachment, preserve its URI access only for the duration required by the feature and inspect the content stream safely. A media-library permission is not a universal grant to arbitrary document providers. Likewise, a picker grant for one image does not authorize enumerating every image in shared storage.
Use a test matrix keyed by device API, target SDK and feature. Include fresh installation, partial grant, full grant where supported, denial, reselection and returning from settings. Record expected visible items for each case so an empty query can be distinguished from an implementation failure. Avoid requesting all permissions again merely because fewer items were returned than in a previous run.
Review dependencies after removing unnecessary declarations. A library can reintroduce a permission through manifest merging, and an old direct-path code branch can remain even when the UI uses a picker. Inspect the final artifact and test the actual release path together before considering the migration complete.
Sources and further reading
- Android Developers: Access media files from shared storage
- Android Developers: Photo picker
- Android Developers: Data and file storage overview
Reference review: 29 September 2026. Examples illustrate the workflow; check your installed versions, release artifact and account-specific Console requirements before applying them. This guide is not a claim that APKLint executed your project or verified your private account.
Android inspection tools and practical release guides. About APKLint · Report a correction
