Teilzugriff auf Fotos und Videos gewähren

Mit Android 14 wird der Zugriff auf ausgewählte Fotos eingeführt. Damit können Nutzer Apps Zugriff auf bestimmte Bilder und Videos in ihrer Mediathek gewähren, anstatt Zugriff auf alle Medien eines bestimmten Typs.

Diese Änderung wird nur aktiviert, wenn deine App auf Android 14 (API-Level 34) oder höher ausgerichtet ist. Wenn du die Bildauswahl noch nicht verwendest, solltest du sie in deiner App implementieren. So kannst du Bilder und Videos einheitlich auswählen und gleichzeitig den Datenschutz für Nutzer verbessern, ohne dass du Speicherberechtigungen anfordern musst.

Wenn du eine eigene Galerieauswahl mit Speicherberechtigungen verwendest und die volle Kontrolle über deine Implementierung hast, passe deine Implementierung an, um die neue Berechtigung READ_MEDIA_VISUAL_USER_SELECTED zu verwenden. Wenn Ihre App die neue Berechtigung nicht verwendet, führt das System sie in einem Kompatibilitätsmodus aus.

Ziel-SDK	READ_MEDIA_VISUAL_USER_SELECTED deklariert	Zugriff auf ausgewählte Fotos aktiviert	UX-Verhalten
SDK 33	Nein	Nein	–
	Ja	Ja	Von der App gesteuert
SDK 34	Nein	Ja	Vom System gesteuert (kompatibles Verhalten)
	Ja	Ja	Von der App gesteuert

Eigene Galerieauswahl erstellen oder anpassen

Das Erstellen einer eigenen Galerieauswahl erfordert umfangreiche Entwicklungs- und Wartung und Ihre App muss Speicherberechtigungen anfordern, um die ausdrückliche Nutzereinwilligung einzuholen. Nutzer können diese Anfragen ablehnen. Wenn deine App auf einem Gerät mit Android 14 ausgeführt wird und deine App auf Android 14 (API-Level 34) oder höher ausgerichtet ist, kannst du den Zugriff auf ausgewählte Medien einschränken. In der folgenden Abbildung sehen Sie ein Beispiel für das Anfordern von Berechtigungen und das Auswählen von Medien mithilfe der neuen Optionen.

In diesem Abschnitt wird der empfohlene Ansatz zum Erstellen einer eigenen Galerieauswahl mit MediaStore beschrieben. Wenn Sie bereits eine Galerieauswahl für Ihre App haben und die volle Kontrolle behalten müssen, können Sie diese Beispiele verwenden, um Ihre Implementierung anzupassen. Wenn du deine Implementierung nicht für die Verarbeitung ausgewählter Fotos aktualisierst, führt das System deine App im Kompatibilitätsmodus aus.

Berechtigungen anfordern

Fordern Sie zuerst je nach Betriebssystemversion die korrekten Speicherberechtigungen im Android-Manifest an:

<!-- Devices running Android 12L (API level 32) or lower  -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />

<!-- Devices running Android 13 (API level 33) or higher -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />

<!-- To handle the reselection within the app on devices running Android 14
     or higher if your app targets Android 14 (API level 34) or higher.  -->
<uses-permission android:name="android.permission.READ_MEDIA_VISUAL_USER_SELECTED" />

Fordern Sie dann je nach Betriebssystemversion die richtigen Laufzeitberechtigungen an:

// Register ActivityResult handler
val requestPermissions = registerForActivityResult(RequestMultiplePermissions()) { results ->
    // Handle permission requests results
    // See the permission example in the Android platform samples: https://github.com/android/platform-samples
}

// Permission request logic
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
    requestPermissions.launch(arrayOf(READ_MEDIA_IMAGES, READ_MEDIA_VIDEO, READ_MEDIA_VISUAL_USER_SELECTED))
} else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
    requestPermissions.launch(arrayOf(READ_MEDIA_IMAGES, READ_MEDIA_VIDEO))
} else {
    requestPermissions.launch(arrayOf(READ_EXTERNAL_STORAGE))
}

Einige Apps benötigen keine Berechtigungen

Ab Android 10 (API-Level 29) benötigen Apps keine Speicherberechtigungen mehr, um dem freigegebenen Speicher Dateien hinzuzufügen. Das bedeutet, dass Apps Bilder zur Galerie hinzufügen, Videos aufnehmen und im freigegebenen Speicher speichern oder PDF-Rechnungen herunterladen können, ohne Speicherberechtigungen anfordern zu müssen. Wenn Ihre Anwendung nur Dateien zum freigegebenen Speicher hinzufügt und keine Bilder oder Videos abfragt, sollten Sie keine Speicherberechtigungen mehr anfordern und in Ihrer AndroidManifest.xml als maxSdkVersion API 28 festlegen:

