写真と動画への部分的なアクセス権を付与する

Android 14 では、選択した写真へのアクセスが導入されています。これにより、ユーザーは特定の種類のすべてのメディアへのアクセス権をアプリに付与するのではなく、ライブラリ内の特定の画像や動画へのアクセス権をアプリに付与できます。

この変更は、アプリが Android 14（API レベル 34）以降をターゲットとしている場合にのみ有効になります。まだ写真選択ツールを使用していない場合は、アプリに実装することをおすすめします。これにより、画像と動画の選択に一貫したエクスペリエンスを提供し、ストレージ権限をリクエストしなくてもユーザーのプライバシーを強化できます。

ストレージの権限を使用して独自のギャラリー選択ツールを維持していて、実装を完全に制御する必要がある場合は、新しい READ_MEDIA_VISUAL_USER_SELECTED 権限を使用するように実装を調整してください。アプリが新しい権限を使用していない場合、システムはアプリを互換モードで実行します。

対象 SDK	READ_MEDIA_VISUAL_USER_SELECTED が宣言されました	選択したフォトへのアクセスが有効になっている	UX の動作
SDK 33	×	×	なし
	はい	はい	アプリによる操作
SDK 34	×	はい	システムによって制御される（互換性のある動作）
	はい	はい	アプリによる操作

独自のギャラリー選択ツールを作成または調整する

独自のギャラリー選択ツールを作成するには、広範な開発とメンテナンスが必要になります。また、アプリはストレージ権限をリクエストして、ユーザーの明示的な同意を得る必要があります。ユーザーはこれらのリクエストを拒否できます。また、アプリが Android 14 を搭載したデバイスで実行されており、Android 14（API レベル 34）以降をターゲットとしている場合は、選択したメディアへのアクセスを制限できます。次の図は、新しいオプションを使用して権限をリクエストし、メディアを選択する例を示しています。

このセクションでは、MediaStore を使用して独自のギャラリー選択ツールを作成する推奨アプローチについて説明します。アプリでギャラリー選択ツールをすでに維持していて、完全に制御する必要がある場合は、これらの例を使用して実装を調整できます。選択した写真へのアクセスを処理するように実装を更新しない場合、システムはアプリを互換モードで実行します。

権限をリクエストする

まず、OS のバージョンに応じて、Android マニフェストで適切なストレージ権限をリクエストします。

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

次に、OS のバージョンに応じて適切な実行時の権限をリクエストします。

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

権限が必要ないアプリもあります

Android 10（API レベル 29）以降、共有ストレージにファイルを追加するために、アプリでストレージの権限が不要になりました。つまり、アプリはストレージ権限をリクエストしなくても、ギャラリーに画像を追加したり、動画を録画して共有ストレージに保存したり、PDF 請求書をダウンロードしたりできます。アプリが共有ストレージにファイルを追加するだけで、画像や動画をクエリしない場合は、ストレージ権限のリクエストを停止し、AndroidManifest.xml に API 28 の maxSdkVersion を設定する必要があります。

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

メディアの再選択を処理する

Android 14 の選択した写真へのアクセス機能を使用するには、アプリで新しい READ_MEDIA_VISUAL_USER_SELECTED 権限を採用してメディアの再選択を制御し、アプリのインターフェースを更新して、ユーザーがアプリに別の画像と動画へのアクセス権を付与できるようにする必要があります。次の図は、権限をリクエストしてメディアを再選択する例を示しています。

選択ダイアログを開くと、リクエストされた権限に応じて、写真、動画、またはその両方が表示されます。たとえば、READ_MEDIA_IMAGES 権限なしで READ_MEDIA_VIDEO 権限をリクエストすると、ユーザーがファイルを選択できる UI に動画のみが表示されます。

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

