Comment utiliser les fichiers AAR dans les plugins Capacitor

Vous souhaitez intégrer des fonctionnalités Android dans votre Capacitor application ? Cette guide explique comment utiliser les fichiers AAR (archive Android) dans les plugins Capacitor pour combiner la fonctionnalité native Android avec des applications web cross-plateformes.

Résultats clés :

• Quels sont les fichiers AAR ? Bibliothèques Android pré-packagées contenant code, ressources et fichiers natifs.
• Pourquoi les utiliser ? Les fichiers AAR permettent le code réutilisation, simplifient la maintenance et protègent les fonctionnalités propriétaires.
• Qu'est-ce qui est requis ? Les outils comme Android Studio, Gradle, et Node.js, plus une configuration de projet appropriée.
• Comment intégrer ? Placez les fichiers AAR dans libs, configurez Gradle et connectez-les aux plugins Capacitor.

Étapes rapides :

1. Configurez votre environnement : Installez les outils requis et configurez Android Studio.
2. Organisez votre projet : Créez une structure claire pour votre Capacitor plugin.
3. Ajoutez les fichiers AAR : Placez-les dans android/libs et mettez à jour les dépendances Gradle.
4. Écrivez le plugin code: Lier la fonctionnalité AAR au JavaScript avec Capacitor’s API.
5. Testez soigneusement : Utilisez le débogueur d'Android Studio pour garantir une intégration fluide.

En suivant ce guide, vous pouvez incorporer de manière fluide les fichiers AAR dans vos Capacitor plugins, déverrouillant ainsi les capacités Android natives pour vos applications web.

Comment intégrer une bibliothèque Android (fichier AAR) dans un capacitor plugin

Configuration requise pour le développement

Avant de travailler avec les fichiers AAR, assurez-vous que votre environnement de développement est correctement configuré pour éviter tout problème.

Logiciels requis

Ici sont les logiciels dont vous aurez besoin pour travailler avec les fichiers AAR dans les Capacitor plugins :

Assurez-vous également que les composants suivants sont inclus dans votre SDK Manager :

• Plateforme Android SDK 33 (Android 13.0)
• Outils de construction Android SDK 33.0.0
• Outils de ligne de commande Android SDK
• Émulateur Android
• Outils de la plateforme Android SDK

Étapes de configuration du projet

1. Initialisez votre environnement de développement

Démarrez par créer un nouveau répertoire avec cette structure :

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

2. Configurez les paramètres de Studio Android

Lancez Studio Android et ajustez les paramètres suivants :

• Fixez la version JDK de Gradle à 11 ou supérieure.
• Activez la fonctionnalité de téléchargement automatique pour les composants Android SDK.
• Mettez à jour les variables d'environnement système avec le chemin correct d'Android SDK.

3. Préparez la structure de votre plugin

Mettez à jour le android/build.gradle fichier avec ces paramètres pour inclure le support des fichiers AAR :

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

4. Configurer le Contrôle de Version

Initialisez Git dans votre répertoire de projet et créez un .gitignore fichier à exclure les fichiers inutiles. Voici un exemple .gitignore:

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

Une fois ces étapes complétées, vous serez prêt à passer à l'ajout de vos fichiers AAR.

Ajouter des fichiers AAR à votre plugin

Obtenir des fichiers AAR

Les fichiers AAR peuvent provenir de SDK tiers, de bibliothèques personnalisées ou de dépendances Maven. Il est une bonne idée de documenter leur source, leur version et leur but dans un README fichier situé dans le libs répertoire.

Une fois que vos fichiers AAR sont prêts et documentés, vous pouvez configurer votre plugin pour les inclure.

Configuration des fichiers de plugin

Organisez vos fichiers de plugin pour garantir une intégration fluide des dépendances AAR. Voici un exemple de la structure de votre plugin qui pourrait ressembler à ceci :

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

Emplacement des fichiers AAR

Pour activer la fonctionnalité AAR, placez les fichiers dans android/libs répertoire de votre plugin en suivant ces étapes :

• Utilisez un format de nommage clair et cohérent, comme libraryname-version.aar.
• Gérer les versions dans un versions.properties fichier. Par exemple :

library1=1.2.3
library2=2.0.0

• Ajoutez un dependencies.gradle fichier pour les autres dépendances :

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

• Organisez les fichiers spécifiques au fournisseur dans des sous-répertoires pour une meilleure gestion :

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

Conserver les fichiers de configuration dans les sous-répertoires spécifiques au fournisseur aide à maintenir l'organisation et évite les conflits de construction lors du travail avec plusieurs dépendances AAR.

Gradle Étapes de configuration

Mise à jour de build.gradle

Pour intégrer les fichiers AAR dans votre Capacitor plugin, vous devez configurer Gradle en conséquence. Commencez par ajouter ces paramètres de référentiel à android/build.gradle:

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

Ensuite, incluez les dépendances AAR dans le dependencies bloc :

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

Pour une gestion de version plus efficace, créez un gradle.properties fichier dans votre dossier de projet et définissez les versions de vos bibliothèques :

# Library versions
MY_LIBRARY_VERSION=1.2.3
CAPACITOR_VERSION=5.5.0

Si le fichier AAR est accompagné de dépendances supplémentaires, déclarez-les dans android/build.gradle comme suit :

android {
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }

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

Une fois que vous avez apporté ces modifications, synchronisez votre projet pour les appliquer.

Exécution de la synchronisation de Gradle

Ouvrez votre projet dans Android Studio et attendez que Gradle se synchronise automatiquement. Si cela ne démarre pas, cliquez sur le bouton « Synchroniser le projet avec les fichiers Gradle » dans la barre d'outils.

