ส่วนขยาย SDK

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

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

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

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

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

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

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

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

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

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

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

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

    Groovy

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

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

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

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

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 สำหรับตรวจสอบความพร้อมใช้งานของ API ของส่วนขยาย SDK เช่น คุณสามารถใช้ฟังก์ชันไลบรารีของ Jetpack เพื่อตรวจสอบความพร้อมใช้งานของ PhotoPicker ซึ่งจะแยกการตรวจสอบเวอร์ชันแบบมีเงื่อนไขออก

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

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

เครื่องมือ Lint จะแจ้งว่าอินสแตนซ์ไม่เป็นไปตามเวอร์ชันขั้นต่ำของ SDK Extension ที่จําเป็นในการเรียก 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) ขึ้นไป
ส่วนขยาย U VERSION_CODES.UPSIDE_DOWN_CAKE Android 14 (API ระดับ 34) ขึ้นไป
ส่วนขยาย V VERSION_CODES.VANILLA_ICE_CREAM Android 15 (API ระดับ 35) ขึ้นไป
ส่วนขยายบริการโฆษณา 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)