Come utilizzare i file AAR nei plugin di Capacitor

Vuoi integrare funzionalità Android nel tuo Capacitor questo guide spiega come utilizzare i file AAR (Archivio Android) nei plugin di Capacitor Capacitor plugins Chiavi di apprendimento:

Cosa sono i file AAR?

• Le librerie Android preconfezionate contenenti Pre-packaged Android libraries containing code, resources, and native files.
• Perché usarli? AAR files enable code reuse, simplify maintenance, and protect proprietary features.
• risorse, semplificano la manutenzione e proteggono le funzionalità proprietarie. Strumenti come Android Studio, Gradle, e Node.js, più una corretta configurazione del progetto.
• Come integrare? Collega i file AAR in libsconfigura 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 file AAR: Colloca loro in android/libs e aggiorna le dipendenze di Gradle.
4. Scrivi il plugin code: Collega la funzionalità AAR al JavaScript con Capacitor’s API.
5. Testa accuratamente: Utilizza il debugger di Android Studio per assicurare un'integrazione liscia.

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

How to embed an Android library (AAR file) into un capacitor plugin

Requisiti di configurazione del setup di sviluppo

Prima di lavorare con i file AAR, assicurati di avere un ambiente di sviluppo configurato correttamente per evitare problemi.

Software richiesto

Ecco il software di cui avrai bisogno per lavorare con i file AAR nei plugin Capacitor:

Inoltre, assicurati di includere i seguenti componenti nel tuo SDK Manager:

• Piattaforma Android SDK 33 (Android 13.0)
• Strumenti di costruzione Android SDK 33.0.0
• Strumenti di riga di comando Android SDK
• Emulatore Android
• Strumenti di piattaforma Android SDK

Istruzioni per la configurazione del progetto

1. Istruzioni per l'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

Lancia 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 queste impostazioni per includere il supporto dei file AAR: android/build.gradle Configura il Controllo delle Versioni

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

4. Inizializza Git nel tuo directory di progetto e crea un file per escludere file non necessari. Ecco un esempio:

Una volta completate queste fasi, sarai pronto a passare all'aggiunta dei tuoi file AAR. .gitignore Aggiorna il file con queste impostazioni per includere il supporto dei file AAR: .gitignore:

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

Aggiorna il file con queste impostazioni per includere il supporto dei file AAR:

Aggiungere file AAR al tuo plugin

Ottenere file AAR

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

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

Configurazione dei file del plugin

Organizza i tuoi file del plugin per garantire un'integrazione liscia delle dipendenze AAR. Ecco un esempio di come la tua struttura del 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 dei 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.
• gestire le versioni in un versions.properties file. Ad esempio:

library1=1.2.3
library2=2.0.0

• aggiungere un dependencies.gradle file per altre dipendenze:

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

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

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

mantenere i file di configurazione nelle sottodirectory specifiche del fornitore aiuta a mantenere l'organizzazione e evita i conflitti di costruzione 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 a android/build.gradle:

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

Quindi, includi le dipendenze AAR nel dependencies block:

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 file nella cartella root del tuo progetto e definisci le versioni delle tue librerie: gradle.properties Se il file AAR viene fornito con dipendenze aggiuntive, dichiarale in questo modo:

# Library versions
MY_LIBRARY_VERSION=1.2.3
CAPACITOR_VERSION=5.5.0

Una volta apportate queste modifiche, sincronizza il tuo progetto per applicarle. android/build.gradle Esecuzione di Sync Gradle

android {
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }

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

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

Punto di controllo

Risultato previsto

Se la sincronizzazione fallisce, verificare nuovamente la configurazione. Ad esempio, assicurarsi che questi impostazioni siano presenti:

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

    lintOptions {
        abortOnError false
    }
}

Per grandi file AAR, potrebbe essere necessario aumentare l'allocazione di memoria di Gradle in gradle.properties:

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

Una volta completata la sincronizzazione con successo, i file AAR dovrebbero essere completamente integrati e pronti per le prove.

Connettere le funzionalità AAR a Capacitor

Scrivere la classe del plugin

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

Ecco cosa ti serve per inizializzare la libreria AAR:

Crea metodi della plugin

Successivamente, definisci metodi nella tua 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 le attività 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);
        }
    });
}

Ecco come i tipi comuni vengono convertiti tra JavaScript e Java:

Per la pulizia delle risorse, sovrascrivi il metodo: 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.

Testing e Risoluzione dei Problemi

Debugging in Android Studio

Per debuggare l'integrazione AAR nel tuo progetto di Android Studio, inizia abilitando il debug nel file: build.gradle Aggiungi breakpoint nei metodi del tuo plugin per tracciare il flusso dei dati e identificare potenziali problemi:

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

Boolean

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

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

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

Passaggi di Risoluzione dei Problemi

Quando il debug da solo 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. Biblioteche native mancanti

Assicurati che l'AAR includa le librerie native richieste .so file in cartelle appropriate, ad esempio:

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

3. Problemi di Merge del Manifesto

Se si verificano conflitti di manifesto, includere i seguenti nel proprio AndroidManifest.xml file per sovrascrivere 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 e Gestione della Memoria

Utilizzare la scheda di prestazioni in Android Studio per monitorare la stabilità in esecuzione. Per problemi di inizializzazione, gestire le eccezioni con cura:

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

Per prevenire le perdite di memoria, assicurarsi che le risorse vengano rilasciate correttamente. Utilizzare il Profilo della Memoria in Android Studio per tracciare l'uso della memoria e identificare eventuali perdite.

Riepilogo

Per integrare i file AAR nei plugin Capacitor, sarà necessario configurare l'ambiente Android, posizionare i file AAR correttamente, configurare Gradle con precisione e testare accuratamente.

Fasi di Implementazione Chiave

Una volta che avrai padroneggiato queste basi, potrai esplorare tecniche più avanzate.

Passaggi successivi

Per migliorare il tuo plugin, concentra l'attenzione 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.

• Preparazione della distribuzione
  Documenta tutte le configurazioni AAR, genera API documentazione e testa la compatibilità con i livelli Android API 29–34.

• Strategia di manutenzione
  Automatizza i test, gestisci le versioni AAR con il controllo delle versioni, mantiene un changelog e configura il reporting degli errori per affrontare le problematiche in 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 del sistema. Ciò renderà più facile per gli altri sviluppatori adottare e utilizzare il tuo plugin in modo efficace.

Continua da Come utilizzare i file AAR nei plugin Capacitor

If sei stai utilizzando Come utilizzare i file AAR nei plugin Capacitor per pianificare il lavoro sui plugin nativi, connettilo con il Capgo Directory dei plugin per il flusso di lavoro del prodotto nel Capgo Directory dei plugin, Capacitor Plugins da Capgo per i dettagli di implementazione in Capacitor Plugins da Capgo Aggiungere o Aggiornare i plugin per i dettagli di implementazione in Aggiungere o Aggiornare i plugin Sostituti dei plugin Enterprise di Ionic per il flusso di lavoro del prodotto in Sostituti dei plugin Enterprise di Ionic, e Capgo Costruzioni native per il workflow del prodotto in Capgo Costruzioni native.