Après synchronisation, vérifiez les éléments suivants :

Si la synchronisation échoue, vérifiez votre configuration. Par exemple, assurez-vous que ces paramètres sont en place :

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

    lintOptions {
        abortOnError false
    }
}

Pour les fichiers AAR volumineux, vous devrez peut-être augmenter l'allocation de mémoire de Gradle en gradle.properties:

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

Une fois la synchronisation terminée avec succès, vos fichiers AAR devraient être intégrés pleinement et prêts à la mise en test.

Connexion des fonctionnalités AAR à Capacitor

Écriture de la classe de plugin

Une fois vos fichiers Gradle synchronisés, il est temps de connecter votre fonctionnalité AAR en étendant la classe Plugin. Cette étape relie JavaScript à l'Android natif __CAPGO_KEEP_0__. 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());
    }
}

Composant

Définir les méthodes du plugin

Ensuite, définissez les méthodes dans votre plugin en utilisant le @PluginMethod annotation. Ces méthodes gèrent l'échange de données entre JavaScript et 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);
    }
}

Pour les tâches qui nécessitent d'être exécutées de manière asynchrone :

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

Voici comment les types courants sont convertis entre JavaScript et Java :

Pour la suppression des ressources, surécrivez le handleOnDestroy méthode :

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

Avec ces méthodes en place, votre pont natif est prêt. Testez votre implémentation dans l'environnement de débogage d'Android Studio pour vous assurer que tout fonctionne comme prévu.

Test et correction des problèmes

Débogage dans Android Studio

Pour déboguer votre intégration AAR dans Android Studio, commencez par activer le mode débogage dans le projet de votre build.gradle file:

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

Ajoutez des points d'arrêt dans vos méthodes de plugin pour suivre le flux de données et identifier les problèmes potentiels :

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

Utilisez le panneau de débogage dans Android Studio pour surveiller les zones clés :

Si la débogage ne résout pas le problème, suivez les étapes de dépannage de la section suivante.

Étapes de Dépannage

Lorsque la débogage seul ne suffit pas, utilisez ces étapes pour résoudre les problèmes courants :

1. Conflits de dépendances

Vérifiez les conflits de versions dans votre build.gradle Vous pouvez forcer des versions spécifiques pour résoudre les conflits :

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

2. Bibliothèques natives manquantes

Assurez-vous que le fichier AAR inclut les fichiers requis dans les répertoires appropriés, tels que : .so 3. Problèmes de fusion de manifestes

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

Si vous rencontrez des conflits de manifestes, incluez les éléments suivants dans votre fichier pour contourner les bibliothèques problématiques :

4. Crashes et gestion de la mémoire en temps de exécution AndroidManifest.xml Utilisez l'onglet Performance dans Android Studio pour surveiller la stabilité en temps de exécution. Pour les problèmes d'initialisation, gérez les exceptions avec soin :

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

Pour prévenir les fuites de mémoire, assurez-vous que les ressources sont libérées correctement. Utilisez le Profiler de la mémoire dans Android Studio pour suivre l'utilisation de la pile et identifier toute fuite.

Résumé

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

Pour intégrer les fichiers AAR dans les plugins __CAPGO_KEEP_0__, vous devrez configurer l'environnement Android, placer les fichiers AAR correctement, configurer Gradle avec précision et tester soigneusement.

Phases d'implémentation clés

Intégration des fichiers AAR dans les plugins Capacitor nécessite la configuration de l'environnement Android, la mise en place des fichiers AAR dans les répertoires appropriés, la configuration de Gradle avec précision et des tests approfondis.

Pour intégrer les fichiers AAR dans les plugins __CAPGO_KEEP_0__ vous devez configurer l'environnement Android, mettre en place les fichiers AAR dans les répertoires appropriés, configurer Gradle avec précision et effectuer des tests approfondis.

Une fois que vous avez maîtrisé ces bases, vous pouvez explorer des techniques plus avancées.

Étapes suivantes

Pour améliorer votre plugin, concentrez-vous sur ces domaines :

• Optimisation de la performance
  Utilisez le profilateur d'Android Studio pour surveiller la consommation de mémoire et vous assurer que les ressources sont correctement libérées.

• Préparation de la distribution
  Documentez toutes les configurations AAR, générerz API documentation et testez la compatibilité avec les niveaux d'Android API 29–34.

• Stratégie de maintenance
  Automatisez les tests, gérez les versions AAR avec le contrôle de version, maintenez un journal des modifications et configurez la notification d'erreur pour résoudre les problèmes de production.

If vous prévoyez de partager votre plugin publiquement, assurez-vous de fournir une documentation détaillée sur les paramètres AAR spécifiques et toute limitation de plateforme. Cela facilitera l'adoption et l'utilisation de votre plugin par d'autres développeurs.

Continuez de la section Comment utiliser les fichiers AAR dans les Capacitor Plugins

Si vous utilisez Comment utiliser les fichiers AAR dans les Capacitor Plugins pour planifier le travail de plugin natif, connectez-le à Capgo Répertoire de plugins pour le flux de travail du produit dans Capgo Répertoire de plugins, Capacitor Plugins par Capgo pour les détails d'implémentation dans Capacitor Plugins par Capgo, Ajout ou mise à jour de plugins pour les détails d'implémentation dans Ajout ou mise à jour de plugins, Alternatives de plugins d'entreprise Ionic pour le flux de travail du produit dans les alternatives Ionic Enterprise Plugin Capgo Builds natifs pour le flux de travail du produit dans Capgo Builds natifs.