Bagaimana Menggunakan File AAR di Plugin Capacitor

Inginkah Anda mengintegrasikan fitur Android ke aplikasi Anda? Capacitor app? Petunjuk ini menjelaskan cara menggunakan file AAR (Arsip Android) dalam plugin Capacitor. Bagaimana cara menggunakan file AAR (Arsip Android) di Capacitor plugins untuk menggabungkan fungsi Android native dengan aplikasi web multi-platform. Menggabungkan fungsi Android asli dengan aplikasi web lintas platform.

Apa itu file AAR?

• Apa itu file AAR? Perpustakaan Android yang sudah dikemas, berisi code, sumber daya, dan file native.
• Mengapa menggunakan mereka? AAR files enable code reuse, simplify maintenance, and protect proprietary features.
• Apa yang dibutuhkan? Alat seperti Studio Android, Gradle, dan Node.js, ditambah dengan pengaturan proyek yang tepat.
• Bagaimana cara mengintegrasikan? Tempatkan file AAR di libs, konfigurasi Gradle, dan hubungkan mereka ke Capacitor plugin.

Langkah-langkah cepat:

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

Melalui panduan ini, Anda dapat dengan mudah mengintegrasikan file AAR ke dalam Capacitor Anda, mengaktifkan kemampuan Android native untuk aplikasi web Anda.

Cara mengintegrasikan sebuah library Android (file AAR) ke dalam capacitor plugin

Persyaratan Pengaturan Pengembangan

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

Peralatan yang Diperlukan

Berikut adalah peralatan yang Anda butuhkan untuk bekerja dengan file AAR di Capacitor plugins:

Pastikan juga komponen-komponen berikut ada di Manajer SDK Anda.

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

Langkah-Langkah Pengaturan Proyek

1. Mulai Lingkungan Pengembangan Anda

Mulai dengan membuat direktori baru dengan struktur ini:

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

2. Konfigurasi Pengaturan Android Studio

Luncurkan Android Studio dan atur pengaturan berikut:

• Setel JDK Gradle ke versi 11 atau lebih tinggi.
• Dapatkan 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 berkas dengan pengaturan ini untuk termasuk dukungan file AAR:

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

4. Tetapkan Kontrol Versi

Buatlah Git di direktori proyek Anda dan buatlah sebuah .gitignore file untuk menghilangkan file yang tidak perlu. Contoh berikut .gitignore:

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

Setelah langkah-langkah ini selesai, Anda akan siap untuk melanjutkan ke penggunaan 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, catat sumber, versi, dan tujuan mereka dalam sebuah README berkas yang terletak di libs Jenis Sumber

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

Pengaturan File Plugin

Organisir 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/**/*"
    ]
}

Pengaturan File AAR

Untuk mengaktifkan fungsi AAR, tempatkan file di android/libs directory plugin Anda mengikuti langkah-langkah berikut:

• Menggunakan format penamaan yang jelas dan konsisten, seperti libraryname-version.aar.
• Manajemen versi dalam sebuah versions.properties file. Misalnya:

library1=1.2.3
library2=2.0.0

• Tambahkan dependencies.gradle file untuk ketergantungan lainnya:

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

• Mengorganisir file vendor ke dalam subdirektori untuk manajemen yang lebih baik:

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

Menggunakan subdirektori vendor untuk menyimpan file konfigurasi membantu menjaga organisasi dan menghindari konflik build ketika bekerja dengan beberapa ketergantungan AAR.

Gradle Langkah-Langkah Konfigurasi

Mengupdate build.gradle

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

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

Setelah itu, tambahkan 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 manajemen versi yang lebih baik, buatlah gradle.properties file di root project 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 seperti ini: android/build.gradle seperti ini:

android {
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }

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

Saat Anda telah membuat perubahan, sinkronkan proyek Anda untuk menerapkan perubahan tersebut.

Menggunakan Gradle Sync

Open your project in Android Studio and wait for Gradle to sync automatically. If it doesn’t start, click the “Sync Project with Gradle Files” button in the toolbar.

Setelah sinkronisasi, pastikan 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-file AAR yang besar, Anda mungkin perlu meningkatkan alokasi memori Gradle di gradle.properties:

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

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

Menghubungkan Fitur AAR ke Capacitor

Membuat Kelas Plugin

Saat file-file Gradle Anda sudah disinkronisasi, saatnya untuk menghubungkan fungsi AAR Anda dengan menambahkan ekstensi ke. Plugin kelas. Langkah ini menghubungkan JavaScript dengan 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 apa yang Anda butuhkan untuk menginisialisasi library AAR:

Membuat Metode Plugin

Selanjutnya, definisikan metode di plugin menggunakan @PluginMethod dekorasi. 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 yang perlu dijalankan 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 cara umum jenis-jenis yang 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.

Testing dan Mengatasi Masalah

Menggunakan Mode Debug di Menggunakan Android Studio

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

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

Tambahkan titik henti pada 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);
}

Menggunakan panel Debug di Android Studio untuk memantau area kunci:

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

Kerusakan Memori

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

Langkah-Langkah Troubleshooting

Periksa konflik versi di dalam proyek Anda build.gradle Anda dapat memaksa versi tertentu untuk menyelesaikan konflik:

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

2. Kurangnya Librerai Nama Lokal

Pastikan AAR mencakup file yang diperlukan .so file-file yang tepat di direktori-direktori seperti:

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

3. Masalah Penggabungan Manifest

Jika Anda mengalami konflik manifest, termasuklah hal-hal berikut dalam proyek Anda. 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>

4. Kecelakaan Waktu Jalannya dan Pengelolaan Memori

Gunakan tab Performance di Android Studio untuk memantau stabilitas waktu eksekusi. Untuk masalah inisialisasi, tangani kesalahan dengan hati-hati.

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

Pastikan memori tidak terleak dengan mengeluarkan sumber daya secara tepat. Gunakan Profiler Memori di Android Studio untuk mengikuti penggunaan heap dan mengidentifikasi apapun yang terleak.

Summary

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

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

Next Steps

Fokus pada hal-hal ini untuk meningkatkan plugin Anda:

• Mengoptimalkan plugin Anda, fokuslah pada area ini:
  Gunakan Profiler Studio Android untuk memantau penggunaan memori dan pastikan sumber daya dibersihkan dengan benar.

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

• Strategi Perawatan
  Automatisasi pengujian, mengelola versi AAR dengan kontrol versi, memelihara log perubahan, dan mengatur pelaporan kesalahan untuk menangani masalah produksi.

If you plan to share your plugin publicly, make sure to provide detailed documentation on AAR-specific setups and any platform limitations. This will make it easier for other developers to adopt and use your plugin effectively.

Teruskan dari Cara Menggunakan File AAR di Capacitor Plugin

Jika Anda menggunakan Cara Menggunakan File AAR di Capacitor Plugin untuk merencanakan pekerjaan plugin native, hubungkannya dengan Capgo Direktori Plugin untuk alur kerja produk di Capgo Direktori Plugin, Capacitor Plugin oleh Capgo untuk detail implementasi di Capacitor Plugin oleh Capgo, Tambahkan atau Perbarui Plugin untuk detail implementasi di Tambahkan atau Perbarui Plugin, Ganti Alternatif Plugin Enterprise Ionic untuk alur kerja produk di Ganti Alternatif Plugin Enterprise Ionic, dan Capgo Pembangunan Natively untuk alur kerja produk di Capgo Pembangunan Natively.