How to Use AAR Files in Capacitor Plugins

Möchten Sie Android-Funktionen in Ihre Capacitor app? Diese Anleitung erklärt, wie Sie AAR-Dateien (Android Archive) in Capacitor-Plugins zur Kombination von nativen Android-Funktionen mit cross-plattformigen Web-Anwendungen verwenden.

Hauptergebnisse:

• Was sind AAR-Dateien? Vorverpackte Android-Bibliotheken, die code, Ressourcen und native Dateien enthalten.
• Warum sollten Sie sie verwenden? AAR-Dateien ermöglichen die code-Wiederverwendung, vereinfachen die Wartung und schützen geheime Funktionen.
• Was ist erforderlich? Tools wie Android Studio, Gradle, und Node.js, sowie eine ordnungsgemäße Projektierung.
• Wie kann ich integrieren? Legen Sie AAR-Dateien in libs, konfigurieren Sie Gradle und verbinden Sie sie mit Capacitor-Plugins.

Schnelle Schritte:

1. Konfigurieren Sie Ihr Umfeld: Installieren Sie erforderliche Tools und konfigurieren Sie Android Studio.
2. Organisieren Sie Ihr Projekt: Erstellen Sie eine klare Struktur für Ihre Capacitor Plugin.
3. AAR-Dateien hinzufügen: Platzieren Sie sie in android/libs und aktualisieren Sie die Gradle-Abhängigkeiten.
4. Schreiben Sie den Plugin-Code für code: Verbinden Sie die AAR-Funktionalität mit JavaScript mit Capacitor’s API.
5. Sorgfältig testen: Verwenden Sie Android Studios Debugger, um eine glatte Integration sicherzustellen.

Durch die Befolgung dieser Anleitung können Sie AAR-Dateien in Ihren Capacitor-Plugins einbetten, was Ihnen Zugriff auf native Android-Funktionen für Ihre Web-Anwendungen ermöglicht.

Wie Sie eine Android-Bibliothek (AAR-Datei) in ein capacitor Plugin

Entwicklungs-Setup-Anforderungen

Bevor Sie mit AAR-Dateien arbeiten, stellen Sie sicher, dass Ihre Entwicklungsumgebung ordnungsgemäß konfiguriert ist, um eventuelle Probleme zu vermeiden.

Erforderliche Software

Hier ist die Software, die Sie zum Arbeiten mit AAR-Dateien in Capacitor-Plugins benötigen:

Zusätzlich stellen Sie sicher, dass die folgenden Komponenten in Ihrem SDK Manager enthalten sind:

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

Projekt-Einrichtungs-Schritte

1. Initialisieren Sie Ihre Entwicklungsumgebung

Beginnen Sie mit der Erstellung eines neuen Verzeichnisses mit dieser Struktur:

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

2. Konfigurieren Sie die Einstellungen von Android Studio

Starten Sie Android Studio und passen Sie die folgenden Einstellungen an:

• Stellen Sie die Gradle JDK auf Version 11 oder höher ein.
• Aktivieren Sie die automatische Herunterladen-Funktion für Android SDK-Komponenten.
• Passen Sie Ihre Systemumgebungsvariablen mit dem korrekten Android SDK-Pfad an.

3. Vorbereiten Sie Ihre Plugin-Struktur.

Update das android/build.gradle Datei mit diesen Einstellungen, um die Unterstützung für AAR-Dateien einzuschließen:

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

4. Einrichten Sie die Versionskontrolle.

Initialisieren Sie Git in Ihrem Projektverzeichnis und erstellen Sie eine .gitignore Datei, um unnötige Dateien auszuschließen. Hier ist ein Beispiel .gitignore:

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

Wenn diese Schritte abgeschlossen sind, sind Sie bereit, Ihre AAR-Dateien hinzuzufügen.

Hinzufügen von AAR-Dateien zu Ihrem Plugin.

AAR-Dateien hinzufügen

AAR-Dateien können aus drittbezogenen SDKs, benutzerdefinierten Bibliotheken oder Maven-Abhängigkeiten stammen. Es ist eine gute Idee, ihre Quelle, Version und Zweck in einem README verzeichnis zu dokumentieren. libs Quelltyp

