ส่วนขยาย SDK

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

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

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

กำหนด SDK Extensions ที่จะใช้

ก่อนที่จะใช้ API ของ SDK Extension คุณต้องกำหนดก่อนว่า SDK ใดบ้างที่มี API ที่รองรับกรณีการใช้งานของแอป

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

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

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

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

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

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

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

    ดึงดูด

    android {
    compileSdk 33
    compileSdkExtension 4
    ...
}

    Kotlin

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

ตรวจสอบว่า SDK Extensions พร้อมใช้งานหรือไม่

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

ตรวจสอบในรันไทม์

แอปสามารถตรวจสอบในรันไทม์ว่า SDK Extensions พร้อมใช้งานสำหรับแพลตฟอร์มเวอร์ชันหนึ่งๆ หรือไม่ โดยใช้วิธี getExtensionVersion() ตัวอย่างเช่น โค้ดต่อไปนี้จะตรวจสอบว่า Extension เวอร์ชัน 2 ขึ้นไปสำหรับ SDK Extension ของ 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 จะแสดงผลเป็น "เท็จ" ในอุปกรณ์บางเครื่องแม้ว่า API ของ Extension จะพร้อมใช้งานก็ตาม ด้วยเหตุนี้ การตรวจสอบ SDK_INT จึงไม่ใช่ตัวเลือกที่ดีที่สุด และการตรวจสอบเวอร์ชัน Extension เป็นวิธีที่ดีกว่าในการตรวจสอบความพร้อมใช้งานของ API อุปกรณ์ทั้งหมดที่มี SDK_INT มากกว่าหรือเท่ากับ 33 (Android 13 ขึ้นไป) จะมี API ของเครื่องมือเลือกรูปภาพใน SDK สาธารณะ แต่ก็มีอุปกรณ์ที่มี SDK_INT น้อยกว่า 33 (เช่น Android 11, 12 และ 12L) ที่เข้าถึง API ได้เช่นกันหากมี R Extension เวอร์ชัน 2 ขึ้นไป

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

Ad Services Extensions

การอ้างอิง API ของ AdServices บางครั้งจะระบุว่า API เป็นส่วนหนึ่งของ "Ad Services Extensions" เวอร์ชันหนึ่ง ซึ่งคล้ายกับ SDK Extensions ทั่วไป แต่ Ad Services Extensions จะใช้ค่าคงที่ 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;
}

ดูข้อมูลเพิ่มเติมเกี่ยวกับฟีเจอร์ใน Ad Services Extensions และวิธีเริ่มต้นใช้งานได้ที่เอกสารประกอบ Ad Services Extensions

วิธีการยูทิลิตี

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

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

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

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

ชื่อและค่าคงที่ของ SDK Extension

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

ชื่อ SDK Extension ค่าคงที่ อุปกรณ์ที่มีสิทธิ์
R Extensions VERSION_CODES.R Android 11 (API ระดับ 30) ขึ้นไป
S Extensions VERSION_CODES.S Android 12 (API ระดับ 31) ขึ้นไป
T Extensions VERSION_CODES.TIRAMISU Android 13 (ระดับ API 33) ขึ้นไป
U Extensions VERSION_CODES.UPSIDE_DOWN_CAKE Android 14 (ระดับ API 34) ขึ้นไป
V Extensions VERSION_CODES.VANILLA_ICE_CREAM Android 15 (ระดับ API 35) ขึ้นไป
B Extensions VERSION_CODES.BAKLAVA Android 16 (ระดับ API 36) ขึ้นไป
C Extensions VERSION_CODES.CINNAMON_BUN Android 17 (ระดับ API 37) ขึ้นไป
Ad Services Extensions SdkExtensions.AD_SERVICES Android 13 (ระดับ API 33) ขึ้นไป

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

หากต้องการตรวจสอบว่า SDK Extensions ใดบ้างที่พร้อมใช้งานในอุปกรณ์โดยใช้ 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 Extension ที่มีอยู่ในอุปกรณ์พร้อมกับเวอร์ชัน Extension ที่เกี่ยวข้อง (ในกรณีนี้คือ 3)