Teilweisen Zugriff 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 zu gewähren.

Diese Änderung ist nur aktiviert, wenn Ihre App auf Android 14 (API-Level 34) oder höher ausgerichtet ist. Wenn Sie die Bildauswahl noch nicht verwenden, empfehlen wir Ihnen, sie in Ihrer App zu implementieren. So können Sie Bilder und Videos einheitlich auswählen und gleichzeitig den Datenschutz für Nutzer verbessern, ohne Speicherberechtigungen anfordern zu müssen.

Wenn Sie Ihre eigene Galerieauswahl mit Speicherberechtigungen verwalten und die vollständige Kontrolle über Ihre Implementierung behalten möchten, passen Sie Ihre 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 Ihre App im Kompatibilitätsmodus aus.

Ziel-SDK	READ_MEDIA_VISUAL_USER_SELECTED erklärt	Ausgewählter Zugriff auf Fotos aktiviert	UX-Verhalten
SDK 33	Nein	Nein	–
	Ja	Ja	Über die App steuerbar
SDK 34	Nein	Ja	Vom System gesteuert (Kompatibilitätsverhalten)
	Ja	Ja	Über die App steuerbar

Eigene Galerieauswahl erstellen oder anpassen

Das Erstellen einer eigenen Galerieauswahl erfordert umfangreiche Entwicklungs- und Wartungsarbeiten. Außerdem muss Ihre App Speicherberechtigungen anfordern, um die ausdrückliche Einwilligung der Nutzer einzuholen. Nutzer können diese Anfragen ablehnen oder, wenn Ihre App auf einem Gerät mit Android 14 ausgeführt wird und auf Android 14 (API-Level 34) oder höher ausgerichtet ist, den Zugriff auf ausgewählte Medien einschränken. Das folgende Bild zeigt ein Beispiel für die Anforderung von Berechtigungen und die Auswahl von Medien mit den neuen Optionen.

In diesem Abschnitt wird der empfohlene Ansatz zum Erstellen einer eigenen Galerieauswahl mit MediaStore veranschaulicht. Wenn Sie bereits eine Galerieauswahl für Ihre App haben und die volle Kontrolle behalten möchten, können Sie diese Beispiele verwenden, um Ihre Implementierung anzupassen. Wenn Sie Ihre Implementierung nicht so aktualisieren, dass der Zugriff auf ausgewählte Fotos verarbeitet wird, führt das System Ihre App im Kompatibilitätsmodus aus.

Berechtigungen anfordern

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

<!-- 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" />

Fordere dann die richtigen Laufzeitberechtigungen an, je nach Betriebssystemversion:

// 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))
}

Für einige Apps sind keine Berechtigungen erforderlich

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 neu verarbeiten

Mit der Funktion „Zugriff auf ausgewählte Fotos“ in Android 14 sollte Ihre App die neue Berechtigung READ_MEDIA_VISUAL_USER_SELECTED verwenden, um die erneute Auswahl von Medien zu steuern. Außerdem sollten Sie die Benutzeroberfläche Ihrer App so aktualisieren, dass Nutzer Ihrer App Zugriff auf eine andere Gruppe von Bildern und Videos gewähren können. Das folgende Bild zeigt ein Beispiel für das Anfordern von Berechtigungen und das erneute Auswählen von Medien:

Wenn Sie das Auswahldialogfeld öffnen, werden je nach den 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))

Sie können prüfen, ob Ihre App vollen, teilweisen oder keinen 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. Beachten Sie, dass die Berechtigung zwischen den onStart- und onResume-App-Lebenszyklusereignissen geändert werden kann, da der Nutzer den Zugriff in den Einstellungen ändern kann, ohne Ihre 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, dass Sie Zugriff auf die richtigen Speicherberechtigungen haben, können Sie mit MediaStore die Gerätebibliothek abfragen. Dabei spielt es keine Rolle, ob der gewährte Zugriff teilweise oder vollständig ist:

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 ist vereinfacht, um die Interaktion mit MediaStore zu veranschaulichen. Verwenden Sie in einer produktionsfertigen App die Paginierung mithilfe der Paginierungsbibliothek, 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 des Geräts auf Android 14 gewährt wurden.

