Grant partial access to photos and videos

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).

Note: This change affects any app requesting visual media permissions regardless of the target SDK and requires developer action to properly support it.

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.

Note: If your app already uses the photo picker, you don't need to take any action to support this change. Otherwise, consider using the photo picker instead of adopting this change.

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 and READ_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 the READ_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.

Note: Your app doesn't need any media permission to use photo picker or any system intent actions like ACTION_GET_CONTENT or ACTION_OPEN_DOCUMENT.

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 and READ_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 the READ_MEDIA_VIDEO permission (or both permissions) again.

Note: Create a UI element in your app that the user must press before you re-request the READ_MEDIA_IMAGES or READ_MEDIA_VIDEO permission. The user shouldn't be surprised to see the system dialog 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.

Note: The permission grant may still be denied manually by the user, the device corporate policy or by a permission auto-reset. Always check for the permission instead of assuming a previously granted state.

Permissions from Android 13

Consider the following situation:

1. Your app is installed on a device that runs Android 13.
2. The user has granted the READ_MEDIA_IMAGES permission and the READ_MEDIA_VIDEO permission to your app.
3. 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:

1. Your app is installed on a device that runs Android 13.
2. The user has granted the READ_EXTERNAL_STORAGE permission or the WRITE_EXTERNAL_STORAGE permission to your app.
3. 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 using ContentResolver, 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.