Fotoğraflara ve videolara kısmi erişim izni verme

Android 14'te, kullanıcıların uygulamalara izin vermelerine olanak tanıyan Seçili Fotoğraflar Erişimi'ni kullanıma sunduk. kendi kitaplıklarındaki belirli resimlere ve videolara erişebilirler. belirli bir türdeki tüm medyalara erişim.

Bu değişiklik yalnızca uygulamanız Android 14 (API düzeyi 34) veya daha yüksek olabilir. Henüz fotoğraf seçiciyi kullanmıyorsanız fotoğraf seçiciyi uygulamanızda tutarlı bir deneyim sunmak için kullanın Ayrıca, depolama alanı istemeden kullanıcı gizliliğini de artırır. izin verir.

Depolama alanı izinlerini kullanarak kendi galeri seçiciyi kullanıyorsanız ve Uygulamanız üzerinde tam kontrol sahibi olmak, uygulamanızı uyarlama yeni READ_MEDIA_VISUAL_USER_SELECTED iznini kullanın. Uygulamanız yeni izni kullanmazsa sistem, uygulamanızı uyumluluk mod'u seçin.

Kendi galeri seçiciyi oluşturun veya uyarlayın

Kendi galeri seçicinizi oluşturmak için kapsamlı geliştirme ve bakım gerekir. Ayrıca uygulamanızın açık kullanıcı izni almak için depolama izni istemesi gerekir. Kullanıcılar bu istekleri reddedebilir. Ayrıca, uygulamanız Android 14 ve uygulamanız Android 14 (API düzeyi 34) veya sonraki sürümleri hedefliyorsa sınır seçilen medyaya erişim. Aşağıdaki resimde, yeni seçenekleri kullanarak medya öğelerini seçmesini sağlayabilirsiniz.

Bu bölümde, kendi galerinizi oluşturmak için önerilen yaklaşım gösterilmektedir MediaStore kullanarak seçiciyi tıklayın. Uygulamanız için zaten bir galeri seçici kullanıyorsanız ve tam kontrol sahibi olmanız gerekiyorsa, bu örnekleri kullanarak hakkında bilgi edindiniz. Uygulamanızı, seçilen öğeleri işleyecek şekilde güncellemezseniz Fotoğraflar Erişimi, sistem uygulamanızı uyumluluk modunda çalıştırır.

İzin iste

Öncelikle, Android manifest'inde doğru depolama izinlerini isteyin, OS sürümüne bağlı olarak:

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

Ardından, işletim sistemi sürümüne bağlı olarak doğru çalışma zamanı izinlerini isteyin:

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

Bazı uygulamalar izin gerektirmez

Android 10 (API düzeyi 29) sürümünden itibaren, uygulamaların veri eklemek için depolama izinlerine ihtiyacı yoktur. dosyaları paylaşılan depolama alanına aktarın. Bu, uygulamaların galeriye resim ekleyebilecekleri, video kaydedip paylaşılan depolama alanına kaydedebilir veya veya depolama alanı izni isteyebilir. Uygulamanız yalnızca paylaşılanlara dosya ekliyorsa ve resimler ya da videolar sorgulanmıyorsa depolama alanı izinlerini ve AndroidManifest.xml içinde API 28 maxSdkVersion değerini ayarlayın:

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

Medya yeniden seçimini yönetme

Android 14'te Seçili Fotoğraflar Erişimi özelliği sayesinde uygulamanız medyayı kontrol etmek için yeni READ_MEDIA_VISUAL_USER_SELECTED izni yeniden seçim yapabilir ve kullanıcıların uygulamanıza erişim izni verebilmesi için uygulamanızın arayüzünü güncelleyebilirsiniz farklı bir resim ve video grubuna ekleyebilirsiniz. Aşağıdaki resimde izin istiyor ve medyayı yeniden seçin:

Seçim iletişim kutusu açıldığında, bağlı olarak fotoğraflar, videolar veya her ikisi de gösterilir seçeneğini tıklayın. Örneğin, bir web sitesine READ_MEDIA_IMAGES izni olmadan READ_MEDIA_VIDEO izni, yalnızca videolar, kullanıcı arayüzünde kullanıcıların dosyaları seçmesi için görünür.

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

Uygulamanızın cihazın ve arayüzünüzü uygun şekilde güncelleyin. Bu izinleri iste uygulama başlangıçta değil, depolama alanına erişmelidir. Lütfen izin verme işlemi, onStart ve onResume uygulaması arasında değiştirilebilir kullanıcı yaşam döngüsü geri çağırmasını kullanın. Çünkü kullanıcı en iyi uygulamaları paylaşacağız.

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
}

