ส่วนขยาย SDK

ส่วนขยาย SDK ใช้ประโยชน์จากระบบโมดูล คอมโพเนนต์เพื่อเพิ่ม API SDK สาธารณะสำหรับ API บางระดับที่เปิดตัวไปก่อนหน้านี้ API เหล่านี้ ที่ส่งไปยังอุปกรณ์เมื่อผู้ใช้ปลายทางได้รับการอัปเดตโมดูลผ่าน Google Play ระบบ อัปเดต แอป นักพัฒนาซอฟต์แวร์สามารถใช้ API เหล่านี้ในแอปของตน ฟังก์ชันที่ก่อนหน้านี้ไม่มีให้ใน SDK สำหรับ เวอร์ชัน Android

การกำหนดเวอร์ชัน API

ตั้งแต่ Android 11 (API ระดับ 30) เป็นต้นไป อุปกรณ์ Android จะมีชุด SDK ส่วนขยาย เมื่อมีการเพิ่ม API ใหม่ API เหล่านั้นจะรวมอยู่ในระดับ API แต่อาจ รวมอยู่ในส่วนขยาย SDK ของเวอร์ชันที่เจาะจงได้ด้วย ตัวอย่างเช่น พารามิเตอร์ ACTION_PICK_IMAGES เพิ่ม API สำหรับเครื่องมือเลือกรูปภาพไปยัง SDK สาธารณะใน Android 13 (API ระดับ 33) แล้ว แต่ยังมีให้ใช้งานผ่านส่วนขยาย SDK ในส่วนขยาย R เวอร์ชัน 2 ด้วย ชื่อส่วนขยาย SDK จะสอดคล้องกับจำนวนเต็มคงที่ ไม่ว่าจะเป็นค่าใด ค่าคงที่จาก Build.VERSION_CODES หรือ 1 ที่กำหนดไว้ในคลาส SdkExtensions (เช่น SdkExtensions.AD_SERVICES)

เลือกว่าจะใช้ส่วนขยาย SDK ใด

ก่อนที่คุณจะใช้ SDK ส่วนขยาย API ได้ คุณต้องพิจารณาก่อนว่า SDK ใด มี API ที่รองรับกรณีการใช้งานของแอป

หน้าอ้างอิง API สำหรับ API ส่วนขยาย SDK ระบุ SDK ที่เร็วที่สุด เวอร์ชันส่วนขยายที่แอปของคุณสามารถใช้เพื่อเข้าถึง API หากเอกสารประกอบ ระบุเวอร์ชันแพลตฟอร์ม Android ด้วย (อ้างอิงตามระดับ API) จากนั้น นอกจากนี้ API ยังใช้ได้กับอุปกรณ์ทั้งหมดที่ใช้ Android เวอร์ชันดังกล่าวหรือสูงกว่า

เช่น ACTION_PICK_IMAGES พร้อมให้บริการแก่ผู้ใช้ทั่วไปใน SDK สาธารณะ เริ่มตั้งแต่ Android 13 (API ระดับ 33) แต่พร้อมใช้งานบนอุปกรณ์ กลับไปเป็น Android 11 (API ระดับ 30) ตราบใดที่อุปกรณ์มี R ส่วนขยายเวอร์ชัน 2:

API ที่เป็นส่วนหนึ่งของส่วนขยาย SDK แสดงเวอร์ชันส่วนขยายใน API ข้อมูลอ้างอิง เอกสาร

หากต้องการใช้ API นี้ คุณต้องคอมไพล์กับ SDK ที่มีระดับ API เป็นอย่างต่ำ 33 หรือระดับส่วนขยายอย่างน้อย 2

