Come usare i file AAR nei plugin Capacitor

Vuoi integrare funzionalità Android nella tua Capacitor app? Questa guida spiega come usare i file AAR (Android Archive) nei plugin Capacitor per combinare funzionalità native Android con web app cross-platform.

Punti chiave:

• Cosa sono i file AAR? Librerie Android pre-impacchettate che contengono code, risorse e file nativi.
• Perché usarli? I file AAR permettono il riutilizzo di code, semplificano la manutenzione e proteggono le funzionalità proprietarie.
• What’s required? Strumenti come Android Studio, Gradle, e Node.js, oltre a un setup corretto del progetto.
• Come integrarli? Inserisci i file AAR in libs, configura Gradle e collegali ai plugin Capacitor.

Passaggi rapidi:

1. Configura l'ambiente: Installa gli strumenti necessari e configura Android Studio.
2. Organizza il progetto: Crea una struttura chiara per il tuo plugin Capacitor.
3. Aggiungi i file AAR: Inseriscili in android/libs e aggiorna le dipendenze Gradle.
4. Scrivi il plugin code: Collega le funzionalità AAR a JavaScript con API di Capacitor.
5. Testa a fondo: Usa il debugger di Android Studio per garantire un'integrazione fluida.

Seguendo questa guida, potrai integrare senza problemi i file AAR nei tuoi plugin Capacitor, sbloccando le capacità native Android per le tue web app.

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

Requisiti per il setup di sviluppo

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

Software richiesto

Ecco il software necessario per gestire 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)
• Android SDK Build-Tools 33.0.0
• Strumenti da riga di comando Android SDK
• Emulatore Android
• Strumenti della piattaforma Android SDK

Passaggi per il setup del progetto

1. Inizializza il tuo ambiente di sviluppo

Inizia creando una nuova 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 Gradle JDK alla versione 11 o superiore.
• Abilita l'auto-download per i componenti Android SDK.
• Aggiorna le variabili d'ambiente con il percorso Android SDK corretto.

3. Prepara la struttura del tuo plugin

Aggiorna il file android/build.gradle file con queste impostazioni per includere il supporto ai file AAR:

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

4. Configura il Version Control

Inizializza Git nella directory del progetto e crea un .gitignore file per escludere i file non necessari. Ecco un esempio di .gitignore:

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

Una volta completati questi passaggi, potrai procedere con l'aggiunta dei tuoi file AAR.

Aggiungere file AAR al tuo plugin

Ottenere i file AAR

I file AAR possono provenire da SDK di terze parti, librerie custom o dipendenze Maven. È consigliabile documentarne la sorgente, la versione e lo scopo in un README file situato nella directory libs directory.

Una volta pronti e documentati i file AAR, puoi configurare il tuo plugin per includerli.

Configurazione dei file del plugin

Organizza i file del tuo plugin per garantire un'integrazione fluida delle dipendenze AAR. Ecco un esempio della struttura del plugin:

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, inserisci i file nella android/libs directory del tuo plugin seguendo questi passaggi:

• Usa 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 le altre dipendenze:

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

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

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

Mantenere i file di configurazione in sottodirectory specifiche del vendor aiuta l'organizzazione ed evita 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, devi configurare correttamente Gradle. Inizia aggiungendo queste impostazioni del repository a android/build.gradle:

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

Successivamente, 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 migliore gestione delle versioni, crea un gradle.properties file nella root del progetto e definisci le versioni delle librerie:

# Library versions
MY_LIBRARY_VERSION=1.2.3
CAPACITOR_VERSION=5.5.0

Se il file AAR include dipendenze aggiuntive, dichiarale in android/build.gradle in questo modo:

android {
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }

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

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

Esecuzione della Gradle Sync

Apri il progetto in Android Studio e attendi che Gradle completi la sincronizzazione automatica. Se non parte, clicca sul pulsante “Sync Project with Gradle Files” nella toolbar.

Dopo la sincronizzazione, verifica quanto segue:

Se la sincronizzazione fallisce, ricontrolla la configurazione. Ad esempio, assicurati che queste impostazioni siano presenti:

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

    lintOptions {
        abortOnError false
    }
}

Per i file AAR di grandi dimensioni, potresti dover aumentare la memoria allocata a Gradle in gradle.properties:

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

Una volta completata correttamente la sincronizzazione, i tuoi file AAR dovrebbero essere completamente integrati e pronti per i test.

Collegare le funzionalità AAR a Capacitor

Scrittura della classe Plugin

Dopo aver sincronizzato i file Gradle, è il momento di collegare la funzionalità AAR estendendo la Plugin classe. Questo passaggio collega JavaScript al code nativo di Android.

@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 serve per inizializzare la libreria AAR:

Creazione dei metodi del plugin

Successivamente, definisci i metodi nel tuo plugin usando il @PluginMethod Questi metodi gestiscono lo scambio 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 i task che devono essere eseguiti 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 vengono convertiti i tipi comuni 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 implementati, il tuo bridge nativo è pronto. Testa la tua implementazione nell'ambiente di debug di Android Studio per assicurarti che tutto funzioni correttamente.

Test e risoluzione dei problemi

Debugging in Android Studio

Per fare il debug dell'integrazione AAR in Android Studio, inizia abilitando la debug mode nel file build.gradle file:

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

Aggiungi dei breakpoint nei metodi del tuo plugin per tracciare il flusso dei dati e identificare eventuali 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);
}

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

Se il debugging non risolve il problema, segui i passaggi di troubleshooting nella sezione successiva.

Passaggi di Troubleshooting

Quando il debugging da solo non basta, segui questi passaggi per risolvere i problemi comuni:

1. Conflitti di dipendenze

Controlla eventuali conflitti di versione nel tuo 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 l'AAR includa i .so file necessari nelle directory corrette, come:

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

3. Problemi di Manifest Merger

Se riscontri conflitti nel manifest, aggiungi quanto segue al 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. Crash a runtime e gestione della memoria

Usa la tab Performance di Android Studio per monitorare la stabilità a runtime. Per 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;
}

Per evitare memory leak, assicurati che le risorse vengano rilasciate correttamente. Usa il Memory Profiler di Android Studio per monitorare l'uso dell'heap e identificare eventuali leak.

Riassunto

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

Fasi chiave dell'implementazione

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

Prossimi passi

Per migliorare il tuo plugin, concentrati su questi aspetti:

• Ottimizzazione delle Performance
  Usa il profiler di Android Studio per monitorare l'uso della memoria e assicurarti che le risorse siano rilasciate correttamente.

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

• Strategia di Manutenzione
  Automatizza i test, gestisci le versioni AAR con il version control, mantieni un changelog e imposta il reporting degli errori per risolvere i problemi in produzione.

Se intendi condividere il tuo plugin pubblicamente, assicurati di fornire una documentazione dettagliata sulle configurazioni AAR e su eventuali limitazioni della piattaforma. Questo faciliterà l'adozione e l'uso efficace del tuo plugin da parte di altri sviluppatori.

Continua da Come Usare i File AAR nei Plugin Capacitor

Se stai usando Come Usare i File AAR nei Plugin Capacitor per pianificare il lavoro sui plugin nativi, collegalo a Directory dei plugin Capgo per il workflow del prodotto nella Directory dei plugin Capgo, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins by Capgo, Aggiungere o aggiornare i plugin per i dettagli di implementazione in Adding or Updating Plugins, Alternative ai plugin Ionic Enterprise per il workflow del prodotto in Ionic Enterprise Plugin Alternatives, e Capgo Native Build per il workflow del prodotto in Capgo Native Builds.