Cara Menggunakan File AAR di Plugin-Plugin Capacitor

Ingin mengintegrasikan fitur Android ke dalam Capacitor aplikasi? Panduan ini menjelaskan cara menggunakan file AAR (Android Archive) dalam Capacitor plugin untuk menggabungkan fungsi Android native dengan aplikasi web cross-platform.

Poin Utama:

• Apa itu file AAR? Lampiran Android yang sudah dipaketkan yang berisi code, sumber daya, dan file native.
• Mengapa menggunakan mereka? File AAR memungkinkan code digunakan kembali, memudahkan perawatan, dan melindungi fitur properti.
• Apa yang dibutuhkan? Alat seperti Android Studio, Bagaimana cara mengintegrasikan?Tempatkan file-file AAR di konfigurasi Gradle, dan hubungkan ke __CAPGO_KEEP_0__ plugin.Langkah-Langkah Cepat:
• Siapkan lingkungan Anda: Pasang alat-alat yang diperlukan dan konfigurasi Android Studio. libs, configure Gradle, and connect them to Capacitor plugins.

Buat struktur yang jelas untuk

1. Gradle , dan
2. Node.js , plus pengaturan proyek yang tepat. Capacitor plugin.
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 Android Studio untuk memastikan integrasi lancar.

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

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

Persyaratan Pengaturan Pengembangan

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

Perangkat Lunak yang Diperlukan

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

Additionally, make sure the following components are included in your SDK Manager:

• Sistem Operasi Android SDK Versi 33 (Android 13.0)
• Tool Pembangun Android SDK Versi 33.0.0
• Tool Perintah Baris Android SDK
• Emulator Android
• Tool Sistem Operasi Android SDK

Langkah-Langkah Pengaturan Proyek

1. Mulai dengan Menginisialisasi Lingkungan Pengembangan Anda

Mulai dengan membuat direktori baru dengan struktur seperti ini:

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

2. Pengaturan Pengaturan Android Studio

Luncurkan Android Studio dan atur pengaturan-pengaturan berikut:

• Setel 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 dengan pengaturan ini untuk mendukung file AAR: android/build.gradle Set Up Pengendalian Versi

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

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

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

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

Mendapatkan File AAR

Getting AAR Files

Adding AAR Files to Your Plugin

AAR file dapat berasal dari SDK pihak ketiga, library khusus, atau dependensi Maven. Baiknya untuk mendokumentasikan sumber, versi, dan tujuan mereka dalam sebuah README berkas yang terletak di libs Jenis Sumber

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

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

• Pakai 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 sebuah dependencies.gradle file untuk dependensi lainnya:

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

• Organisir file vendor khusus ke subdirektori untuk manajemen yang lebih baik:

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

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

Gradle Langkah-Langkah Konfigurasi

Mengupdate build.gradle

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

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

Kemudian, 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 manajemen versi yang lebih baik, buat sebuah 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 membuat perubahan ini, sinkronkan proyek Anda untuk menerapkan perubahan tersebut.

Menggunakan 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 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 AAR Anda seharusnya sudah terintegrasi sepenuhnya dan siap untuk diuji.

Menyambungkan Fitur AAR ke Capacitor

Membuat Kelas Plugin

Setelah file Gradle Anda disinkronisasi, saatnya untuk menghubungkan fungsi AAR dengan mengembangkan kelas Plugin class. This step links JavaScript to the native 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());
    }
}

Untuk menginisialisasi library AAR, Anda memerlukan:

Membuat Metode Plugin

Selanjutnya, definisikan metode dalam plugin menggunakan @PluginMethod annotasi. 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 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 metode:

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

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

Pengujian dan Mengatasi Masalah

Pengujian di Studio Android

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

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

Penggunaan Panel Debug di Studio Android untuk memantau area kunci:

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

Langkah-Langkah Troubleshooting

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

1. Konflik Dependensi

Periksa konflik versi di file Anda. Anda dapat memaksa versi tertentu untuk menyelesaikan konflik: build.gradle 2. Kurangnya Library Nativ

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 __CAPGO_KEEP_0__

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

__CAPGO_KEEP_1__

Jika Anda mengalami konflik manifest, masukkan hal-hal berikut ke 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>

Pakai tab Performance di Android Studio untuk memantau stabilitas runtime. Untuk masalah inisialisasi, tangani exception 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

Tidak ada crash waktu eksekusi

Langkah Selanjutnya

Mengoptimalkan plugin Anda, fokuslah pada hal-hal berikut:

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

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

• Strategi Pemeliharaan
  Lakukan tes otomatis, kelola versi AAR dengan kontrol 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 batasan platform. Hal ini akan membuatnya lebih mudah bagi pengembang lain untuk menerapkan dan menggunakan plugin Anda secara efektif.

Teruskan dari Cara Menggunakan File AAR di Capacitor Plugin

Jika Anda menggunakan Cara Menggunakan File AAR di Capacitor Plugin Dalam 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 Menambahkan atau Mengupdate Plugin untuk detail implementasi di Menambahkan atau Mengupdate Plugin, Alternatif Plugin Enterprise Ionic untuk alur kerja produk di Alternatif Plugin Enterprise Ionic, dan Capgo Pembangunan Native untuk alur kerja produk di Capgo Pembangunan Native.