Cara Menggunakan File AAR di Plugin Capacitor

Ingin mengintegrasikan fitur Android ke dalam aplikasi Anda? Capacitor Panduan ini menjelaskan cara menggunakan file AAR (Arsip Android) di plugin __CAPGO_KEEP_0__ untuk menggabungkan fungsi Android asli dengan aplikasi web lintas platform. Poin Utama: Panduan ini menjelaskan cara menggunakan file AAR (Arsip Android) di plugin Capacitor untuk menggabungkan fungsi Android asli dengan aplikasi web lintas platform. Poin Utama:

Panduan ini menjelaskan cara menggunakan file AAR (Arsip Android) di plugin __CAPGO_KEEP_0__ untuk menggabungkan fungsi Android asli dengan aplikasi web lintas platform.

• Apa itu file AAR? File AAR Android yang sudah dikemas dengan code, sumber daya, dan file native.
• Mengapa menggunakan mereka? File AAR memungkinkan penggunaan ulang code, memudahkan perawatan, dan melindungi fitur properti.
• Apa yang dibutuhkan? Alat seperti Android Studio, Gradle, dan Node.js, plus pengaturan proyek yang tepat.
• Bagaimana cara mengintegrasikannya? Tempatkan file-file AAR di libs, atur Gradle, dan hubungkan mereka ke plugin-plugin Capacitor.

Langkah-Langkah Cepat:

1. Tetapkan lingkungan Anda: Pasang alat-alat yang diperlukan dan atur Android Studio.
2. Organisir proyek Anda: Buat struktur yang jelas untuk plugin __CAPGO_KEEP_0__ Anda Capacitor plugin.
3. Tempatkan mereka di dan perbarui dependensi Gradle. android/libs Tulis plugin __CAPGO_KEEP_0__:
4. Write plugin code: Tautankan fungsi AAR dengan JavaScript dengan Capacitor’s API.
5. Lakukan tes secara menyeluruh: Gunakan debugger Android Studio untuk memastikan integrasi yang lancar.

Dengan mengikuti panduan ini, Anda dapat menyematkan file AAR ke dalam plugin Capacitor Anda dengan mudah, sehingga membuka kemampuan Android native untuk aplikasi web Anda.

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

Persyaratan Pengaturan Pengembangan

Sebelum bekerja dengan file AAR, pastikan lingkungan pengembangan Anda telah terkonfigurasi dengan baik untuk menghindari kesalahan.

Perangkat Lunak yang Diperlukan

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

Selain itu, pastikan komponen berikut termasuk dalam Manajer SDK Anda:

• Platform Android SDK 33 (Android 13.0)
• Alat Bangun Android SDK 33.0.0
• Alat Perintah Baris Perintah Android SDK
• Emulator Android
• Platform-Tools Android SDK

Langkah-Langkah Pengaturan Proyek

1. Mulai dengan Membuat Lingkungan Pengembangan

Mulai dengan membuat direktori baru dengan struktur sebagai berikut:

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

2. Konfigurasi Pengaturan Android Studio

Luncurkan Android Studio dan atur pengaturan berikut:

• Atur versi JDK Gradle ke 11 atau lebih tinggi.
• Aktifkan fitur pengunduhan otomatis untuk komponen Android SDK.
• Perbarui variabel lingkungan sistem Anda dengan jalur Android SDK yang benar.

3. Siapkan Struktur Plugin Anda

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

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

4. Set Up Pengawasan Versi

Inisialisasi Git di direktori proyek Anda dan buat sebuah .gitignore file untuk mengabaikan file yang tidak perlu. Berikut contoh .gitignore:

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

Setelah langkah-langkah ini selesai, Anda akan siap untuk melanjutkan ke menambahkan file AAR Anda.

Menambahkan File AAR ke Plugin Anda

Mendapatkan File AAR

File AAR dapat berasal dari SDK pihak ketiga, library kustom, atau dependensi Maven. Sebaiknya, dokumentasikan sumber, versi, dan tujuan mereka dalam sebuah README file yang terletak di libs directory.

Setelah Anda memiliki file AAR yang siap dan didokumentasikan, Anda dapat mengonfigurasi plugin Anda untuk menambahkannya.

Mengatur File Plugin

Susun file plugin Anda untuk memastikan integrasi yang lancar dari dependensi AAR. Berikut adalah contoh struktur plugin Anda mungkin terlihat:

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, tempatkan file-file tersebut di android/libs dengan mengikuti langkah-langkah berikut:

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

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

• Susun file vendor khusus ke subdirektori untuk pengelolaan yang lebih baik:

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

Menggunakan subdirektori untuk file konfigurasi vendor membantu menjaga organisasi dan menghindari konflik pembangunan ketika bekerja dengan dependensi AAR multiple.

Gradle Langkah-Langkah Konfigurasi

Mengupdate build.gradle