<!-- No permission is needed to add files to shared storage on Android 10 (API level 29) or higher  -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="28" />

Medienauswahl bearbeiten

Mit der Funktion „Zugriff auf ausgewählte Fotos“ in Android 14 sollte Ihre App die neue Berechtigung READ_MEDIA_VISUAL_USER_SELECTED zur Steuerung der Neuauswahl von Medien haben und die Benutzeroberfläche Ihrer App aktualisieren, damit Nutzer Ihrer App Zugriff auf andere Bilder und Videos gewähren können. In der folgenden Abbildung sehen Sie ein Beispiel für das Anfordern von Berechtigungen und die nochmalige Auswahl von Medien:

Beim Öffnen des Auswahldialogfelds werden je nach angeforderten Berechtigungen Fotos, Videos oder beides angezeigt. Wenn Sie beispielsweise die Berechtigung READ_MEDIA_VIDEO ohne die Berechtigung READ_MEDIA_IMAGES anfordern, werden in der UI nur Videos angezeigt, die Nutzer auswählen können.

// Allow the user to select only videos
requestPermissions.launch(arrayOf(READ_MEDIA_VIDEO, READ_MEDIA_VISUAL_USER_SELECTED))

Du kannst prüfen, ob deine App vollständigen, teilweisen oder verweigerten Zugriff auf die Fotogalerie des Geräts hat, und die Benutzeroberfläche entsprechend aktualisieren. Fordern Sie diese Berechtigungen dann an, wenn die Anwendung Speicherzugriff benötigt, und nicht beim Start. Die Berechtigung kann zwischen den Callbacks für den App-Lebenszyklus onStart und onResume geändert werden, da der Nutzer den Zugriff in den Einstellungen ändern kann, ohne die App zu schließen.

if (
    Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU &&
    (
        ContextCompat.checkSelfPermission(context, READ_MEDIA_IMAGES) == PERMISSION_GRANTED ||
        ContextCompat.checkSelfPermission(context, READ_MEDIA_VIDEO) == PERMISSION_GRANTED
    )
) {
    // Full access on Android 13 (API level 33) or higher
} else if (
    Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE &&
    ContextCompat.checkSelfPermission(context, READ_MEDIA_VISUAL_USER_SELECTED) == PERMISSION_GRANTED
) {
    // Partial access on Android 14 (API level 34) or higher
}  else if (ContextCompat.checkSelfPermission(context, READ_EXTERNAL_STORAGE) == PERMISSION_GRANTED) {
    // Full access up to Android 12 (API level 32)
} else {
    // Access denied
}

Gerätebibliothek abfragen

Nachdem Sie überprüft haben, ob Sie Zugriff auf die richtigen Speicherberechtigungen haben, können Sie mit MediaStore interagieren, um die Gerätebibliothek abzufragen. Dies funktioniert auch, unabhängig davon, ob Sie nur teilweise oder uneingeschränkt Zugriff haben:

data class Media(
    val uri: Uri,
    val name: String,
    val size: Long,
    val mimeType: String,
)

// Run the querying logic in a coroutine outside of the main thread to keep the app responsive.
// Keep in mind that this code snippet is querying only images of the shared storage.
suspend fun getImages(contentResolver: ContentResolver): List<Media> = withContext(Dispatchers.IO) {
    val projection = arrayOf(
        Images.Media._ID,
        Images.Media.DISPLAY_NAME,
        Images.Media.SIZE,
        Images.Media.MIME_TYPE,
    )

    val collectionUri = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        // Query all the device storage volumes instead of the primary only
        Images.Media.getContentUri(MediaStore.VOLUME_EXTERNAL)
    } else {
        Images.Media.EXTERNAL_CONTENT_URI
    }

    val images = mutableListOf<Media>()

    contentResolver.query(
        collectionUri,
        projection,
        null,
        null,
        "${Images.Media.DATE_ADDED} DESC"
    )?.use { cursor ->
        val idColumn = cursor.getColumnIndexOrThrow(Images.Media._ID)
        val displayNameColumn = cursor.getColumnIndexOrThrow(Images.Media.DISPLAY_NAME)
        val sizeColumn = cursor.getColumnIndexOrThrow(Images.Media.SIZE)
        val mimeTypeColumn = cursor.getColumnIndexOrThrow(Images.Media.MIME_TYPE)

        while (cursor.moveToNext()) {
            val uri = ContentUris.withAppendedId(collectionUri, cursor.getLong(idColumn))
            val name = cursor.getString(displayNameColumn)
            val size = cursor.getLong(sizeColumn)
            val mimeType = cursor.getString(mimeTypeColumn)

            val image = Media(uri, name, size, mimeType)
            images.add(image)
        }
    }

    return@withContext images
}

