Cara Menggunakan File AAR di Plugin Capacitor

Ingin mengintegrasikan fitur Android ke dalam Capacitor app Anda? Panduan ini menjelaskan cara menggunakan file AAR (Android Archive) di Plugin Capacitor untuk menggabungkan fungsionalitas native Android dengan web app lintas platform.

Poin Penting:

• Apa itu file AAR? Library Android siap pakai yang berisi code, resource, dan file native.
• Mengapa menggunakannya? File AAR memungkinkan penggunaan kembali code, mempermudah maintenance, dan melindungi fitur proprietary.
• Apa saja persyaratannya? Tools seperti Android Studio, Gradle, dan Node.js, serta setup project yang benar.
• Cara integrasi? Letakkan file AAR di libs, konfigurasikan Gradle, dan hubungkan ke plugin Capacitor.

Langkah cepat:

1. Siapkan environment Anda: Instal tools yang dibutuhkan dan konfigurasikan Android Studio.
2. Atur proyek Anda: Buat struktur yang jelas untuk plugin Capacitor.
3. Tambah file AAR: Letakkan di android/libs dan update dependensi Gradle.
4. Tulis plugin code: Hubungkan fungsionalitas AAR ke JavaScript dengan Capacitor dari API.
5. Uji secara menyeluruh: Gunakan debugger Android Studio untuk memastikan integrasi berjalan lancar.

Dengan mengikuti panduan ini, Anda dapat mengintegrasikan file AAR ke plugin Capacitor Anda dengan mulus, membuka kemampuan Android native untuk aplikasi web Anda.

Cara menyematkan pustaka Android (file AAR) ke dalam capacitor plugin

Persyaratan Setup Development

Sebelum bekerja dengan file AAR, pastikan lingkungan pengembangan Anda sudah dikonfigurasi dengan benar untuk menghindari masalah.

Software yang Dibutuhkan

Berikut perangkat lunak yang Anda butuhkan untuk bekerja dengan file AAR di plugin Capacitor:

Selain itu, pastikan komponen berikut sudah terpasang di SDK Manager Anda:

• Platform Android SDK 33 (Android 13.0)
• Android SDK Build-Tools 33.0.0
• Android SDK Command-line Tools untuk SDK
• Emulator Android
• Platform-Tools Android SDK

Langkah Setup Proyek

1. Inisialisasi Lingkungan Pengembangan Anda

Mulai dengan membuat direktori baru dengan struktur berikut:

my-plugin/
├── android/
│   ├── src/
│   └── build.gradle
├── src/
│   └── definitions.ts
└── package.json

2. Konfigurasi Pengaturan Android Studio

Buka Android Studio dan sesuaikan pengaturan berikut:

• Atur Gradle JDK ke versi 11 atau lebih tinggi.
• Aktifkan fitur auto-download untuk komponen Android SDK.
• Perbarui environment variables sistem Anda dengan path Android SDK yang benar.

3. Siapkan Struktur Plugin Anda

Perbarui android/build.gradle file dengan pengaturan ini untuk menyertakan dukungan file AAR:

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

4. Siapkan Version Control

Inisialisasi Git di direktori proyek Anda dan buatlah .gitignore file untuk mengecualikan file yang tidak perlu. Berikut contoh .gitignore:

android/build/
node_modules/
dist/
*.iml
.idea/
.gradle/
local.properties

Setelah langkah-langkah ini selesai, Anda siap lanjut menambahkan file AAR Anda.

Menambahkan File AAR ke Plugin Anda

Mendapatkan File AAR

File AAR bisa berasal dari SDK pihak ketiga, library kustom, atau dependensi Maven. Sebaiknya dokumentasikan sumber, versi, dan tujuannya dalam README file yang terletak di libs direktori.

Setelah file AAR Anda siap dan terdokumentasi, Anda dapat mengonfigurasi plugin untuk menyertakannya.

Menyiapkan File Plugin

Atur file plugin Anda agar integrasi dependensi AAR berjalan lancar. Berikut contoh struktur plugin Anda:

my-plugin/
├── android/
│   ├── libs/        # AAR files with README
│   ├── src/
│   └── build.gradle
├── src/
│   └── definitions.ts
└── package.json
{
    "files": [
        "android/libs/*.aar",
        "android/src/**/*",
        "src/**/*"
    ]
}

Penempatan File AAR

Untuk mengaktifkan fungsi AAR, letakkan file di dalam android/libs direktori plugin Anda dengan mengikuti langkah-langkah berikut:

• Gunakan format penamaan yang jelas dan konsisten, seperti libraryname-version.aar.
• Kelola versi di dalam versions.properties file. Contohnya:

library1=1.2.3
library2=2.0.0