Cihaz kitaplığını sorgulama

Doğru depolama izinlerine sahip olduğunuzu doğruladıktan sonra cihaz kitaplığını sorgulamak için MediaStore ile etkileşimde bulunun (aynı yaklaşım işe yarar) verilen erişim izninin kısmi mi yoksa tam mı olduğunu belirtin):

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
}

Bu kod snippet'i, MediaStore ile nasıl etkileşim kurulacağını göstermek amacıyla basitleştirilmiştir. Üretime hazır bir uygulamada, sayfalama kitaplığını kullanabilirsiniz.

Son seçimi sorgula

Android 15 ve sonraki sürümlerdeki ve Android 14'teki uygulamalar için Google Play sistem güncellemeleri desteği Kısmi erişimde kullanıcının yaptığı son resim ve video seçimini sorgula QUERY_ARG_LATEST_SELECTION_ONLY etkinleştirerek:

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

Cihaz yeni sürüme geçirildiğinde fotoğraf ve video erişimi korunur

Uygulamanızın, önceki bir Android sürümünden yükseltme yapılan bir cihazda olduğu durumlarda Android 14 sürümüne geçerseniz sistem, kullanıcının fotoğraflarına ve ve uygulamanıza otomatik olarak bazı izinler verir. Tam davranışı, önceden uygulamanıza verilen izin grubuna bağlıdır Cihaz Android 14'e geçer.

Android 13'teki izinler

Aşağıdaki durumu göz önünde bulundurun:

1. Uygulamanız Android 13 çalıştıran bir cihaza yüklendi.
2. Kullanıcı READ_MEDIA_IMAGES iznini verdi ve Uygulamanız için READ_MEDIA_VIDEO izni.
3. Ardından cihaz, uygulamanız yüklüyken Android 14'e geçer.
4. Uygulamanız Android 14 (API düzeyi 34) veya sonraki sürümleri hedeflemeye başladı.

Bu durumda uygulamanız, kullanıcının fotoğraf ve videolarına tam erişime sahip olmaya devam eder. Sistem, READ_MEDIA_IMAGES ve READ_MEDIA_VIDEO izinlerini de korur otomatik olarak verilir.

Android 12 ve önceki sürümlerdeki izinler

Aşağıdaki durumu göz önünde bulundurun:

1. Uygulamanız Android 13 çalıştıran bir cihaza yüklendi.
2. Kullanıcı READ_EXTERNAL_STORAGE iznini veya Uygulamanız için WRITE_EXTERNAL_STORAGE izni.
3. Ardından cihaz, uygulamanız yüklüyken Android 14'e geçer.
4. Uygulamanız Android 14 (API düzeyi 34) veya sonraki sürümleri hedeflemeye başladı.

Bu durumda uygulamanız, kullanıcının fotoğraf ve videolarına tam erişime sahip olmaya devam eder. Sistem ayrıca READ_MEDIA_IMAGES izni verir ve Uygulamanız için otomatik olarak READ_MEDIA_VIDEO izni.

En iyi uygulamalar

Bu bölümde, READ_MEDIA_VISUAL_USER_SELECTED izni. Daha fazla bilgi için bkz. izinlerle ilgili en iyi uygulamalarımıza göz atın.

İzin durumunu kalıcı olarak depolama

İzin durumunu, şunlar da dahil olmak üzere kalıcı bir şekilde depolamayın: SharedPreferences veya DataStore. Depolanmış durum, durumunu gösterir. İzin durumu, izin sıfırlandıktan sonra değişebilir. uygulama hazırda bekleme, uygulamanızın ayarlarında kullanıcı tarafından başlatılan bir değişiklik veya arka plana geçer. Bunun yerine, depolama alanı izinlerini kontrol etmek için ContextCompat.checkSelfPermission().

Fotoğraflara ve videolara tam erişim sahibi olduğunuzu varsaymayın

Android 14'te yapılan değişikliklere göre uygulamanızda yalnızca kısmi cihazın fotoğraf kitaplığına erişim. Uygulama MediaStore verilerini önbelleğe alıp almadığı ContentResolver kullanılarak sorgulandığında önbellek güncel olmayabilir.