Dieses Code-Snippet wurde vereinfacht, um die Interaktion mit MediaStore zu veranschaulichen. Verwenden Sie die Paginierung in einer produktionsreifen Anwendung mit einer Funktion wie der Paging-Bibliothek, um eine gute Leistung zu erzielen.

Letzte Auswahl abfragen

Apps mit Android 15 und höher und Android 14, die Google Play-Systemupdates unterstützen, können die letzte Auswahl von Bildern und Videos abfragen, die der Nutzer mit Teilzugriff erstellt hat. Dazu muss QUERY_ARG_LATEST_SELECTION_ONLY aktiviert werden:

if (getExtensionVersion(Build.VERSION_CODES.U) >= 12) {
    val queryArgs = bundleOf(
        QUERY_ARG_SQL_SORT_ORDER to "${Images.Media.DATE_ADDED} DESC"
        QUERY_ARG_LATEST_SELECTION_ONLY to true
    )

    contentResolver.query(collectionUri, projection, queryArgs, null)
}

Der Zugriff auf Fotos und Videos bleibt erhalten, wenn das Gerät aktualisiert wird

Wenn sich deine App auf einem Gerät befindet, das von einer früheren Android-Version auf Android 14 aktualisiert wird, behält das System vollständigen Zugriff auf die Fotos und Videos des Nutzers und gewährt deiner App automatisch einige Berechtigungen. Das genaue Verhalten hängt von den Berechtigungen ab, die Ihrer App vor dem Upgrade auf Android 14 gewährt werden.

Berechtigungen von Android 13

Betrachten Sie die folgende Situation:

1. Deine App ist auf einem Gerät mit Android 13 installiert.
2. Der Nutzer hat deiner App die Berechtigungen READ_MEDIA_IMAGES und READ_MEDIA_VIDEO gewährt.
3. Solange deine App noch installiert ist, wird das Gerät dann auf Android 14 aktualisiert.
4. Deine App ist ab Android 14 (API-Level 34) ausgerichtet.

In diesem Fall hat Ihre App weiterhin vollen Zugriff auf die Fotos und Videos des Nutzers. Das System behält auch die Ihrer App automatisch gewährten Berechtigungen READ_MEDIA_IMAGES und READ_MEDIA_VIDEO bei.

Berechtigungen von Android 12 und niedriger

Betrachten Sie die folgende Situation:

1. Deine App ist auf einem Gerät mit Android 13 installiert.
2. Der Nutzer hat deiner App die Berechtigung READ_EXTERNAL_STORAGE oder WRITE_EXTERNAL_STORAGE gewährt.
3. Solange deine App noch installiert ist, wird das Gerät dann auf Android 14 aktualisiert.
4. Deine App ist ab Android 14 (API-Level 34) ausgerichtet.

In diesem Fall hat Ihre App weiterhin vollen Zugriff auf die Fotos und Videos des Nutzers. Außerdem erteilt das System deiner App automatisch die Berechtigungen READ_MEDIA_IMAGES und READ_MEDIA_VIDEO.

Best Practices

Dieser Abschnitt enthält mehrere Best Practices für die Verwendung der Berechtigung READ_MEDIA_VISUAL_USER_SELECTED. Weitere Informationen finden Sie in unseren Best Practices für Berechtigungen.

Berechtigungsstatus nicht dauerhaft speichern

Speichern Sie den Berechtigungsstatus nicht dauerhaft, z. B. SharedPreferences oder DataStore. Der gespeicherte Status ist möglicherweise nicht mit dem tatsächlichen Status synchron. Der Berechtigungsstatus kann sich nach dem Zurücksetzen der Berechtigungen, dem Ruhezustand, einer vom Nutzer initiierten Änderung der App-Einstellungen oder wenn die App in den Hintergrund wechselt, ändern. Prüfen Sie stattdessen mit ContextCompat.checkSelfPermission(), ob Speicherberechtigungen vorhanden sind.

Kein uneingeschränkter Zugriff auf Fotos und Videos

Aufgrund der Änderungen in Android 14 hat deine App möglicherweise nur eingeschränkten Zugriff auf die Fotogalerie des Geräts. Wenn die Anwendung bei der Abfrage mit ContentResolver MediaStore-Daten im Cache speichert, ist der Cache möglicherweise nicht auf dem neuesten Stand.

• Fragen Sie MediaStore immer mit ContentResolver ab, anstatt sich auf einen gespeicherten Cache zu verlassen.
• Die Ergebnisse werden gespeichert, während die App im Vordergrund ausgeführt wird.
• Aktualisieren Sie die Ergebnisse, wenn Ihre App den Lebenszyklus der onResume-Anwendung durchläuft, da der Nutzer über die Berechtigungseinstellungen vom Vollzugriff zu Teilzugriff wechseln kann.

