Cara Menggunakan File AAR di Plugin Capacitor

Ingin mengintegrasikan fitur Android ke dalam aplikasi web Anda dengan __CAPGO_KEEP_0__ Capacitor Aplikasi? Petunjuk ini menjelaskan cara menggunakan file AAR (Arsip Android) dalam Capacitor plugin untuk menggabungkan fungsi Android native dengan aplikasi web lintas platform.

Kunci Pemahaman:

• Mengapa AAR? File AAR adalah perpustakaan Android yang sudah diinstal, berisi code, sumber daya, dan file native.
• Mengapa menggunakan mereka? File AAR memungkinkan code penggunaan ulang, memudahkan perawatan, dan melindungi fitur properti.
• Apa yang dibutuhkan? Alat seperti Studio Android, Gradle, dan Node.js, plus pengaturan proyek yang tepat.
• Cara mengintegrasikan? Tempatkan file AAR di libs, konfigurasi Gradle, dan hubungkan ke plugin-plugin Capacitor.

Langkah-Langkah Cepat:

1. Tetapkan lingkungan Anda: Pasang alat-alat yang diperlukan dan konfigurasi Android Studio.
2. Organisasi proyek Anda: Buat struktur yang jelas untuk Anda Capacitor plugin.
3. Tambahkan file AAR: Tempatkan mereka di android/libs dan perbarui dependensi Gradle.
4. Tulis plugin code: Hubungkan fungsi AAR ke JavaScript dengan Capacitor’s API.
5. Test secara menyeluruh: Gunakan debugger Android Studio untuk memastikan integrasi lancar.

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

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

Persyaratan Pengaturan Pengembangan

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

Perangkat Lunak yang Diperlukan

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

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

• Platform Android SDK 33 (Android 13.0)
• Tools Pembangunan Android SDK 33.0.0
• Tools Perintah Baris Android SDK
• Emulator Android
• Tools Platform Android SDK

Langkah-Langkah Pengaturan Proyek

1. Mulai dengan membuat direktori baru dengan struktur sebagai berikut:

Tetapkan Pengaturan Android Studio

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

2. Luncurkan Android Studio dan atur pengaturan-pengaturan berikut:

Luncurkan Android Studio dan atur pengaturan-pengaturan berikut:

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

3. Siapkan Struktur Plugin Anda

Update file ini dengan pengaturan ini untuk mendukung file AAR: android/build.gradle Siapkan Kontrol Versi

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

4. Inisialisasi Git di direktori proyek Anda dan buat file untuk menghapus file yang tidak perlu. Berikut contoh:

Setelah langkah-langkah ini selesai, Anda akan siap untuk melanjutkan dengan menambahkan file AAR. .gitignore Menambahkan File AAR ke Plugin Anda .gitignore:

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

Mendapatkan File AAR

Mendapatkan File AAR

Menambahkan File AAR ke Plugin Anda

File-file AAR dapat berasal dari SDK pihak ketiga, library kustom, atau dependensi Maven. Sebaiknya, catat sumber, versi, dan tujuan mereka dalam sebuah README __CAPGO_KEEP_0__ libs dokumen yang berada di

Setelah Anda siapkan file-file AAR dan mendokumentasinya, Anda dapat mengonfigurasi plugin Anda untuk menyertakannya.

Mengatur File Plugin

Susun file-file plugin Anda untuk memastikan integrasi AAR yang lancar. 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 di android/libs dari plugin Anda 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 file untuk dependensi lainnya: dependencies.gradle Mengatur file vendor khusus ke subdirektori untuk pengelolaan yang lebih baik:

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

• Mengatur file konfigurasi di subdirektori vendor membantu menjaga organisasi dan menghindari konflik pembangunan saat bekerja dengan dependensi AAR multiple.

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

Gradle

Langkah-Langkah Konfigurasi Gradle Build Tool Interface

Untuk mengintegrasikan file AAR ke dalam plugin __CAPGO_KEEP_0__ Anda, Anda perlu mengonfigurasi Gradle dengan tepat. Mulai dengan menambahkan pengaturan repository ini ke

To integrate AAR files into your Capacitor plugin, you need to configure Gradle appropriately. Start by adding these repository settings to android/build.gradle:

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

block: dependencies Untuk pengelolaan versi yang lebih baik, buat

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

subdirektori gradle.properties file di root proyek Anda dan tentukan 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 membuat perubahan-perubahan ini, sinkronkan proyek Anda untuk menerapkan perubahan-perubahan tersebut.

Jalankan Gradle Sync

Buka proyek Anda di Android Studio dan tunggu sampai Gradle sinkronisasi secara otomatis. Jika tidak, klik tombol "Sinkronkan Proyek dengan File Gradle" di toolbar.

Setelah sinkronisasi, verifikasi hal-hal berikut:

Jika sinkronisasi gagal, periksa kembali konfigurasi Anda. Misalnya, pastikan pengaturan-pengaturan berikut 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 harus sudah terintegrasi sepenuhnya dan siap untuk diuji.

Menghubungkan Fitur AAR ke Capacitor

Menggambar Kelas Plugin

Setelah file Gradle Anda disinkronisasi, saatnya untuk menghubungkan fungsi AAR dengan mengembangkan kelas Plugin Langkah ini menghubungkan JavaScript dengan Android 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 pengandaian. 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 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-tipe umum dikonversi antara JavaScript dan Java:

Untuk membersihkan sumber daya, override metode: handleOnDestroy __CAPGO_KEEP_0__

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

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

Menguji dan Mengatasi Masalah

Menggunakan Debug di Android Studio

Untuk mengdebug integrasi AAR Anda di Android Studio, mulai dengan mengaktifkan mode debug di proyek Anda’s build.gradle __CAPGO_KEEP_0__

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

Tambahkan titik henti di metode-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 debugging tidak dapat menyelesaikan masalah, 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 Ketergantungan

Periksa konflik versi pada file Anda. Anda dapat memaksakan versi tertentu untuk menyelesaikan konflik: build.gradle 2. Libray Native Hilang

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 4. Masalah Penggabungan Manifest

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

5. Masalah Penggabungan Manifest

Jika Anda mengalami konflik manifest, masukkan hal-hal berikut dalam file Anda untuk mengatasi library yang bermasalah: AndroidManifest.xml 4. Kecelakaan Runtime dan Pengelolaan Memori

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

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

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.

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

Ringkasan

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

To integrate AAR files into Capacitor plugins, you’ll need to set up the Android environment, place AAR files correctly, configure Gradle accurately, and test thoroughly.

Fase

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

Langkah-Langkah Selanjutnya

Untuk meningkatkan plugin Anda, fokus 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 konsistensi dengan Android API level 29–34.

• Strategi Pemeliharaan
  Automatisasi tes, kelola versi AAR dengan pengendalian versi, simpan catatan perubahan, dan atur laporan kesalahan untuk menangani masalah produksi.

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