איך נותנים גישה חלקית לתמונות ולסרטונים

ב-Android 14 כולל התכונה 'גישה לתמונות שנבחרו', שמאפשרת למשתמשים להעניק אפליקציות גישה לתמונות ולסרטונים ספציפיים בספרייה שלהם, במקום להעניק גישה גישה לכל המדיה מסוג נתון.

השינוי הזה מופעל רק אם האפליקציה מטרגטת את Android 14 (רמת API 34) או גבוהה יותר. אם אתם עדיין לא משתמשים בכלי לבחירת תמונות, מומלץ להטמיע אותו האפליקציה שלך כדי לספק חוויה עקבית בבחירת תמונות וסרטונים שמשפר גם את פרטיות המשתמשים בלי לבקש נפח אחסון נוסף הרשאות.

אם יש לכם כלי לבחירת גלריה משלכם שיש לו הרשאות אחסון ואתם צריכים לשמור על שליטה מלאה בהטמעה, להתאים את ההטמעה כדי להשתמש בהרשאה החדשה READ_MEDIA_VISUAL_USER_SELECTED. אם האפליקציה לא משתמשת בהרשאה החדשה, המערכת מפעילה את האפליקציה בתאימות .

יצירה או התאמה של בורר גלריה משלכם

כדי ליצור בורר גלריה משלכם, נדרשים פיתוח ותחזוקה מקיפים, והאפליקציה שלך צריכה לבקש הרשאות אחסון כדי לקבל הסכמה מפורשת מהמשתמשים. המשתמשים יכולים לדחות את הבקשות האלה. לחלופין, אם האפליקציה פועלת במכשיר עם Android 14 והאפליקציה שלך מטרגטת את Android 14 (רמת API 34) ואילך, מגבלה גישה למדיה שנבחרה. בתמונה הבאה מוצגת דוגמה לבקשה ובחירת מדיה באמצעות האפשרויות החדשות.

בקטע הזה נדגים את הגישה המומלצת ליצירת גלריה משלכם. באמצעות MediaStore. אם כבר יש לכם כלי לבחירת גלריה לאפליקציה שלכם וכדי לשמור על שליטה מלאה, אפשר להשתמש בדוגמאות האלה כדי להתאים את יישום בפועל. אם לא מעדכנים את ההטמעה כדי לטפל בפריטים שנבחרו ב-Photos Access, המערכת מפעילה את האפליקציה במצב תאימות.

בקשת הרשאות

קודם כול, מבקשים את הרשאות האחסון המתאימות במניפסט של 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" />

לאחר מכן, מבקשים את ההרשאות המתאימות בתחילת ההפעלה, גם בהתאם לגרסת מערכת ההפעלה:

// 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 ללא שצריך לבקש הרשאות אחסון. אם האפליקציה מוסיפה רק קבצים ששותפו אחסון ולא שולח שאילתות על תמונות או סרטונים, עליך להפסיק לבקש נפח אחסון ולהגדיר maxSdkVersion של API 28 בAndroidManifest.xml:

<!-- 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_VIDEO ללא ההרשאה READ_MEDIA_IMAGES, רק סרטונים יופיעו בממשק המשתמש כדי שהמשתמשים יוכלו לבחור קבצים.

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

אפשר לבדוק אם לאפליקציה יש גישה מלאה, חלקית או נדחתה ספריית התמונות ולעדכן את הממשק בהתאם. בקשת ההרשאות האלה כשהאפליקציה צריכה גישה לאחסון, במקום בזמן ההפעלה. חשוב לזכור אפשר לשנות את הרשאת ההרשאה בין האפליקציה onStart והאפליקציה onResume קריאות חוזרות (callback) במחזור החיים, כיוון שהמשתמש יכול לשנות את הגישה בהגדרות כשסוגרים את האפליקציה.

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 ואילך וב-Android 14 עם תמיכה בעדכוני מערכת של Google Play לשלוח שאילתות על הבחירה האחרונה של התמונות והסרטונים שהמשתמש יצר בגישה חלקית באמצעות הפעלת 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, יכול להיות שבאפליקציה שלך יש רק חלק לגשת לספריית התמונות של המכשיר. אם האפליקציה שומרת במטמון נתוני MediaStore כשנשלחת שאילתה באמצעות ContentResolver, יכול להיות שהמטמון לא עדכני.

