Mastering Android Scoped Storage: Migration Strategies and Compatibility Modes

Background

In September 2019 Google released Android 10, which introduced Scoped Storage to improve user privacy and limit redundant files. Scoped Storage redesigns external storage access based on three principles: clearer file ownership, app data protection, and user data protection.

New Scoped Storage Features

External storage is divided into two parts:

App private directory : Stores app‑specific data (e.g., /Android/data/<em>packageName</em> on external storage or /data/data/<em>packageName</em> on internal storage).

Shared directory : Stores media, documents, and other files accessible by other apps (e.g., DCIM, Pictures, Music, Downloads, etc.).

Access rules:

App private files can be accessed via normal file paths without extra permissions.

Shared files must be accessed through the MediaStore API or the Storage Access Framework (SAF). MediaStore allows creating and reading media files without storage permission, but accessing non‑media files (PDF, DOC, TXT) requires SAF.

Compatibility Mode

Android 10 provides a legacy compatibility mode to ease migration. Apps targeting API level ≤28 run unchanged, while apps targeting API level ≥29 can enable android:requestLegacyExternalStorage="true" in the manifest to retain full‑path access. This mode will be removed in Android 11, so migration must be completed before then.

<manifest ...>
  <!-- This attribute is "false" by default on apps targeting Android 10 or higher. -->
  <application android:requestLegacyExternalStorage="true" ...>
    ...
  </application>
</manifest>

Use Environment.isExternalStorageLegacy() at runtime to check whether the app is running in legacy mode (returns true) or Scoped Storage mode (returns false).

Migration Plan

1. File Migration

Move files from shared directories to either the app private directory or the appropriate MediaStore collection:

Files only used by the app and deletable after uninstall should be migrated to the private directory and can continue to be accessed via file paths.

Files that need to remain accessible to other apps must be moved to the appropriate MediaStore collection (Images, Videos, Audio, Downloads).

2. Access Compatibility

Shared‑directory files can no longer be accessed via raw file paths; they must be accessed using MediaStore or SAF.

MediaStore API Overview

MediaStore automatically scans external storage and indexes files into collections such as Images, Video, Audio, and Downloads. Creating files is limited to designated sub‑folders; attempts to create files elsewhere throw IllegalArgumentException. The MediaStore.Downloads.EXTERNAL_CONTENT_URI API (added in Android 10) enables creation and access of non‑media files.

Storage Access Framework (SAF)

Introduced in Android 4.4, SAF lets apps obtain file handles through system pickers without requesting storage permissions. It involves three components:

Document provider : Supplies files (local or cloud) via a hierarchical model.

Client app : Calls intents such as ACTION_CREATE_DOCUMENT, ACTION_OPEN_DOCUMENT, or ACTION_OPEN_DOCUMENT_TREE to let the user select files.

Picker UI : System UI that returns a Uri to the selected document.

Sharing Scenarios

When an app shares a file:

Using FileProvider, the app can grant read access via a content Uri without requiring storage permission.

In Scoped Storage, sharing via a file‑scheme Uri or a MediaStore Uri may fail for non‑media files; developers should use FileProvider or SAF instead.

Case Study: Baidu App Scoped Storage Adaptation

The Baidu app migrated over twenty business modules across three version iterations, solving about 90% of scenarios. Migration steps included:

Identifying legacy files accessed via raw paths.

Moving app‑only deletable files to the private directory.

Using MediaStore or SAF for files that must remain shared.

Business teams chose the appropriate migration strategy based on whether files needed to stay accessible after app uninstall.

References

Official Android documentation and related videos provide further details on Scoped Storage, MediaStore, and SAF.