Users who interact with your app on Android 14 devices can now grant partial
access to their visual media library (Photos/Videos) when an app requests any
visual media permissions (READ_MEDIA_IMAGES
or READ_MEDIA_VIDEO
) introduced
in Android 13 (API level 33).
The new dialog contains the following options:
- Select photos and videos: New in Android 14. The user selects the specific photos and videos that they want to make available to your app.
- Allow all: The user grants full-library access to all photos and videos on the device.
- Don't allow: The user denies all access.
If the user chooses Select photos and videos and your app later requests
READ_MEDIA_IMAGES
or READ_MEDIA_VIDEO
again, the system displays a different
dialog, giving the user a chance to grant full access, keep the current
selection, or grant additional photos and videos. After a certain period of
time, the system directly shows the system picker instead.
To help apps support the new changes, the system introduces a new permission,
READ_MEDIA_VISUAL_USER_SELECTED
. The system behaves differently, based on
whether or not your app uses the new permission.
Behavior if your app makes no change
If you don't declare the READ_MEDIA_VISUAL_USER_SELECTED
permission, the
following behavior occurs:
- The
READ_MEDIA_IMAGES
andREAD_MEDIA_VIDEO
permissions are granted during the app session, providing a temporary permission grant and temporary access to the user-selected photos and videos. When your app moves to the background, or when the user actively kills your app, the system eventually denies these permissions. This behavior is just like other one-time permissions. - If your app needs access to additional photos and videos at a later time,
you must manually request the
READ_MEDIA_IMAGES
permission or theREAD_MEDIA_VIDEO
permission again. The system follows the same flow as with the initial permission request, prompting users to select photos and videos.
If your app is following permissions best practices, this change shouldn't break your app. This is especially true if your app doesn't assume that URI access is retained, stores system permission state, or refreshes the set of displayed images after the permission changes. However, this behavior might not be ideal depending on your app's use case.
Migrate to control behaviour in your app
If you declare the READ_MEDIA_VISUAL_USER_SELECTED
permission, and the user
chooses Select photos and videos in the system permissions dialog, the
following behavior occurs:
- The
READ_MEDIA_IMAGES
andREAD_MEDIA_VIDEO
permissions are both denied. - The
READ_MEDIA_VISUAL_USER_SELECTED
permission is granted, providing partial and temporary access to the user's photos and videos. - If your app needs access to other photos and videos, you must manually
request the
READ_MEDIA_IMAGES
permission or theREAD_MEDIA_VIDEO
permission (or both permissions) again.
Keep in mind that READ_MEDIA_IMAGES
and READ_MEDIA_VIDEO
are the only other
permissions needed to access the user's photos and videos photo library.
Declaring READ_MEDIA_VISUAL_USER_SELECTED
makes the permission controller
aware that your app supports a manual re-request to select more photos and
videos.
To prevent users from seeing multiple system runtime dialog boxes, request the
READ_MEDIA_VISUAL_USER_SELECTED
, ACCESS_MEDIA_LOCATION
and the "read media"
permissions (READ_MEDIA_IMAGES
, READ_MEDIA_VIDEO
, or both) in a single
operation.
Photo and video access is preserved when the device upgrades
In cases where your app is on a device that upgrades from an earlier Android version to Android 14, the system keeps full access to the user's photos and videos, and it grants some permissions to your app automatically. The exact behavior depends on the set of permissions that are granted to your app before the device upgrades to Android 14.
Permissions from Android 13
Consider the following situation:
- Your app is installed on a device that runs Android 13.
- The user has granted the
READ_MEDIA_IMAGES
permission and theREAD_MEDIA_VIDEO
permission to your app. - The device then upgrades to Android 14 while your app is still installed.
In this case, your app still has full access to the user's photos and videos.
The system also keeps the READ_MEDIA_IMAGES
and READ_MEDIA_VIDEO
permissions
granted to your app automatically.
Permissions from Android 12 and lower
Consider the following situation:
- Your app is installed on a device that runs Android 13.
- The user has granted the
READ_EXTERNAL_STORAGE
permission or theWRITE_EXTERNAL_STORAGE
permission to your app. - The device then upgrades to Android 14 while your app is still installed.
In this case, your app still has full access to the user's photos and videos.
The system also grants the READ_MEDIA_IMAGES
permission and the
READ_MEDIA_VIDEO
permission to your app automatically.
Best practices
This section contains several best practices for using the
READ_MEDIA_VISUAL_USER_SELECTED
permission. For more information, check out
our permission best practices.
Background media processing essentially requires the new permission
If the app does media processing, such as compressing or uploading media in the
background, keep in mind that the READ_MEDIA_IMAGES
and READ_MEDIA_VIDEO
permission states eventually become denied again. We strongly recommend that
you add support for READ_MEDIA_VISUAL_USER_SELECTED
. Alternatively, your app
should check if it has access to the specific photo or video by opening an
InputStream
or querying using ContentResolver
.
Don't store the permission state permanently
Don't store the permission state in a permanent way, including
SharedPreferences
or DataStore
. The stored state might not be in sync with
the actual state. The permission state can change after permission reset,
app hibernation, a user-initiated change in your app's settings, or when
your app goes into the background. Instead, check for storage permissions using
ContextCompat.checkSelfPermission()
.
Don't assume full access to photos and videos
Based on the changes introduced in Android 14, your app might have only partial
access to the device’s photo library. If the app is caching MediaStore
data
when queried using ContentResolver
, the cache might not be up to date.
- Always query
MediaStore
usingContentResolver
, instead of relying on a stored cache. - Keep the results in memory while your app is in the foreground.
Treat URI access as temporary
If the user chooses Select photos and videos in the system permissions
dialog, your app's access to the selected photos and videos will expire
eventually. Your app should always handle the case of not having access to any
Uri
, no matter their authority.