Untuk mengintegrasikan file-file AAR ke dalam plugin Capacitor Anda, Anda perlu mengkonfigurasi Gradle dengan tepat. Mulailah dengan menambahkan pengaturan repositori ini ke android/build.gradle:

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

Lalu, masukkan dependensi AAR ke dalam 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 pengelolaan versi yang lebih baik, buatlah gradle.properties file di root proyek Anda dan definisikan versi library Anda:

# Library versions
MY_LIBRARY_VERSION=1.2.3
CAPACITOR_VERSION=5.5.0

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

android {
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }

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

Setelah Anda telah membuat perubahan-perubahan ini, sinkronkan proyek Anda untuk menerapkan perubahan-perubahan tersebut.

Jalankan Sinkronisasi Gradle

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

Setelah sinkronisasi, verifikasi hal-hal berikut:

Jika sinkronisasi gagal, periksa kembali konfigurasi Anda. Misalnya, pastikan pengaturan ini sudah ada:

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

    lintOptions {
        abortOnError false
    }
}

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

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

Setelah sinkronisasi selesai dengan sukses, file AAR Anda seharusnya sudah terintegrasi sepenuhnya dan siap untuk diuji.

Menghubungkan Fitur AAR ke Capacitor

Membuat Kelas Plugin

Setelah file Gradle Anda disinkronisasi, saatnya menghubungkan fungsi AAR Anda dengan mengembangkan kelas Plugin kelas. Langkah ini menghubungkan JavaScript ke Android native code.

@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 butuhkan untuk menginisialisasi library AAR:

Membuat Metode Plugin

Selanjutnya, definisikan metode-metode dalam plugin menggunakan @PluginMethod pembuatan tanda. Metode-metode ini mengelola 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-tugas yang memerlukan eksekusi secara asynchronous:

@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 adalah cara umum jenis-jenis data dikonversi antara JavaScript dan Java:

Untuk membersihkan sumber daya, override metode: handleOnDestroy metode:

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

Dengan metode-metode ini, jembatan native Anda sudah siap. Tes implementasi Anda di lingkungan debug Android Studio untuk memastikan semuanya berjalan seperti yang diharapkan.

Menguji dan Mengatasi Masalah

Mengembangkan di Android Studio

Untuk meng-debug integrasi AAR Anda di Android Studio, mulai dengan mengaktifkan mode debug di proyek Anda’s build.gradle file:

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

Tambahkan titik henti di metode plugin Anda untuk mengikuti 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 kunci:

Jika masalah tidak terpecahkan dengan debugging, ikuti langkah-langkah troubleshooting di bagian berikutnya.

Langkah-Langkah Troubleshooting

Ketika debugging sendiri tidak cukup, gunakan langkah-langkah ini untuk menangani masalah umum:

1. Konflik Dependensi

Periksa konflik versi di file Anda. Anda dapat memaksakan versi tertentu untuk menyelesaikan konflik: build.gradle 2. Libray Nativ Tidak Ditemukan

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

Pastikan AAR mencakup file yang diperlukan di direktori yang tepat, seperti:

3. Masalah Penggabungan Manifest .so Jika Anda mengalami konflik manifest, masukkan hal berikut di file Anda untuk mengatasi library yang bermasalah:

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

4. Kecelakaan Runtime dan Pengelolaan Memori

Gunakan tab Performa di Android Studio untuk memantau stabilitas runtime. Untuk masalah inisialisasi, tangani kecemasan dengan hati-hati: AndroidManifest.xml Untuk mencegah kebocoran memori, pastikan sumber daya dilepaskan dengan benar. Gunakan Profiler Memori di Android Studio untuk mengikuti penggunaan heap dan mengidentifikasi kebocoran apa pun.

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

__CAPGO_KEEP_0__

__CAPGO_KEEP_0__

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

__CAPGO_KEEP_0__

Ringkasan

Untuk mengintegrasikan file-file AAR ke dalam plugin Capacitor, Anda perlu mengatur lingkungan Android, menempatkan file-file AAR dengan benar, mengkonfigurasi Gradle dengan tepat, dan melakukan tes secara menyeluruh.

Fase-Fase Implementasi Utama

Setelah Anda menguasai dasar-dasar ini, Anda dapat mengeksplorasi teknik yang lebih maju.

Langkah Selanjutnya

Untuk meningkatkan plugin Anda, fokuslah pada area ini:

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

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

• Strategi Perawatan
  Automatisasi tes, manajemen versi AAR dengan pengendalian versi, menjaga log perubahan, dan atur laporan kesalahan untuk menangani masalah produksi.

Jika Anda berencana untuk berbagi plugin Anda secara publik, pastikan untuk menyediakan dokumentasi rinci tentang pengaturan AAR khusus dan setiap batasan platform. Hal ini akan membuatnya lebih mudah bagi pengembang lain untuk menerima dan menggunakan plugin Anda secara efektif.