Stellen Sie Ihre AAR-Dateien so ein, dass sie bereit und dokumentiert sind, und konfigurieren Sie Ihren Plugin, um sie zu integrieren.

Einstellungen für Plugin-Dateien

Organisieren Sie Ihre Plugin-Dateien, um eine glatte Integration von AAR-Abhängigkeiten zu gewährleisten. Hier ist ein Beispiel dafür, wie Ihre Plugin-Struktur aussehen könnte:

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

AAR-Datei-Platzierung

Um die AAR-Funktion zu aktivieren, legen Sie die Dateien in das android/libs Verzeichnis Ihres Plugins an, indem Sie diese Schritte befolgen:

• Verwenden Sie ein klares und konsistentes Namensformat, wie zum Beispiel libraryname-version.aar.
• Verwalten Sie Versionen in einem versions.properties Datei. Zum Beispiel:

library1=1.2.3
library2=2.0.0

• Ein Datei für andere Abhängigkeiten hinzufügen: dependencies.gradle Dateien für andere Abhängigkeiten hinzufügen:

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

• Organisieren Sie die Hersteller-spezifischen Dateien in Unterordnern für eine bessere Verwaltung:

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

Die Konfigurationsdateien in Hersteller-spezifischen Unterordnern zu halten hilft, die Organisation aufrechtzuerhalten und vermeidet Konflikte bei der Erstellung, wenn Sie mit mehreren AAR-Abhängigkeiten arbeiten.

Gradle KonfigurationsSchritte

Die build.gradle aktualisieren

To integrate AAR files into your Capacitor plugin, you need to configure Gradle appropriately. Start by adding these repository settings to android/build.gradle:

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

Dann fügen Sie die AAR-Abhängigkeiten in der 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"
}

Für eine bessere Versionsverwaltung erstellen Sie einen gradle.properties Datei in Ihrem Projektroot und definieren Sie Ihre Bibliotheksversionen:

# Library versions
MY_LIBRARY_VERSION=1.2.3
CAPACITOR_VERSION=5.5.0

Wenn das AAR-File zusätzliche Abhängigkeiten enthält, deklarieren Sie sie in android/build.gradle wie folgt:

android {
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }

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

Sobald Sie diese Änderungen vorgenommen haben, synchronisieren Sie Ihr Projekt, um sie anzuwenden.

Gradle Sync ausführen

Öffnen Sie Ihr Projekt in Android Studio und warten Sie, bis Gradle automatisch synchronisiert. Wenn es nicht startet, klicken Sie auf die Schaltfläche "Synchronisieren Sie das Projekt mit den Gradle-Dateien" in der Werkzeugleiste.

Nach der Synchronisierung überprüfen Sie Folgendes:

Wenn der Synchronisierungsprozess fehlschlägt, überprüfen Sie bitte Ihre Konfiguration. Zum Beispiel stellen Sie sicher, dass diese Einstellungen vorliegen:

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

    lintOptions {
        abortOnError false
    }
}

Für große AAR-Dateien müssen Sie möglicherweise die Gradle-Memory-Allokation erhöhen in gradle.properties:

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

Sobald der Synchronisierungsprozess erfolgreich abgeschlossen ist, sollten Ihre AAR-Dateien vollständig integriert und für die Testphase bereit sein.

AAR-Funktionen mit Capacitor verbinden

Die Plugin-Klasse schreiben

Sobald Ihre Gradle-Dateien synchronisiert sind, ist es Zeit, die AAR-Funktionen zu verbinden, indem Sie die Klasse erweitern. 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());
    }
}

Komponente

Erstellung von Plugin-Methode

Als nächstes definieren Sie Methoden in Ihrem Plugin mithilfe der @PluginMethod Anmerkung. Diese Methoden handhaben den Datenaustausch zwischen JavaScript und 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);
    }
}

Führen Sie Aufgaben aus, die asynchron ausgeführt werden müssen:

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

Hier ist die Umwandlung der gängigen Typen zwischen JavaScript und Java:

Für die Ressourcenaufreinigung überschreiben Sie die handleOnDestroy Methode:

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

Mit diesen Methoden ist Ihr Native-Bridge bereit. Testen Sie Ihre Implementierung im Debug-Modus von Android Studio, um sicherzustellen, dass alles wie erwartet funktioniert.

Testen und Probleme beheben

