Come utilizzare i file AAR nei plugin Capacitor

Vuoi integrare funzionalità Android nella tua Capacitor app? Questa guida spiega come utilizzare i file AAR (Archivio Android) nei plugin __CAPGO_KEEP_0__ Capacitor plugins Come utilizzare i file AAR nei plugin __CAPGO_KEEP_0__

Evidenze chiave:

• Cosa sono i file AAR? Illeggi precompilate per Android che contengono code, risorse e file nativi.
• Perché usarli? I file AAR consentono il riutilizzo di code, semplificano la manutenzione e proteggono le funzionalità proprietarie.
• Cosa è richiesto? Gli strumenti come Android Studio, Gradle, e Node.js, più una configurazione del progetto corretta.
• How to integrate? Colloca i file AAR in libs, configura Gradle e collega loro ai plugin Capacitor.

Passaggi veloci:

1. Configura il tuo ambiente: Installa gli strumenti richiesti e configura Android Studio.
2. Organizza il tuo progetto: Creare una struttura chiara per il tuo Capacitor plugin.
3. Aggiungi i file AAR: Colloca loro in android/libs e aggiorna le dipendenze di Gradle.
4. Scrivi plugin code Collega la funzionalità AAR al JavaScript con Capacitor’s API.
5. Testa accuratamente: Utilizza il debugger di Android Studio per garantire un'integrazione liscia.

Seguendo questa guida, puoi incorporare in modo trasparente i file AAR nei tuoi plugin Capacitor, sbloccando le capacità Android native per le tue app web.

Come embeddare una libreria Android (file AAR) in un capacitor plugin

Requisiti di configurazione per lo sviluppo

Prima di lavorare con i file AAR, assicurati che il tuo ambiente di sviluppo sia configurato correttamente per evitare qualsiasi problema.

Software richiesto

Ecco lo software che avrai bisogno per lavorare con i file AAR nei plugin Capacitor:

Inoltre, assicurati che i seguenti componenti siano inclusi nel tuo SDK Manager:

• Piattaforma Android SDK 33 (Android 13.0)
• Strumenti di costruzione Android SDK 33.0.0
• Strumenti per la riga di comando Android SDK
• Emulatore Android
• Piattaforma strumenti Android SDK

Passaggi di configurazione del progetto

1. Inizia configurando il tuo ambiente di sviluppo

Inizia creando un nuovo directory con questa struttura:

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

2. Configura le impostazioni di Android Studio

Avvia Android Studio e regola le seguenti impostazioni:

• Imposta il JDK di Gradle alla versione 11 o superiore.
• Abilita la funzione di download automatico per i componenti Android SDK.
• Aggiorna le variabili di ambiente del sistema con la corretta percorso di Android SDK.

3. Prepara la struttura del tuo plugin

Aggiorna il file con questi impostazioni per includere il supporto per i file AAR: android/build.gradle Configura il Controllo delle Versioni

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

4. Avvia Git nel tuo directory di progetto e crea un

file per escludere file non necessari. Ecco un esempio: .gitignore Una volta completate queste fasi, sarai pronto a passare all'aggiunta dei tuoi file AAR. .gitignore:

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

Aggiungere i File AAR al Tuo Plugin

Ottenere i File AAR

I file AAR possono provenire da SDK di terze parti, librerie personalizzate o dipendenze Maven. È una buona idea documentare la loro origine, versione e scopo in un

file ubicato nella README directory. libs Tipo di Origine

Una volta pronte e documentate le tue AAR, puoi configurare il tuo plugin per includerle.

Configurazione dei File del Plugin

Organizza i file del tuo plugin per garantire un'integrazione liscia delle dipendenze AAR. Ecco un esempio di come la struttura del tuo plugin potrebbe essere:

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

Posizionamento del File AAR

Per abilitare la funzionalità AAR, posiziona i file nella android/libs directory del tuo plugin seguendo questi passaggi:

• Utilizza un formato di denominazione chiaro e coerente, come libraryname-version.aar.
• Gestisci le versioni in un versions.properties file. Ad esempio:

library1=1.2.3
library2=2.0.0

• Aggiungi un dependencies.gradle file per altre dipendenze:

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

• Organizza i file specifici del fornitore in sottodirectory per una gestione migliore:

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

Tenere i file di configurazione nelle sottodirectory specifiche del fornitore aiuta a mantenere l'organizzazione e a evitare conflitti di build quando si lavora con più dipendenze AAR.

Gradle Passaggi di configurazione

Aggiornamento di build.gradle

Per integrare i file AAR nel tuo plugin Capacitor, è necessario configurare Gradle in modo appropriato. Inizia aggiungendo questi impostazioni di repository: android/build.gradle:

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

Quindi, includi le dipendenze AAR nel dependencies blocco:

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

Per una gestione delle versioni migliore, crea un gradle.properties file nella cartella root del tuo progetto e definisci le versioni delle tue librerie:

# Library versions
MY_LIBRARY_VERSION=1.2.3
CAPACITOR_VERSION=5.5.0

Se il file AAR include dipendenze aggiuntive, dichiarale nel android/build.gradle come segue:

android {
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }

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

Una volta apportate queste modifiche, sincronizza il tuo progetto per applicarle.

Esegui il sincronizzazione di Gradle