URI-Zugriff als temporär behandeln

Wenn der Nutzer im Dialogfeld für Systemberechtigungen Fotos und Videos auswählen auswählt, läuft der Zugriff Ihrer App auf die ausgewählten Fotos und Videos nach einer gewissen Zeit ab. Deine App sollte immer den Fall verarbeiten können, dass sie keinen Zugriff auf Uri haben, unabhängig von deren Befugnis.

Auswählbaren Medientyp nach Berechtigung filtern

Im Auswahldialogfeld wird der angeforderte Berechtigungstyp berücksichtigt:

• Wenn Sie nur READ_MEDIA_IMAGES anfordern, werden nur Bilder angezeigt, die ausgewählt werden können.
• Wenn Sie nur READ_MEDIA_VIDEO anfordern, ist nur das Video auswählbar.
• Wenn Sie sowohl READ_MEDIA_IMAGES als auch READ_MEDIA_VIDEO anfordern, ist die gesamte Fotogalerie auswählbar.

Je nach Anwendungsfall Ihrer Anwendung sollten Sie die richtigen Berechtigungen anfordern, um eine negative Nutzererfahrung zu vermeiden. Wenn für ein Feature nur die Auswahl von Videos erwartet wird, fordern Sie nur READ_MEDIA_VIDEO an.

Berechtigungen in einem Vorgang anfordern

Damit Nutzer nicht mehrere Dialogfelder zur Systemlaufzeit sehen, fordern Sie die Berechtigungen READ_MEDIA_VISUAL_USER_SELECTED, ACCESS_MEDIA_LOCATION und „Medien lesen“ (READ_MEDIA_IMAGES, READ_MEDIA_VIDEO oder beide) in einem einzigen Vorgang an.

Nutzern erlauben, ihre Auswahl zu verwalten

Wenn der Nutzer den Modus für teilweisen Zugriff auswählt, sollte Ihre App nicht davon ausgehen, dass die Fotogalerie des Geräts leer ist, und dem Nutzer die Möglichkeit bieten, weitere Dateien zu gewähren.

Der Nutzer kann über die Berechtigungseinstellungen vom Vollzugriff auf Teilzugriff umstellen, ohne Zugriff auf einige visuelle Mediendateien zu gewähren.

Kompatibilitätsmodus

Wenn Sie eine eigene Galerieauswahl mit Speicherberechtigungen verwenden, aber Ihre App nicht so angepasst haben, dass die neue Berechtigung READ_MEDIA_VISUAL_USER_SELECTED verwendet wird, führt das System Ihre App immer dann im Kompatibilitätsmodus aus, wenn der Nutzer Medien auswählen oder noch einmal auswählen muss.

Verhalten bei der ersten Medienauswahl

Wenn ein Nutzer bei der ersten Auswahl die Option „Fotos und Videos auswählen“ auswählt (siehe Abbildung 1), werden die Berechtigungen READ_MEDIA_IMAGES und READ_MEDIA_VIDEO während der App-Sitzung gewährt. Dadurch werden eine temporäre Berechtigung und vorübergehender Zugriff auf die vom Nutzer ausgewählten Fotos und Videos gewährt. Wenn Ihre App in den Hintergrund verschoben wird oder der Nutzer sie aktiv beendet, werden diese Berechtigungen vom System schließlich abgelehnt. Dieses Verhalten entspricht den anderen einmaligen Berechtigungen.

Verhalten bei der Medienauswahl

Wenn deine App später Zugriff auf zusätzliche Fotos und Videos benötigt, musst du die Berechtigung READ_MEDIA_IMAGES oder READ_MEDIA_VIDEO noch einmal manuell anfordern. Das System folgt dem gleichen Ablauf wie bei der ursprünglichen Berechtigungsanfrage und fordert die Nutzer auf, Fotos und Videos auszuwählen (siehe Abbildung 2).

Wenn Ihre Anwendung die Best Practices für Berechtigungen befolgt, sollte diese Änderung Ihre Anwendung nicht beeinträchtigen. Dies gilt insbesondere, wenn Ihre Anwendung nicht davon ausgeht, dass der URI-Zugriff beibehalten wird, den Systemberechtigungsstatus speichert oder die angezeigten Bilder nach Änderung der Berechtigung aktualisiert. Je nach Anwendungsfall Ihrer Anwendung ist dieses Verhalten jedoch möglicherweise nicht ideal. Wir empfehlen dir, die Bildauswahl zu implementieren oder die Galerieauswahl deiner App so anzupassen, dass dieses Verhalten direkt über die Berechtigung READ_MEDIA_VISUAL_USER_SELECTED gehandhabt wird.