Ekstensi SDK

Ekstensi SDK memanfaatkan komponen sistem modular untuk menambahkan API ke SDK publik untuk level API tertentu yang telah dirilis sebelumnya. API ini dikirimkan ke perangkat saat pengguna akhir menerima update modul melalui update sistem Google Play. Developer aplikasi dapat menggunakan API ini di aplikasi mereka untuk menyediakan fungsi tambahan yang awalnya tidak tersedia di SDK untuk versi Android sebelumnya.

Pembuatan Versi API

Mulai dari Android 11 (level API 30), perangkat Android menyertakan kumpulan Ekstensi SDK. Saat ditambahkan, API baru akan disertakan dalam level API, tetapi juga dapat disertakan dalam ekstensi SDK dari versi tertentu. Misalnya, ACTION_PICK_IMAGES API untuk Pemilih Foto ditambahkan ke SDK publik di Android 13 (level API 33), tetapi juga tersedia melalui ekstensi SDK yang dimulai di Ekstensi R Versi 2. Nama Ekstensi SDK sesuai dengan konstanta bilangan bulat–baik konstanta dari Build.VERSION_CODES, atau yang ditentukan di class SdkExtensions (seperti SdkExtensions.AD_SERVICES).

Menentukan Ekstensi SDK yang akan digunakan

Sebelum dapat menggunakan API Ekstensi SDK, Anda harus terlebih dahulu menentukan SDK mana yang menyertakan API yang mendukung kasus penggunaan aplikasi Anda.

Halaman referensi API untuk API Ekstensi SDK menentukan versi ekstensi SDK paling awal yang dapat digunakan aplikasi Anda untuk mengakses API. Jika dokumentasi tersebut juga menentukan versi platform Android (direferensikan oleh level API), API tersebut juga tersedia untuk semua perangkat yang menjalankan versi Android tersebut atau yang lebih tinggi.

Misalnya, ACTION_PICK_IMAGES umumnya tersedia di SDK publik yang dimulai dari Android 13 (level API 33), tetapi juga tersedia di perangkat sejak Android 11 (level API 30) selama perangkat memiliki setidaknya Ekstensi R Versi 2:

API yang merupakan bagian dari Ekstensi SDK menampilkan versi ekstensinya di dokumen referensi API

Untuk menggunakan API ini, Anda harus melakukan kompilasi terhadap SDK yang setidaknya merupakan level API 33, atau setidaknya Ekstensi Level 2.

Untuk menggunakan SDK ekstensi, ikuti langkah-langkah berikut:

  1. Cari versi ekstensi minimum yang Anda butuhkan dengan memeriksa dokumentasi fitur dan referensi API untuk API yang ingin Anda gunakan.
  2. Setelah menentukan versi ekstensi yang diperlukan untuk set fitur, buka SDK Manager di Android Studio.
  3. Pilih entri Android SDK Platform dengan versi ekstensi yang sesuai (atau versi yang lebih tinggi, karena API bersifat aditif). Misalnya: Android SDK Platform 33, Ekstensi Level 4.

  4. Deklarasikan nilai ini di file build.gradle.kts atau build.gradle aplikasi Anda:

    Groovy

    android {
    compileSdk 33
    compileSdkExtension 4
    ...
}

    Kotlin

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

Memeriksa apakah Ekstensi SDK tersedia

Aplikasi Anda dapat memeriksa versi Ekstensi SDK yang tersedia saat runtime, dan saat mengembangkan, Anda dapat mencari versi ekstensi menggunakan perintah Android Debug Bridge (adb), seperti dijelaskan di bagian berikut.

Memeriksa saat runtime

Saat runtime, aplikasi Anda dapat memeriksa apakah Ekstensi SDK tersedia untuk versi platform tertentu menggunakan metode getExtensionVersion(). Misalnya, kode berikut akan memeriksa apakah ekstensi versi 2 atau yang lebih tinggi untuk Ekstensi SDK Android 11 (level API 30) tersedia:

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;
}

Hal ini serupa dengan melakukan pemeriksaan berdasarkan 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;
}