• Bir MediaStore sorgusuna güvenmek yerine her zaman ContentResolver kullanarak sorgu oluşturun saklanıyor.
• Uygulamanız ön plandayken sonuçları bellekte tutun.
• Uygulamanız onResume uygulamasının yaşam döngüsünü tamamladığında sonuçları yenileyin tam erişimden kısmi erişime geçebileceğinden izin ayarlarına gidin.

URI erişimini geçici olarak kabul et

Kullanıcı, sistem izinlerinde Fotoğraf ve videoları seçin seçeneğini belirlerse iletişim kutusunda, uygulamanızın seçilen fotoğraflara ve videolara erişimi bir süre sonra sona erer. Uygulamanız, hiçbir Uri cihazına erişememe durumlarında her zaman ele almalıdır: söz konusu olur.

Seçilebilir medya türünü izne göre filtrele

Seçim iletişim kutusu, istenen izin türüne karşı hassas:

• Yalnızca READ_MEDIA_IMAGES istendiğinde sadece seçilebilecek resimler gösterilir.
• Yalnızca READ_MEDIA_VIDEO istendiğinde, seçilebilecek yalnızca video gösterilir.
• Hem READ_MEDIA_IMAGES hem de READ_MEDIA_VIDEO istendiğinde tümünü gösterir seçilebilir olmasını sağlayın.

Uygulamanızın kullanım alanlarına bağlı olarak, doğru kötü bir kullanıcı deneyimini önlemek için gerekli izinler bulunmalıdır. Bir özellik video seçilecek. Yalnızca READ_MEDIA_VIDEO video isteğinde bulunduğunuzdan emin olun.

Tek bir işlemle izin isteme

Kullanıcıların birden fazla sistem çalışma zamanı iletişim kutusu görmesini engellemek için READ_MEDIA_VISUAL_USER_SELECTED, ACCESS_MEDIA_LOCATION ve "medya okuma" izinlerini (READ_MEDIA_IMAGES, READ_MEDIA_VIDEO veya her ikisi) tek seferde işlemidir.

Kullanıcıların, seçimlerini yönetmesine izin ver

Kullanıcı kısmi erişim modunu seçtiğinde uygulamanız, bu cihazın fotoğraf kitaplığı boş. Kullanıcının daha fazla dosyası olarak da kaydedebilir.

Kullanıcı, bazı görsel medya dosyalarına erişim izni vermeden izin ayarlarını değiştirebilirsiniz.

Uyumluluk modu

Depolama alanı izinlerini kullanarak kendi galeri seçiciyi kullanıyorsanız ancak bunu yapmadıysanız uygulamanızı yeni READ_MEDIA_VISUAL_USER_SELECTED kullanacak şekilde uyarladı kullanıcı izin verdiğinde sistem uygulamanızı uyumluluk modunda çalıştırır. medyayı seçmesi ya da yeniden seçmesi gerekiyor.

İlk medya seçimi sırasındaki davranış

İlk seçim sırasında kullanıcı "Fotoğraf ve video seçin" seçeneğini belirlerse (bkz. şekil 1), READ_MEDIA_IMAGES ve READ_MEDIA_VIDEO izinleri uygulama oturumu sırasında verilir, geçici bir izin kullanıcı tarafından seçilen fotoğraflara ve videolara geçici erişim. Uygulamanız veya kullanıcı uygulamanızı aktif şekilde kapattığında sistem bunun bu izinleri reddeder. Bu davranış diğer tek seferlik izinlerle aynıdır.

Medya yeniden seçimi sırasında davranış

Uygulamanızın daha sonra başka fotoğraflara ve videolara erişmesi gerekirse READ_MEDIA_IMAGES iznini veya READ_MEDIA_VIDEO iznini tekrar kullandı. Sistem, ile aynı akışı izler. kullanıcılardan fotoğraf ve video seçmelerini isteyen ilk izin isteği (bkz. şekil 2) gösterilir.

Uygulamanız izinlerle ilgili en iyi uygulamaları kullanıyorsa bu değişiklik uygulamanızı bozar. Bu, özellikle uygulamanız URI'nin bu olduğunu varsaymıyorsa geçerlidir erişim korunur, sistem izin durumunu depolar veya görüntüler. Ancak bu davranış en iyi seçenek olabilir. En iyi deneyimi sunmaya yardımcı olmak için fotoğraf seçiciyi uygulamanızı veya uygulamanın galeri seçiciyi kullanarak bu davranışı doğrudan READ_MEDIA_VISUAL_USER_SELECTED izni.