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.

Falls 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 Ihre App im Kompatibilitätsmodus aus.

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. 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 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 der Galerie Bilder 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:

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 Benutzeroberfläche nur Videos angezeigt, aus denen Nutzer Dateien 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 an, wenn die App Speicherzugriff benötigt, und nicht beim Starten. 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 unter Android 15 und höher sowie unter Android 14 mit Unterstützung für Google Play-Systemupdates können die letzte Auswahl von Bildern und Videos abfragen, die der Nutzer mit teilweisem Zugriff getroffen hat. Dazu müssen Sie die QUERY_ARG_LATEST_SELECTION_ONLY aktivieren:

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 beim Geräteupgrade erhalten

Wenn Ihre App auf einem Gerät installiert ist, das von einer älteren Android-Version auf Android 14 umgestellt wird, behält das System den vollständigen Zugriff auf die Fotos und Videos des Nutzers und gewährt Ihrer 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 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 deiner App die Berechtigungen READ_MEDIA_IMAGES und 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

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_EXTERNAL_STORAGE oder WRITE_EXTERNAL_STORAGE erteilt.
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 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.

Nicht davon ausgehen, dass Sie vollen Zugriff auf Fotos und Videos haben

Aufgrund der Änderungen in Android 14 hat Ihre 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 im Arbeitsspeicher gespeichert, solange 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. Ihre App sollte immer den Fall behandeln, dass kein Zugriff auf Uri besteht, unabhängig von der Autorisierung.

Auswählbarer 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 Anwendung sollten Sie die richtigen Berechtigungen anfordern, um eine negative 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 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 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 vom Vollzugriff auf Teilzugriff 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 Neuauswahl von Medien

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 Sie die Best Practices für Berechtigungen einhalten, sollte diese Änderung keine Auswirkungen auf Ihre App haben. Das gilt insbesondere, wenn Ihre App nicht davon ausgeht, dass der URI-Zugriff beibehalten wird, den Status der Systemberechtigung speichert oder die angezeigten Bilder nach der Berechtigungsänderung aktualisiert. Je nach Anwendungsfall Ihrer App ist dieses Verhalten jedoch möglicherweise nicht ideal. Für eine optimale Nutzererfahrung empfehlen wir Ihnen, eine Fotoauswahl zu implementieren oder die Galerieauswahl Ihrer App so anzupassen, dass dieses Verhalten direkt über die Berechtigung READ_MEDIA_VISUAL_USER_SELECTED verwaltet wird.