Pemeriksaan SDK_INT ini masih aman dan valid, tetapi isPhotoPickerAvailable akan menampilkan nilai salah di beberapa perangkat meskipun API ekstensi tersedia. Akibatnya, pemeriksaan SDK_INT tidak optimal, dan pemeriksaan versi ekstensi adalah cara yang lebih baik untuk memeriksa ketersediaan API. Semua perangkat dengan SDK_INT yang lebih tinggi atau sama dengan 33 (Android 13 atau yang lebih tinggi) memiliki Photo Picker API di SDK publik, tetapi ada perangkat dengan SDK_INT lebih rendah dari 33 (seperti Android 11, 12, dan 12L) yang juga dapat mengakses API jika memiliki ekstensi R minimal versi 2.

Dalam hal ini, penggunaan pemeriksaan versi ekstensi dapat membantu aplikasi Anda mengirimkan fungsi tambahan ke lebih banyak pengguna. Lihat nama dan konstanta Ekstensi SDK untuk mengetahui daftar semua konstanta yang dapat Anda gunakan untuk memeriksa Ekstensi SDK tertentu di perangkat.

Ekstensi Layanan Iklan

Serupa dengan kumpulan umum Ekstensi SDK, referensi API AdServices terkadang menunjukkan bahwa API adalah bagian dari versi "Ekstensi Layanan Iklan". Tidak seperti Ekstensi SDK umum, Ekstensi Layanan Iklan menggunakan konstanta SdkExtensions.AD_SERVICES untuk menentukan versi mana yang ada di perangkat:

Kotlin

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

Java

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

Untuk mempelajari lebih lanjut fitur di Ekstensi Layanan Iklan dan cara memulai, lihat dokumentasi Ekstensi Layanan Iklan.

Metode utilitas

Dalam beberapa kasus, Ekstensi SDK memiliki metode utilitas Jetpack untuk memeriksa ketersediaan API Ekstensi SDK mereka. Misalnya, Anda dapat menggunakan fungsi library Jetpack untuk memeriksa ketersediaan PhotoPicker, yang memisahkan pemeriksaan versi kondisional.

Dukungan alat

Di Android Studio Flamingo | 2022.2.1 atau yang lebih tinggi, alat lint dapat memindai masalah pada versi Ekstensi SDK sebagai bagian dari pemeriksaan NewAPI-nya. Selain itu, Android Studio dapat otomatis membuat pemeriksaan versi yang benar untuk API yang diluncurkan menggunakan Ekstensi SDK.

Alat lint menandai instance saat versi Ekstensi SDK minimum yang diperlukan untuk memanggil API belum terpenuhi.

Nama dan konstanta Ekstensi SDK

Tabel berikut menjelaskan cara berbagai kumpulan Ekstensi SDK yang tercantum dalam dokumentasi referensi API dipetakan ke konstanta yang dapat digunakan aplikasi Anda untuk memeriksa ketersediaan API saat runtime. Kumpulan umum Ekstensi SDK untuk setiap SDK publik dipetakan ke nilai Build.VERSION_CODES.

Nama Ekstensi SDK Konstanta Perangkat yang memenuhi syarat
Ekstensi R VERSION_CODES.R Android 11 (level API 30) dan yang lebih tinggi
Ekstensi S VERSION_CODES.S Android 12 (level API 31) dan yang lebih tinggi
Ekstensi T VERSION_CODES.TIRAMISU Android 13 (level API 33) dan yang lebih tinggi
Ekstensi Layanan Iklan SdkExtensions.AD_SERVICES Android 13 (level API 33) dan yang lebih tinggi

Memeriksa menggunakan adb

Untuk memeriksa Ekstensi SDK mana yang tersedia di perangkat menggunakan adb, jalankan perintah berikut:

adb shell getprop | grep build.version.extensions

Setelah menjalankan perintah, Anda akan melihat output yang terlihat mirip dengan ini:

[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

Setiap baris menunjukkan Ekstensi SDK yang ada di perangkat beserta versi ekstensinya yang sesuai (dalam hal ini 3).