• Tambahkan dependencies.gradle file untuk dependensi lainnya:

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.aar'])
    implementation 'com.example:dependency:1.0.0'
}

• Kelompokkan file khusus vendor ke dalam subdirektori agar lebih mudah dikelola:

android/libs/
├── vendor1/
│   ├── feature.aar
│   └── config.json
└── vendor2/
    ├── module.aar
    └── settings.xml

Menyimpan file konfigurasi di subdirektori khusus vendor membantu menjaga kerapian dan menghindari konflik build saat bekerja dengan beberapa dependensi AAR.

Gradle Langkah Konfigurasi

Update build.gradle

Untuk mengintegrasikan file AAR ke plugin Capacitor Anda, Anda perlu mengonfigurasi Gradle dengan tepat. Mulailah dengan menambahkan pengaturan repository ini ke android/build.gradle:

repositories {
    google()
    mavenCentral()
    flatDir {
        dirs 'libs'
    }
}

Kemudian, sertakan dependensi AAR di dependencies blok:

dependencies {
    implementation files('libs/your-library.aar')
    implementation fileTree(dir: 'libs', include: ['**/*.aar'])
    implementation "com.getcapacitor:core:${capacitorVersion}"
    implementation "androidx.appcompat:appcompat:1.6.1"
}

Untuk manajemen versi yang lebih baik, buat gradle.properties file di root proyek Anda dan definisikan versi pustaka Anda:

# Library versions
MY_LIBRARY_VERSION=1.2.3
CAPACITOR_VERSION=5.5.0

Jika file AAR menyertakan dependensi tambahan, deklarasikan di android/build.gradle seperti ini:

android {
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }

    packagingOptions {
        exclude 'META-INF/DEPENDENCIES'
        exclude 'META-INF/LICENSE'
    }
}

Setelah membuat perubahan ini, sync proyek Anda untuk menerapkannya.

Jalankan Gradle Sync

Buka proyek Anda di Android Studio dan tunggu Gradle melakukan sync otomatis. Jika tidak berjalan, klik tombol “Sync Project with Gradle Files” di toolbar.

Setelah sync, verifikasi hal berikut:

Jika sinkronisasi gagal, periksa kembali konfigurasi Anda. Misalnya, pastikan pengaturan berikut sudah benar:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    lintOptions {
        abortOnError false
    }
}

Untuk file AAR berukuran besar, Anda mungkin perlu menambah alokasi memori Gradle di gradle.properties:

org.gradle.jvmargs=-Xmx2048m -XX:MaxPermSize=512m

Setelah sinkronisasi berhasil, file AAR Anda seharusnya sudah terintegrasi penuh dan siap diuji.

Menghubungkan fitur AAR ke Capacitor

Menulis Plugin Class

Setelah file Gradle tersinkronisasi, saatnya menghubungkan fungsionalitas AAR Anda dengan meng-extend Plugin class. Langkah ini menghubungkan JavaScript ke code native Android.

@NativePlugin(
    permissions = {
        Manifest.permission.REQUIRED_PERMISSION
    }
)
public class YourPlugin extends Plugin {
    private YourAARLibrary libraryInstance;

    @Override
    public void load() {
        super.load();
        libraryInstance = new YourAARLibrary(getContext());
    }
}

Berikut yang Anda perlukan untuk menginisialisasi library AAR:

Membuat Metode Plugin

Selanjutnya, definisikan metode di plugin Anda menggunakan @PluginMethod annotation. Metode-metode ini menangani pertukaran data antara JavaScript dan Java.

@PluginMethod
public void performAction(PluginCall call) {
    try {
        // Get data from JavaScript
        String inputData = call.getString("inputKey");

        // Call AAR library method
        YourLibraryResult result = libraryInstance.processData(inputData);

        // Return result to JavaScript
        JSObject ret = new JSObject();
        ret.put("value", result.getValue());
        call.resolve(ret);
    } catch (Exception e) {
        call.reject("Error processing data", e);
    }
}

Untuk tugas yang perlu dijalankan secara asinkron:

@PluginMethod(returnType = PluginMethod.RETURN_CALLBACK)
public void startContinuousOperation(PluginCall call) {
    call.setKeepAlive(true);

    libraryInstance.setCallback(new LibraryCallback() {
        @Override
        public void onUpdate(String data) {
            JSObject ret = new JSObject();
            ret.put("data", data);
            call.resolve(ret);
        }
    });
}

Berikut cara tipe umum dikonversi antara JavaScript dan Java:

Untuk pembersihan resource, override handleOnDestroy method:

@Override
protected void handleOnDestroy() {
    if (libraryInstance != null) {
        libraryInstance.cleanup();
        libraryInstance = null;
    }
    super.handleOnDestroy();
}