หากต้องการใช้ SDK ส่วนขยาย ให้ทำตามขั้นตอนต่อไปนี้

  1. ค้นหาเวอร์ชันส่วนขยายขั้นต่ำที่คุณต้องการโดยตรวจสอบฟีเจอร์ และการอ้างอิง API สำหรับ API ที่คุณต้องการใช้
  2. หลังจากที่คุณระบุเวอร์ชันส่วนขยายที่จำเป็นสำหรับชุดฟีเจอร์แล้ว ให้เปิด SDK Manager ใน Android Studio
  3. เลือกรายการ Android SDK Platform ที่มีส่วนขยายที่เกี่ยวข้อง เวอร์ชัน (หรือเวอร์ชันสูงกว่าเนื่องจาก API เป็นส่วนเสริม) ดังตัวอย่างต่อไปนี้ แพลตฟอร์ม Android SDK 33, ส่วนขยายระดับ 4

  4. ประกาศค่าเหล่านี้ใน build.gradle.kts หรือ build.gradle ของแอป ไฟล์:

    ดึงดูด

    android {
    compileSdk 33
    compileSdkExtension 4
    ...
}

    Kotlin

    android {
    compileSdk = 33
    compileSdkExtension = 4
    ...
}

ตรวจสอบว่าส่วนขยาย SDK พร้อมให้บริการหรือไม่

แอปของคุณสามารถตรวจสอบเวอร์ชันส่วนขยาย SDK ที่พร้อมใช้งานขณะรันไทม์ และ ในขณะที่พัฒนา คุณสามารถค้นหาเวอร์ชันส่วนขยายโดยใช้ Android Debug คำสั่ง Bridge (adb) ตามที่อธิบายไว้ในส่วนต่อไปนี้

ตรวจสอบขณะรันไทม์

แอปสามารถตรวจสอบขณะรันไทม์ว่าส่วนขยาย SDK พร้อมใช้งานสำหรับ เวอร์ชันแพลตฟอร์มโดยใช้ getExtensionVersion() ตัวอย่างเช่น โค้ดต่อไปนี้จะตรวจสอบว่าส่วนขยายเวอร์ชัน 2 หรือไม่ ขึ้นไปสำหรับส่วนขยาย SDK ของ Android 11 (API ระดับ 30) ที่พร้อมใช้งาน ดังนี้

Kotlin

fun isPhotoPickerAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2
    // Safely use extension APIs that are available with Android 11 (API level 30) Extensions Version 2, such as Photo Picker.
}

Java

public static final boolean isPhotoPickerAvailable() {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2;
}

ซึ่งคล้ายกับการตรวจสอบตาม Build.VERSION.SDK_INT:

Kotlin

fun isPhotoPickerAvailable(): Boolean {
    return Build.VERSION.SDK_INT >= 33
}

Java

public static final boolean isPhotoPickerAvailable() {
    return Build.VERSION.SDK_INT >= 33;
}

การตรวจสอบ SDK_INT นี้ยังคงปลอดภัยและถูกต้อง แต่ isPhotoPickerAvailable จะ แสดงผล false ในอุปกรณ์บางเครื่อง แม้ว่าจะมี API ส่วนขยายให้ใช้งานก็ตาม เพื่อ แสดงว่าการตรวจสอบ SDK_INT จึงไม่เหมาะสม และการตรวจสอบเวอร์ชันของส่วนขยาย วิธีตรวจสอบความพร้อมใช้งาน API ที่ดียิ่งขึ้น อุปกรณ์ทั้งหมดที่มี SDK_INT ขึ้นไป มากกว่าหรือเท่ากับ 33 (Android 13 ขึ้นไป) มี API ของเครื่องมือเลือกรูปภาพใน SDK สาธารณะ แต่มีอุปกรณ์ที่มี SDK_INT ต่ำกว่า 33 (เช่น Android) 11, 12 และ 12L) ที่เข้าถึง API ได้ด้วยหากมีส่วนขยาย R เวอร์ชันของอย่างน้อย 2

ในกรณีนี้ การใช้การตรวจสอบเวอร์ชันส่วนขยายจะช่วยให้แอปแสดง ฟังก์ชันเพิ่มเติมให้กับผู้ใช้จำนวนมากขึ้น ดูชื่อส่วนขยาย SDK และ ค่าคงที่สำหรับรายการค่าคงที่ที่คุณสามารถใช้เพื่อ ตรวจหาส่วนขยาย SDK บางรายการในอุปกรณ์

ส่วนขยายบริการโฆษณา