Debuggen in Android Studio

Um Ihr AAR-Integration in Android Studio zu debuggen, beginnen Sie damit, den Debug-Modus in Ihrem Projekts build.gradle Datei zu aktivieren:

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

Hinzufügen Sie in Ihren Pluginmethoden Ausbrüche, um den Datenfluss zu verfolgen und potenzielle Probleme zu identifizieren:

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

Verwenden Sie das Debug-Panel in Android Studio, um wichtige Bereiche zu überwachen:

Wenn die Fehlersuche nicht zum Erfolg führt, folgen Sie den Schritten zur Fehlerbehebung in der nächsten Abschnitt.

Fehlerbehebungs-Schritte

Wenn die Fehlersuche allein nicht ausreicht, verwenden Sie diese Schritte, um häufige Probleme anzugehen:

1. Abhängigkeitskonflikte

Überprüfen Sie nach Versionenkonflikten in Ihrem build.gradle Sie können spezifische Versionen zwingen, um Konflikte zu lösen:

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

2. Fehlende native Bibliotheken

Stellen Sie sicher, dass die AAR die erforderlichen .so Dateien in den entsprechenden Verzeichnissen enthält, wie z.B.:

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

3. Probleme bei der Manifest-Merger-Konfiguration

If Sie Manifest-Konflikte begegnen, fügen Sie folgendes Ihrem AndroidManifest.xml Datei hinzu, um problematische Bibliotheken zu überschreiben:

<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. Laufzeitstörungen und Speichermanagement

Verwenden Sie die Leistungsoberfläche in Android Studio, um die Laufzeitstabilität zu überwachen. Für Initialisierungsprobleme behandeln Sie Ausnahmen vorsichtig:

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

Um Speicherverluste zu verhindern, stellen Sie sicher, dass Ressourcen ordnungsgemäß freigegeben werden. Verwenden Sie die Speichermanager in Android Studio, um den Heap-Verbrauch zu überwachen und mögliche Lecks zu identifizieren.

Zusammenfassung

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.

Plugins zu integrieren, müssen Sie die Android-Umgebung einrichten, AAR-Dateien korrekt platzieren, Gradle genau konfigurieren und gründlich testen.

Wenn Sie diese Grundlagen beherrschen, können Sie sich mit fortgeschrittenen Techniken auseinandersetzen.

Zukünftige Schritte

Um Ihr Plugin zu verbessern, konzentrieren Sie sich auf diese Bereiche:

• Leistungsoptimierung
  Verwenden Sie Android Studios Profiler, um den Speicherbedarf zu überwachen und sicherzustellen, dass Ressourcen ordnungsgemäß bereinigt werden.

• Vorbereitung der Verteilung
  Alle AAR-Konfigurationen dokumentieren, API Dokumentation erstellen und die Kompatibilität mit Android API-Versionen 29–34 testen.

• Wartungsstrategie
  Automatisierte Tests durchführen, AAR-Versionen mit der Versionskontrolle verwalten, einen Changelog führen und Fehlerberichte einrichten, um Produktionsprobleme anzugehen.

Wenn Sie beabsichtigen, Ihr Plugin öffentlich zu teilen, stellen Sie sicher, dass Sie detaillierte Dokumentationen zu AAR-spezifischen Einstellungen und Plattformbeschränkungen bereitstellen. Dies erleichtert es anderen Entwicklern, Ihr Plugin effektiv zu adoptieren und zu verwenden.

Fortsetzen Sie mit: Wie Sie AAR-Dateien in Capacitor-Plugins verwenden

Wenn Sie __CAPGO_KEEP_0__ verwenden How to Use AAR Files in Capacitor Plugins um native Plugin-Arbeit zu planen, verbinden Sie es mit Capgo Plugin-Verzeichnis zur Produktionsablauf in Capgo Plugin-Verzeichnis Capacitor Plugins von Capgo zur Implementierungsdetail in Capacitor Plugins von Capgo Hinzufügen oder Aktualisieren von Plugins zur Implementierungsdetail in Hinzufügen oder Aktualisieren von Plugins Ionic Enterprise Plugin Alternativen zur Produktionsablauf in Ionic Enterprise Plugin Alternativen, und Capgo Native Builds zur Produktionsablauf in Capgo Native Builds.