Dengan metode ini, native bridge Anda siap. Uji implementasi Anda di lingkungan debug Android Studio untuk memastikan semuanya berjalan sesuai harapan.

Pengujian dan Perbaikan Masalah

Debugging di Android Studio

Untuk melakukan debugging integrasi AAR di Android Studio, mulai dengan mengaktifkan mode debug di build.gradle file Anda:

android {
    buildTypes {
        debug {
            debuggable true
            minifyEnabled false
        }
    }
}

Tambahkan breakpoint di metode plugin Anda untuk melacak aliran data dan mengidentifikasi potensi masalah:

@PluginMethod
public void yourMethod(PluginCall call) {
    // Set a breakpoint here to inspect input data
    String inputValue = call.getString("key");
    // Another breakpoint here to check method calls to the AAR
    libraryInstance.someMethod(inputValue);
}

Gunakan panel Debug di Android Studio untuk memantau area utama:

Jika debugging tidak menyelesaikan masalah, ikuti langkah troubleshooting di bagian berikutnya.

Langkah Troubleshooting

Jika debugging saja tidak cukup, gunakan langkah-langkah berikut untuk mengatasi masalah umum:

1. Konflik Dependency

Check for version conflicts in your build.gradle file Anda. Anda bisa memaksa versi tertentu untuk mengatasi konflik:

configurations.all {
    resolutionStrategy {
        force 'com.google.android:android:4.1.1.4'
        // Add other forced versions as needed
    }
}

2. Native Library Hilang

Pastikan AAR mencakup yang diperlukan .so file yang diperlukan di direktori yang sesuai, seperti:

• jniLibs/armeabi-v7a/
• jniLibs/arm64-v8a/
• jniLibs/x86/
• jniLibs/x86_64/

3. Masalah Manifest Merger

Jika terjadi konflik manifest, tambahkan berikut ini ke AndroidManifest.xml file Anda untuk menimpa library yang bermasalah:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="your.plugin.package">
    <uses-sdk tools:overrideLibrary="conflicting.library.package"/>
</manifest>

4. Runtime Crash dan Manajemen Memori

Gunakan tab Performance di Android Studio untuk memantau stabilitas runtime. Untuk masalah inisialisasi, tangani exception dengan hati-hati:

try {
    libraryInstance = new YourAARLibrary(getContext());
} catch (Exception e) {
    Log.e("PluginError", "Failed to initialize library: " + e.getMessage());
    return;
}

Untuk mencegah memory leak, pastikan resource dilepas dengan benar. Gunakan Memory Profiler di Android Studio untuk melacak penggunaan heap dan mengidentifikasi kebocoran.

Ringkasan

Untuk mengintegrasikan file AAR ke plugin Capacitor, Anda perlu menyiapkan lingkungan Android, menempatkan file AAR dengan benar, mengonfigurasi Gradle secara akurat, dan melakukan pengujian menyeluruh.

Fase Implementasi Utama

Setelah Anda menguasai dasar-dasar ini, Anda dapat menjelajahi teknik yang lebih lanjut.

Langkah Berikutnya

Untuk meningkatkan plugin Anda, fokus pada area berikut:

• Optimasi Performa
  Gunakan profiler Android Studio untuk memantau penggunaan memori dan pastikan sumber daya dibersihkan dengan benar.

• Persiapan Distribusi
  Dokumentasikan semua konfigurasi AAR, buat dokumentasi API, dan uji kompatibilitas dengan level Android API 29–34.

• Strategi Pemeliharaan
  Otomatiskan pengujian, kelola versi AAR dengan version control, pertahankan changelog, dan atur pelaporan error untuk menangani masalah produksi.

Jika Anda berencana membagikan plugin secara publik, pastikan menyediakan dokumentasi detail tentang setup spesifik AAR dan batasan platform apa pun. Ini akan memudahkan developer lain mengadopsi dan menggunakan plugin Anda secara efektif.

Lanjutkan dari Cara Menggunakan File AAR di Plugin Capacitor

Jika Anda menggunakan Cara Menggunakan File AAR di Plugin Capacitor untuk merencanakan pekerjaan plugin native, hubungkan dengan Direktori Plugin Capgo untuk alur kerja produk di Direktori Plugin Capgo, Plugin Capacitor oleh Capgo untuk detail implementasi pada Capacitor Plugins oleh Capgo Menambahkan atau Memperbarui Plugin untuk detail implementasi pada Menambahkan atau Memperbarui Plugin, Alternatif Plugin Ionic Enterprise untuk alur kerja produk di alternatif plugin Ionic Enterprise, dan Capgo Native Build untuk alur kerja produk di Capgo Native Builds.