เอกสารอ้างอิง API AdServices คล้ายกับชุดส่วนขยาย SDK ทั่วไป บางครั้งระบุว่า API เป็นส่วนหนึ่งของ "ส่วนขยายโฆษณาบริการโฆษณา" เวอร์ชัน ส่วนขยายบริการโฆษณาจะใช้ส่วนขยาย SDK ทั่วไป ซึ่งแตกต่างจากส่วนขยาย SDK ทั่วไป SdkExtensions.AD_SERVICES อย่างต่อเนื่องเพื่อระบุเวอร์ชันที่อยู่ในอุปกรณ์:

Kotlin

fun isAdServicesAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4
}

Java

public static final boolean isAdServicesAvailable() {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4;
}

หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับฟีเจอร์ต่างๆ ในส่วนขยายบริการโฆษณาและวิธีรับ โปรดดูที่ส่วนขยายบริการโฆษณา เอกสารประกอบ

วิธียูทิลิตี

ในบางกรณี ส่วนขยาย SDK จะมีวิธียูทิลิตีของ Jetpack เพื่อตรวจสอบ ของ SDK ส่วนขยาย API กัน ตัวอย่างเช่น คุณสามารถใช้ Jetpack ฟังก์ชัน Library สำหรับตรวจสอบ Photo Picker ความพร้อมจำหน่ายสินค้า [availability] ซึ่งจะลบการตรวจสอบเวอร์ชันแบบมีเงื่อนไขออกไป

การสนับสนุนเครื่องมือ

ใน Android Studio Flamingo | 2022.2.1 ขึ้นไป เครื่องมือ Lint สามารถสแกนหา ปัญหาที่เกิดกับเวอร์ชันส่วนขยาย SDK ที่เป็นส่วนหนึ่งของการตรวจสอบ NewAPI นอกจากนี้ Android Studio สามารถสร้างการตรวจสอบเวอร์ชันที่ถูกต้องโดยอัตโนมัติสำหรับ API ที่ เปิดตัวโดยใช้ส่วนขยาย SDK

วันที่
เครื่องมือ Lint จะแจ้งอินสแตนซ์ที่มีส่วนขยาย SDK ขั้นต่ำ ยังไม่เป็นไปตามเวอร์ชันที่ต้องใช้ในการเรียก API

ชื่อและค่าของส่วนขยาย SDK

ตารางต่อไปนี้จะอธิบายว่าส่วนขยาย SDK ชุดต่างๆ ที่ ที่แสดงในเอกสารประกอบอ้างอิง API จะแมปกับค่าคงที่ที่แอปของคุณสามารถใช้เพื่อ ตรวจสอบความพร้อมใช้งานของ API ขณะรันไทม์ ชุดส่วนขยาย SDK ทั่วไปสำหรับ SDK สาธารณะแต่ละรายการแมปกับค่าของ Build.VERSION_CODES

ชื่อส่วนขยาย SDK ค่าคงที่ อุปกรณ์ที่มีสิทธิ์
ส่วนขยาย R VERSION_CODES.R Android 11 (API ระดับ 30) ขึ้นไป
ส่วนขยาย S VERSION_CODES.S Android 12 (API ระดับ 31) ขึ้นไป
ส่วนขยาย T VERSION_CODES.TIRAMISU Android 13 (API ระดับ 33) ขึ้นไป
ส่วนขยายบริการโฆษณา SdkExtensions.AD_SERVICES Android 13 (API ระดับ 33) ขึ้นไป

ตรวจสอบโดยใช้ adb

หากต้องการตรวจสอบว่าส่วนขยาย SDK ใดพร้อมใช้งานในอุปกรณ์ที่ใช้ adb ให้เรียกใช้ คำสั่งต่อไปนี้

adb shell getprop | grep build.version.extensions

หลังจากเรียกใช้คำสั่ง คุณจะเห็นเอาต์พุตที่มีลักษณะดังนี้

[build.version.extensions.r]: [3] # Android 11 (API level 30) and higher
[build.version.extensions.s]: [3] # Android 12 (API level 31) and higher
[build.version.extensions.t]: [3] # Android 13 (API level 33) and higher

แต่ละบรรทัดแสดงส่วนขยาย SDK ที่มีอยู่ในอุปกรณ์ พร้อมกับส่วนขยาย เวอร์ชันส่วนขยายที่เกี่ยวข้อง (ในกรณีนี้คือ 3)