Comment utiliser des fichiers AAR dans les plugins Capacitor

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

Points clés :

• Que sont les fichiers AAR ? Des bibliothèques Android prépackagées contenant du code, des ressources et des fichiers natifs.
• Pourquoi les utiliser ? Les fichiers AAR permettent la réutilisation du code, simplifient la maintenance et protègent les fonctionnalités propriétaires.
• Que faut-il ? Des outils comme Android Studio, Gradle, et Node.js, plus une configuration de projet appropriée.
• Comment les 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 code du plugin : Liez la fonctionnalité AAR à JavaScript avec l’API Capacitor.
5. Testez minutieusement : Utilisez le débogueur d’Android Studio pour assurer une intégration fluide.

En suivant ce guide, vous pourrez intégrer de manière transparente les fichiers AAR dans vos plugins Capacitor, débloquant ainsi les capacités natives Android pour vos applications web.

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

Exigences de configuration de 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

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

De plus, assurez-vous que les composants suivants sont inclus dans votre SDK Manager :

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

Étapes de configuration du projet

1. Initialisez 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. Configurez les paramètres d’Android Studio

Lancez Android Studio et ajustez les paramètres suivants :

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

3. Préparez la structure de votre plugin

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

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

4. Configurez le contrôle de version

Initialisez Git dans votre répertoire de projet et créez un fichier .gitignore 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 serez prêt à passer à l’ajout de vos fichiers AAR.

Ajout de fichiers AAR à votre plugin

Obtention 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, version et objectif dans un fichier README situé dans le répertoire libs.

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

Configuration des fichiers du plugin

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

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

Placement des fichiers AAR

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

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

library1=1.2.3
library2=2.0.0

• Ajoutez un fichier dependencies.gradle 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

Le maintien des 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.

Étapes de configuration Gradle

Mise à jour de build.gradle

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

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

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

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 fichier gradle.properties à la racine de votre projet et définissez vos versions de bibliothèque :

# Library versions
MY_LIBRARY_VERSION=1.2.3
CAPACITOR_VERSION=5.5.0

Si le fichier AAR est livré avec 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.

Exécution de la synchronisation Gradle

Ouvrez votre projet dans Android Studio et attendez que Gradle se synchronise automatiquement. Si cela ne démarre pas, cliquez sur le bouton “Sync Project with Gradle Files” dans la barre d’outils.

Après la synchronisation, vérifiez les points suivants :

Si la synchronisation échoue, revé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 gros fichiers AAR, 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 devraient être entièrement intégrés et prêts pour les tests.

Connexion des fonctionnalités AAR à Capacitor

Écriture de la classe Plugin

Une fois vos fichiers Gradle synchronisés, il est temps de connecter votre fonctionnalité AAR en étendant la classe Plugin. Cette étape lie 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 dont vous avez besoin pour initialiser la bibliothèque AAR :

Création des méthodes du plugin

Ensuite, définissez les méthodes dans votre plugin en utilisant l’annotation @PluginMethod. 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 doivent 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, redéfinissez la méthode handleOnDestroy :

@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 résolution des problèmes

Débogage dans Android Studio

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

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 Debug dans 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 dans la section suivante.

Étapes de dépannage

Lorsque le 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 version dans votre fichier 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 l’AAR inclut les fichiers .so 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

Si vous rencontrez des conflits de manifeste, incluez ce qui suit dans votre fichier AndroidManifest.xml 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 d’exécution et gestion de la mémoire

Utilisez l’onglet Performance dans Android Studio pour surveiller la stabilité d’exécution. Pour les problèmes d’initialisation, gérez soigneusement les exceptions :

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

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

Résumé

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

Phases clés d’implémentation

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

Prochaines étapes

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

• Optimisation des performances
  Utilisez le profileur d’Android Studio pour surveiller l’utilisation de la mémoire et garantir que les ressources sont correctement nettoyé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 les tests, gérez les versions AAR avec le contrôle de version, maintenez un journal des modifications et configurez le reporting d’erreurs pour traiter les problèmes en production.

Si vous prévoyez de partager votre plugin publiquement, assurez-vous de fournir une documentation détaillée sur les configurations spécifiques aux AAR et toutes les limitations de plateforme. Cela facilitera l’adoption et l’utilisation de votre plugin par d’autres développeurs.