• תמיד צריך להריץ שאילתה על MediaStore באמצעות ContentResolver, במקום להסתמך על שנשמר במטמון.
• התוצאות יישמרו בזיכרון בזמן שהאפליקציה פועלת בחזית.
• רענון התוצאות כשהאפליקציה עוברת את מחזור החיים של onResume מאחר שהמשתמש עשוי לעבור מגישה מלאה לגישה חלקית דרך הגדרות ההרשאות.

התייחסות לגישה ל-URI כזמנית

אם המשתמש בוחר באפשרות בחירת תמונות וסרטונים בהרשאות המערכת הגישה של האפליקציה לתמונות ולסרטונים שנבחרו תפוג בסופו של דבר. האפליקציה צריכה תמיד לטפל במקרה של אין גישה ל-Uri כלשהו, לא הם חשובים בסמכות שלהם.

סינון סוג המדיה שניתן לבחור לפי הרשאה

תיבת הדו-שיח של הבחירה רגישה לסוג ההרשאה המבוקש:

• אם שולחים בקשה רק ל-READ_MEDIA_IMAGES, מוצגות רק תמונות שניתן לבחור.
• בבקשה READ_MEDIA_VIDEO בלבד יוצג רק סרטון שניתן לבחור.
• בקשה להצגת READ_MEDIA_IMAGES וגם READ_MEDIA_VIDEO תציג את כל התוכן ספריית התמונות שאפשר לבחור בה.

על סמך התרחישים לדוגמה של האפליקציה שלך, עליך לבקש את הרשאות כדי למנוע חוויית משתמש גרועה. אם התכונה מצפה רק לתכונה סרטונים שייבחרו, עליך להקפיד לבקש רק READ_MEDIA_VIDEO.

בקשת הרשאות בפעולה אחת

כדי למנוע ממשתמשים לראות תיבות דו-שיח מרובות של סביבת זמן ריצה במערכת, צריך לבקש 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 במהלך הסשן של האפליקציה, מתן הרשאה זמנית גישה זמנית לתמונות ולסרטונים שהמשתמש בחר. כשהאפליקציה עוברת אל ברקע, או כשהמשתמש הורג את האפליקציה באופן פעיל, המערכת בסופו של דבר דוחה את ההרשאות האלה. ההתנהגות הזו זהה להרשאות חד-פעמיות אחרות.

התנהגות במהלך בחירה מחדש של מדיה

אם האפליקציה צריכה גישה לתמונות ולסרטונים נוספים בשלב מאוחר יותר, אפשר חייב לבקש ידנית את ההרשאה READ_MEDIA_IMAGES או שוב ההרשאה READ_MEDIA_VIDEO. המערכת מבצעת את אותו תהליך כמו בבקשת ההרשאה הראשונית, כדי לבקש מהמשתמשים לבחור תמונות וסרטונים ( איור 2).

אם האפליקציה שלך פועלת לפי השיטות המומלצות בנושא הרשאות, השינוי הזה לא אמור להשפיע עליך להפסיק את פעולת האפליקציה. הדבר נכון במיוחד אם האפליקציה שלך לא מניחה שה-URI הגישה נשמרת, מאחסנת את מצב הרשאת המערכת או מרעננת את קבוצת תמונות שמוצגות אחרי שינוי ההרשאה. עם זאת, לא בטוח שההתנהגות הזו להיות אידיאליות בהתאם לתרחיש לדוגמה של האפליקציה שלכם. כדי לספק את החוויה הטובה ביותר למשתמשים שלך, מומלץ להטמיע את הכלי לבחירת תמונות או להתאים באמצעות בוחר הגלריה של האפליקציה כדי לטפל בהתנהגות הזו ישירות באמצעות הרשאה READ_MEDIA_VISUAL_USER_SELECTED.