Apre il tuo progetto in Android Studio e attendi che Gradle sincronizzi automaticamente. Se non inizia, clicca sul pulsante "Sincronizza progetto con file Gradle" nella barra degli strumenti.

Dopo aver sincronizzato, verifica i seguenti punti:

Se il sincronizzazione fallisce, controlla nuovamente la tua configurazione. Ad esempio, assicurati che questi impostazioni siano presenti:

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

    lintOptions {
        abortOnError false
    }
}

Per grandi file AAR, potresti dover aumentare l'allocazione di memoria di Gradle in gradle.properties:

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

Una volta completata con successo la sincronizzazione, i tuoi file AAR dovrebbero essere completamente integrati e pronti per il testing.

Collegamento delle funzionalità AAR a Capacitor

Scrivere la classe del Plugin

Una volta sincronizzati i file Gradle, è tempo di collegare la tua funzionalità AAR estendendo la Plugin class. Questo passaggio collega JavaScript alla Android nativa 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());
    }
}

Ecco cosa ti serve per inizializzare la libreria AAR:

Creare Metodi Plugin

Successivamente, definisci metodi nel tuo plugin utilizzando l' @PluginMethod annotazione. Questi metodi gestiscono l'interscambio di dati tra JavaScript e 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);
    }
}

Per compiti che richiedono l'esecuzione in modo asincrono:

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

Il seguente è un elenco dei tipi comuni convertiti tra JavaScript e Java:

Per la pulizia delle risorse, sovrascrivi il handleOnDestroy metodo:

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

Con questi metodi in posizione, il tuo ponte nativo è pronto. Testa la tua implementazione nell'ambiente di debug di Android Studio per assicurarti che tutto funzioni come previsto.

Test e Risoluzione dei Problemi

Debugging in Studio Android

Per debuggare la tua integrazione AAR in Android Studio, inizia abilitando il debug nel progetto del tuo: build.gradle file:

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

Aggiungi i punti di interruzione nei metodi del tuo plugin per tracciare il flusso dei dati e identificare potenziali problemi:

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

Utilizza il pannello Debug in Android Studio per monitorare le aree chiave:

Se la debug non risolve il problema, segui i passaggi di risoluzione dei problemi nella sezione successiva.

Passaggi di risoluzione dei problemi

Quando il debug singolo non è sufficiente, utilizza questi passaggi per risolvere i problemi comuni:

1. Conflitti di dipendenza

Controlla i conflitti di versione nei tuoi build.gradle file. Puoi forzare versioni specifiche per risolvere i conflitti:

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

2. Librerie native mancanti

Assicurati che il file AAR includa i file richiesti .so nei directory appropriati, ad esempio:

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

3. Problemi di fusione del manifesto

Se incontri conflitti di manifesto, include i seguenti nel tuo AndroidManifest.xml file per sovrascrivere le librerie problematiche:

<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. Crashes di runtime e gestione della memoria

Utilizza la scheda Performance in Android Studio per monitorare la stabilità di runtime. Per i problemi di inizializzazione, gestisci le eccezioni con cura:

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

To prevenire le perdite di memoria, assicurati che le risorse vengano rilasciate correttamente. Utilizza il Profilo della Memoria in Android Studio per tracciare l'uso della pila e identificare eventuali perdite.

Riepilogo

Per integrare i file AAR nei plugin Capacitor, avrai bisogno di configurare l'ambiente Android, posizionare i file AAR correttamente, configurare Gradle con precisione e testare accuratamente.

Fasi di Implementazione Chiave

Una volta padroneggiati questi concetti base, potrai esplorare tecniche più avanzate.

Passaggi successivi

Per migliorare il tuo plugin, concentra i tuoi sforzi su queste aree:

• Optimizzazione delle prestazioni
  Utilizza il profiler di Android Studio per monitorare l'uso della memoria e assicurarti che le risorse vengano pulite correttamente.

• Distribuzione Preparazione
  Documenta tutte le configurazioni AAR, generare la API documentazione e testare la compatibilità con i livelli Android API 29–34.

• Strategia di Manutenzione
  Automatizzare i test, gestire le versioni AAR con il controllo delle versioni, mantenere un changelog e configurare il reporting degli errori per affrontare le questioni di produzione.

Se hai l'intenzione di condividere il tuo plugin pubblicamente, assicurati di fornire una documentazione dettagliata sulle impostazioni AAR specifiche e su eventuali limitazioni di piattaforma. Ciò renderà più facile per gli altri sviluppatori adottare e utilizzare il tuo plugin in modo efficace.

Continua da Come utilizzare i file AAR in Capacitor Plugin

Se stai utilizzando Come utilizzare i file AAR in Capacitor Plugin per pianificare il lavoro di plugin nativo, connettilo con Capgo Directory dei Plugin per il flusso di lavoro del prodotto in Capgo Directory dei Plugin, Capacitor Plugin da Capgo per i dettagli di implementazione nei plugin Capacitor di Capgo, Aggiunta o Aggiornamento dei Plugin per i dettagli di implementazione in Aggiunta o Aggiornamento dei Plugin, Sostituti dei Plugin Enterprise di Ionic per il workflow del prodotto in Sostituti dei Plugin Enterprise di Ionic, e Capgo Build Nativi per il workflow del prodotto in Capgo Build Nativi.