アプリがデバイスのフォトライブラリに完全アクセス、部分アクセス、またはアクセス拒否されているかどうかを確認し、それに応じてインターフェースを更新できます。これらの権限は、アプリがストレージへのアクセスを必要とするときにリクエストしてください。起動時にリクエストしないでください。ユーザーはアプリを閉じることなく設定でアクセス権を変更できるため、権限の付与は onStart アプリ ライフサイクル コールバックと onResume アプリ ライフサイクル コールバックの間で変更される可能性があります。

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
}

デバイス ライブラリにクエリを実行する

適切なストレージ権限にアクセスできることを確認したら、MediaStore を操作してデバイス ライブラリをクエリできます（付与されるアクセス権が部分的でも完全でも、同じアプローチです）。

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
}

このコード スニペットは、MediaStore を操作する方法を示するために簡素化されています。製品版アプリでは、ページング ライブラリなどのページネーションを使用して、優れたパフォーマンスを確保します。

最後の選択内容をクエリする

Android 15 以降のアプリと、Google Play システム アップデートをサポートする Android 14 のアプリは、QUERY_ARG_LATEST_SELECTION_ONLY を有効にすることで、部分アクセスでユーザーが最後に選択した画像と動画をクエリできます。

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

デバイスのアップグレード後も、写真と動画へのアクセスは保持される

以前のバージョンの Android から Android 14 にアップグレードするデバイスにアプリがインストールされている場合、システムではそのユーザーの写真と動画への完全アクセス権は維持され、アプリに一部の権限が自動的に付与されます。デバイスが Android 14 にアップグレードされる前にアプリに付与されている権限のセットによって、具体的な動作は異なります。

Android 13 の権限

次のような状況を考えてみましょう。

1. アプリは Android 13 を搭載したデバイスにインストールされています。
2. ユーザーがアプリに READ_MEDIA_IMAGES 権限と READ_MEDIA_VIDEO 権限を付与しています。
3. アプリがインストールされている状態で、デバイスが Android 14 にアップグレードされます。
4. アプリのターゲットは Android 14（API レベル 34）以降になります。

この場合、アプリは引き続きそのユーザーの写真と動画への完全アクセス権を持ちます。また、アプリに付与されている READ_MEDIA_IMAGES 権限と READ_MEDIA_VIDEO 権限も自動的に保持されます。

Android 12 以前の権限

次のような状況を考えてみましょう。

1. アプリは Android 13 を搭載したデバイスにインストールされています。
2. ユーザーがアプリに READ_EXTERNAL_STORAGE 権限または WRITE_EXTERNAL_STORAGE 権限を付与しています。
3. アプリがインストールされている状態で、デバイスが Android 14 にアップグレードされます。
4. アプリのターゲットは Android 14（API レベル 34）以降になります。

この場合、アプリは引き続きそのユーザーの写真と動画への完全アクセス権を持ちます。また、READ_MEDIA_IMAGES 権限と READ_MEDIA_VIDEO 権限もアプリに自動的に付与されます。

おすすめの方法

このセクションでは、READ_MEDIA_VISUAL_USER_SELECTED 権限を使用する際のベスト プラクティスについて説明します。詳しくは、権限に関するベスト プラクティスをご覧ください。

権限の状態を永続的に保存しない

SharedPreferences や DataStore を含め、権限の状態を永続的に保存しないでください。保存された状態は、実際の状態と同期していない可能性があります。権限の状態は、権限のリセット後、アプリの休止状態の後、アプリの設定でユーザーが開始した変更の後、またはアプリがバックグラウンドになったときに変更される可能性があります。代わりに、ContextCompat.checkSelfPermission() を使用してストレージへの権限を確認してください。

写真と動画への完全アクセス権を持っていることを前提としない

Android 14 で導入された変更により、アプリはデバイスのフォト ライブラリに部分的にしかアクセスできない場合があります。ContentResolver を使用してクエリが行われたときにアプリが MediaStore データをキャッシュに保存していた場合、キャッシュが最新ではない可能性があります。