Berechtigungen unter Android 13

Stellen Sie sich folgende Situation vor:

1. Ihre App ist auf einem Gerät mit Android 13 installiert.
2. Der Nutzer hat Ihrer App die Berechtigung READ_MEDIA_IMAGES und die Berechtigung READ_MEDIA_VIDEO gewährt.
3. Das Gerät wird dann auf Android 14 aktualisiert, während Ihre App noch installiert ist.
4. Ihre App ist jetzt auf Android 14 (API-Level 34) oder höher ausgerichtet.

In diesem Fall hat Ihre App weiterhin vollen Zugriff auf die Fotos und Videos des Nutzers. Außerdem werden die READ_MEDIA_IMAGES- und READ_MEDIA_VIDEO-Berechtigungen, die Ihrer App automatisch gewährt wurden, beibehalten.

Berechtigungen von Android 12 und niedriger

Betrachten Sie die folgende Situation:

1. Ihre App ist auf einem Gerät mit Android 13 installiert.
2. Der Nutzer hat Ihrer App die Berechtigung READ_EXTERNAL_STORAGE oder WRITE_EXTERNAL_STORAGE erteilt.
3. Während die App noch installiert ist, wird das Gerät dann auf Android 14 aktualisiert.
4. Ihre App ist jetzt auf Android 14 (API-Level 34) oder höher ausgerichtet.

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

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.

Speichern Sie den Berechtigungsstatus nicht dauerhaft.

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

Kein uneingeschränkter Zugriff auf Fotos und Videos

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

• Führe immer Abfragen für MediaStore mit ContentResolver aus, anstatt auf einen gespeicherten Cache zu vertrauen.
• Die Ergebnisse werden gespeichert, während die App im Vordergrund ausgeführt wird.
• Aktualisieren Sie die Ergebnisse, wenn Ihre App den onResume App-Lebenszyklus durchläuft, da der Nutzer über die Berechtigungseinstellungen vom vollständigen Zugriff zum teilweisen Zugriff wechseln kann.

URI-Zugriff als vorübergehend behandeln

Wenn der Nutzer im Dialogfeld für die Systemberechtigungen Fotos und Videos auswählen auswählt, läuft der Zugriff Ihrer App auf die ausgewählten Fotos und Videos irgendwann 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

Das Auswahldialogfeld ist vom angeforderten Berechtigungstyp abhängig:

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

Je nach Anwendungsfall Ihrer App sollten Sie die richtigen Berechtigungen anfordern, um eine schlechte Nutzererfahrung zu vermeiden. Wenn für eine Funktion nur Videos ausgewählt werden sollen, fordern Sie nur READ_MEDIA_VIDEO an.

Berechtigungen in einem einzigen Vorgang anfordern

Damit Nutzer nicht mehrere Systemdialogfelder zur Laufzeit 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 einer einzigen Operation an.

Nutzern erlauben, ihre Auswahl zu verwalten

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

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

Kompatibilitätsmodus

Wenn Sie Ihre eigene Galerieauswahl mit Speicherberechtigungen verwalten, Ihre App aber nicht an die neue Berechtigung READ_MEDIA_VISUAL_USER_SELECTED angepasst haben, führt das System Ihre App 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 „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 erteilt. Dadurch wird eine vorübergehende Berechtigung erteilt und der vorübergehende Zugriff auf die vom Nutzer ausgewählten Fotos und Videos ermöglicht. Wenn Ihre App in den Hintergrund verschoben wird oder der Nutzer sie aktiv beendet, werden diese Berechtigungen vom System schließlich widerrufen. Das Verhalten entspricht dem anderer einmaliger Berechtigungen.

Verhalten bei der Medienauswahl

Wenn Ihre App später auf weitere Fotos und Videos zugreifen muss, müssen Sie die Berechtigung READ_MEDIA_IMAGES oder READ_MEDIA_VIDEO noch einmal manuell anfordern. Das System folgt demselben 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 App 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.