Comment utiliser les fichiers AAR dans les plugins Capacitor

Vous souhaitez intégrer des fonctionnalités Android à votre Capacitor app ? Ce guide explique comment utiliser les fichiers AAR (Android Archive) dans Plugins Capacitor pour combiner les fonctionnalités Android natives avec vos applications web multiplateformes.

Points clés :

• Qu’est-ce qu’un fichier AAR ? Bibliothèques Android pré-emballées contenant du code, des ressources et des fichiers natifs.
• Pourquoi les utiliser ? Les fichiers AAR permettent de réutiliser du code, simplifient la maintenance et protègent les fonctionnalités propriétaires.
• What’s required? Des outils comme Android Studio, Gradle, et Node.js, ainsi qu’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 Plugin Capacitor.
3. Ajoutez les fichiers AAR : Placez-les dans android/libs et mettez à jour les dépendances Gradle.
4. Écrivez le plugin code : Liez la fonctionnalité AAR à JavaScript avec API de Capacitor.
5. Testez minutieusement : Utilisez le débogueur d’Android Studio pour garantir une intégration fluide.

En suivant ce guide, vous pouvez intégrer des fichiers AAR à vos plugins Capacitor et ainsi exploiter les capacités natives Android dans vos applications web.

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

Prérequis de configuration du développement

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

Logiciels requis

Voici le logiciel nécessaire pour travailler avec des fichiers AAR dans les plugins Capacitor :

De plus, vérifiez que les composants suivants sont inclus dans votre SDK Manager :

• Android SDK Plateforme 33 (Android 13.0)
• Android SDK Build-Tools 33.0.0
• Outils en ligne de commande Android SDK
• Émulateur Android
• Outils de plateforme Android SDK

Étapes de configuration du projet

1. Initialiser votre environnement de développement

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

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

2. Configurer les paramètres d’Android Studio

Lancez Android Studio et ajustez les paramètres suivants :

• Définissez le JDK Gradle sur la version 11 ou supérieure.
• Activez le téléchargement automatique des composants Android SDK.
• Mettez à jour les variables d’environnement de votre système avec le bon chemin Android SDK.

3. Préparer 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 la gestion de versions

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

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

Une fois ces étapes terminées, vous pourrez passer à l'ajout de vos fichiers AAR.

Ajouter des fichiers AAR à votre plugin

Récupérer des fichiers AAR

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

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

Configurer les fichiers du plugin

Organisez les fichiers de votre plugin pour assurer une intégration fluide des dépendances AAR. Voici un exemple de structure :

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 le android/libs répertoire de votre plugin en suivant ces étapes :

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

library1=1.2.3
library2=2.0.0

• Ajoutez une 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 aux fournisseurs 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 des sous-répertoires spécifiques aux fournisseurs aide à maintenir l’organisation et évite les conflits de build lors du travail avec plusieurs dépendances AAR.

Gradle Étapes de configuration

Mise à jour de build.gradle

Pour intégrer des fichiers AAR dans votre plugin Capacitor, vous devez configurer Gradle correctement. Commencez par ajouter ces paramètres de dépôt dans android/build.gradle:

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

Ensuite, incluez les dépendances AAR dans 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 meilleure gestion des versions, créez un gradle.properties fichier à la racine de votre projet et définissez vos versions de librairies :

# Library versions
MY_LIBRARY_VERSION=1.2.3
CAPACITOR_VERSION=5.5.0

Si le fichier AAR inclut des dépendances supplémentaires, déclarez-les dans android/build.gradle comme ceci :

android {
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }

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

Une fois ces modifications effectuées, synchronisez votre projet pour les appliquer.

Lancer la synchronisation Gradle

Ouvrez votre projet dans Android Studio et attendez que Gradle se synchronise automatiquement. Si ce n’est pas le cas, cliquez sur le bouton « Sync Project with Gradle Files » dans la barre d’outils.

After syncing, verify the following:

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 mémoire de Gradle dans gradle.properties:

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

Une fois la synchronisation terminée avec succès, vos fichiers AAR sont entièrement intégrés et prêts pour les tests.

Connecter les fonctionnalités AAR à Capacitor

Écrire la classe de plugin

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

Voici ce qu’il vous faut pour initialiser la bibliothèque AAR :

Création de méthodes de plugin

Ensuite, définissez les méthodes de votre plugin en utilisant l' @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 devant s'exécuter 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 le nettoyage des ressources, surchargez la 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 debug d’Android Studio pour vous assurer que tout fonctionne comme prévu.

Tests et correction des problèmes

Debug dans Android Studio

Pour déboguer votre intégration AAR dans Android Studio, commencez par activer le mode debug dans votre build.gradle fichier :

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

Ajoutez des points d’arrêt dans les méthodes de votre 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 Debug d’Android Studio pour surveiller les zones clés :

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

Étapes de dépannage

Quand le débogage ne suffit pas, utilisez ces étapes pour résoudre les problèmes courants :

1. Conflits de dépendances

Vérifiez les conflits de version dans votre build.gradle fichier. 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 l’AAR contient les .so fichiers requis dans les répertoires appropriés, tels que :

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

3. Problèmes de fusion de manifeste

En cas de conflits de manifeste, incluez ce qui suit dans votre AndroidManifest.xml fichier pour remplacer les bibliothèques problématiques :

<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 au runtime et gestion de la mémoire

Utilisez l’onglet Performance dans Android Studio pour surveiller la stabilité au runtime. Pour les problèmes d’initialisation, gérez les exceptions avec soin :

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

Pour éviter les fuites mémoire, assurez-vous que les ressources sont correctement libérées. Utilisez le Memory Profiler d’Android Studio pour suivre l’utilisation du heap et identifier d’éventuelles fuites.

Résumé

Pour intégrer des fichiers AAR dans les plugins Capacitor, vous devez configurer l’environnement Android, placer correctement les fichiers AAR, configurer Gradle avec précision et tester rigoureusement.

Phases clés de l’implémentation

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

Étapes suivantes

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

• Optimisation des performances
  Utilisez le profil d’Android Studio pour surveiller l’utilisation de la 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érez la documentation API et testez la compatibilité avec les niveaux API Android 29–34.

• Stratégie de maintenance
  Automatisez vos tests, gérez les versions d'AAR avec un contrôle de version, maintenez un changelog et configurez le reporting d'erreurs pour résoudre les problèmes en production.

Si vous prévoyez de partager votre plugin publiquement, pensez à fournir une documentation détaillée sur les configurations AAR spécifiques et les éventuelles limitations de plateforme. Cela facilitera l'adoption et l'utilisation efficace de votre plugin par d'autres développeurs.

Continuer avec « Comment utiliser les fichiers AAR dans les plugins Capacitor »

Si vous utilisez Comment utiliser les fichiers AAR dans les plugins Capacitor pour planifier le travail sur les plugins natifs, connectez-l’à Capgo Répertoire des plugins pour le workflow produit dans Capgo Plugin Directory, Plugins Capacitor par Capgo pour les détails d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans Adding or Updating Plugins, Alternatives aux plugins Ionic Enterprise pour le workflow produit dans les alternatives aux plugins Ionic Enterprise, et Capgo Native Build pour le workflow produit dans Capgo Native Builds.