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

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 を使用して独自のギャラリー選択ツールを作成する場合のおすすめの方法について説明します。すでにアプリのギャラリー選択ツールを管理しており、完全に制御する必要がある場合は、以下の例を使用して実装を調整できます。選択した写真へのアクセスを処理するように実装を更新しない場合、システムはアプリを互換モードで実行します。

権限をリクエストする

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

<!-- 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 の操作方法を示すために簡略化されています。本番環境対応のアプリでは、ページング ライブラリなどでページネーションを使用して、優れたパフォーマンスを確保します。

最後の選択をクエリする

Google Play システム アップデートをサポートする Android 15 以降と 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 権限を使用してこの動作を直接処理することをおすすめします。