• 保存されたキャッシュに依存するのではなく、常に ContentResolver を使用して MediaStore をクエリしてください。
• アプリがフォアグラウンドにある間、結果をメモリに保持してください。
• アプリが onResume アプリのライフサイクルを経験したら、結果を更新します。ユーザーが権限の設定で完全アクセス権から部分アクセス権に切り替える可能性があるためです。

URI アクセスを一時的なものとして扱う

ユーザーがシステム権限ダイアログで [写真と動画を選択] を選択すると、選択した写真と動画へのアプリのアクセス権が最終的に期限切れになります。アプリは、認証局にかかわらず、Uri にアクセスできないケースを常に処理する必要があります。

選択可能なメディアタイプを権限でフィルタ

選択ダイアログは、リクエストされた権限の種類に応じて異なります。

• READ_MEDIA_IMAGES のみをリクエストすると、選択可能な画像のみが表示されます。
• READ_MEDIA_VIDEO のみをリクエストすると、選択可能な動画のみが表示されます。
• READ_MEDIA_IMAGES と READ_MEDIA_VIDEO の両方をリクエストすると、写真ライブラリ全体が選択可能になります。

アプリのユースケースに応じて、適切な権限をリクエストし、ユーザー エクスペリエンスの低下を回避する必要があります。動画のみが選択されることを想定している機能の場合は、READ_MEDIA_VIDEO のみをリクエストしてください。

1 回の操作で権限をリクエストする

ユーザーに複数のシステム ランタイム ダイアログ ボックスが表示されないようにするには、1 回のオペレーションで READ_MEDIA_VISUAL_USER_SELECTED、ACCESS_MEDIA_LOCATION、「読み取りメディア」権限（READ_MEDIA_IMAGES と READ_MEDIA_VIDEO のいずれかまたは両方）をリクエストします。

ユーザーが選択内容を管理できるようにする

ユーザーが部分アクセス モードを選択した場合、アプリはデバイスの写真ライブラリが空であると想定しないで、ユーザーがさらにファイルを許可できるようにする必要があります。

ユーザーは、一部のビジュアル メディア ファイルへのアクセス権を付与せずに、権限設定で完全アクセス権から部分アクセス権に切り替える場合があります。

互換性モード

ストレージ権限を使用して独自のギャラリー選択ツールを維持しているが、新しい READ_MEDIA_VISUAL_USER_SELECTED 権限を使用するようにアプリを適応させていない場合、ユーザーがメディアを選択または再選択する必要があるたびに、アプリは互換モードで実行されます。

最初のメディア選択時の動作

最初の選択時にユーザーが [写真と動画を選択] を選択した場合（図 1 を参照）、READ_MEDIA_IMAGES 権限と READ_MEDIA_VIDEO 権限がアプリ セッション中に付与され、ユーザーが選択した写真と動画に対する一時的な権限およびアクセス権が提供されます。アプリがバックグラウンドに移動した場合や、ユーザーが積極的にアプリを強制終了した場合、システムは最終的にこれらの権限を拒否します。この動作は、他の 1 回だけのアクセス許可と同様です。

メディアの再選択時の動作

後からアプリで追加の写真と動画にアクセスする必要が生じた場合は、READ_MEDIA_IMAGES 権限または READ_MEDIA_VIDEO 権限をもう一度手動でリクエストする必要があります。システムは最初の権限リクエストと同じフローに従い、ユーザーは写真と動画を選択するよう求められます（図 2 を参照）。

アプリが権限に関するベスト プラクティスに従っている場合、この変更によってアプリが機能しなくなることはありません。これは特に、アプリが URI アクセスが保持されることを想定していない場合、システム権限の状態を保存すること、権限の変更後に表示される画像のセットを更新することを想定していない場合に当てはまります。ただし、アプリのユースケースによっては、この動作が望ましくない場合があります。ユーザーに最適なエクスペリエンスを提供するには、写真選択ツールを実装するか、アプリのギャラリー選択ツールを適応して、READ_MEDIA_VISUAL_USER_SELECTED 権限を使用してこの動作を直接処理することをおすすめします。