Cómo usar archivos AAR en plugins de Capacitor

¿Quieres integrar funciones de Android en tu Capacitor app? Esta guía explica cómo usar archivos AAR (Android Archive) en plugins de Capacitor para combinar la funcionalidad nativa de Android con web apps multiplataforma.

Puntos clave:

• ¿Qué son los archivos AAR? Bibliotecas de Android preempaquetadas que contienen code, recursos y archivos nativos.
• ¿Por qué usarlas? Los archivos AAR permiten reutilizar code, simplifican el mantenimiento y protegen las funciones propietarias.
• ¿Qué se necesita? Herramientas como Android Studio, Gradle, y Node.js, además de la configuración adecuada del proyecto.
• ¿Cómo integrarlo? Coloca los archivos AAR en libs, configura Gradle y conéctalos a los plugins de Capacitor.

Pasos rápidos:

1. Prepara tu entorno: Instala las herramientas necesarias y configura Android Studio.
2. Organiza tu proyecto: Crea una estructura clara para tu plugin Capacitor.
3. Añade archivos AAR: Colócalos en android/libs y actualiza las dependencias de Gradle.
4. Escribe el plugin code: Vincula la funcionalidad AAR a JavaScript con el API de Capacitor.
5. Prueba a fondo: Usa el debugger de Android Studio para asegurar una integración fluida.

Siguiendo esta guía, podrás incorporar archivos AAR sin problemas en tus plugins de Capacitor, desbloqueando capacidades nativas de Android para tus web apps.

Cómo embeber una librería de Android (archivo AAR) en un capacitor plugin

Requisitos de configuración de desarrollo

Antes de trabajar con archivos AAR, asegúrate de que tu entorno de desarrollo esté bien configurado para evitar problemas.

Software requerido

Este es el software que necesitarás para trabajar con archivos AAR en plugins de Capacitor:

Además, asegúrate de que los siguientes componentes estén incluidos en tu SDK Manager:

• Android SDK Platform 33 (Android 13.0)
• Android SDK Build-Tools 33.0.0
• Herramientas de línea de comandos de Android SDK
• Emulador de Android
• Herramientas de plataforma de Android SDK

Pasos de configuración del proyecto

1. Inicializa tu entorno de desarrollo

Comienza creando un nuevo directorio con esta estructura:

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

2. Configura los ajustes de Android Studio

Abre Android Studio y ajusta los siguientes parámetros:

• Establece el JDK de Gradle en la versión 11 o superior.
• Habilita la descarga automática para los componentes de Android SDK.
• Actualiza las variables de entorno de tu sistema con la ruta correcta de Android SDK.

3. Prepara la estructura de tu plugin

Actualiza el android/build.gradle archivo con estos ajustes para incluir soporte para archivos AAR:

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

4. Configura el control de versiones

Inicializa Git en el directorio de tu proyecto y crea un .gitignore archivo para excluir archivos innecesarios. Aquí tienes un ejemplo de .gitignore:

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

Una vez completados estos pasos, estarás listo para pasar a añadir tus archivos AAR.

Cómo añadir archivos AAR a tu plugin

Obtener archivos AAR

Los archivos AAR pueden provenir de SDKs de terceros, librerías personalizadas o dependencias de Maven. Es recomendable documentar su origen, versión y propósito en un README archivo ubicado en el libs directorio.

Una vez que tus archivos AAR estén listos y documentados, puedes configurar tu plugin para incluirlos.

Configuración de archivos del plugin

Organiza los archivos de tu plugin para asegurar una integración fluida de las dependencias AAR. Así es como podría verse la estructura de tu plugin:

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

Ubicación de archivos AAR

Para habilitar la funcionalidad AAR, coloca los archivos en el android/libs directorio de tu plugin siguiendo estos pasos:

• Usa un formato de nombre claro y consistente, como libraryname-version.aar.
• Gestiona las versiones en un versions.properties archivo. Por ejemplo:

library1=1.2.3
library2=2.0.0

• Añade una dependencies.gradle archivo para otras dependencias:

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

• Organiza los archivos de cada vendor en subdirectorios para una mejor gestión:

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

Mantener los archivos de configuración en subdirectorios por proveedor ayuda a mantener el orden y evita conflictos de build al trabajar con varias dependencias AAR.

Gradle Pasos de configuración

Actualizar build.gradle

Para integrar archivos AAR en tu plugin de Capacitor, debes configurar Gradle correctamente. Comienza añadiendo estas configuraciones de repositorio a android/build.gradle:

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

Luego, incluye las dependencias AAR en el dependencies bloque:

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

Para una mejor gestión de versiones, crea un gradle.properties archivo en la raíz de tu proyecto y define las versiones de tus librerías:

# Library versions
MY_LIBRARY_VERSION=1.2.3
CAPACITOR_VERSION=5.5.0

Si el archivo AAR incluye dependencias adicionales, decláralas en android/build.gradle de esta manera:

android {
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }

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

Una vez que hayas realizado estos cambios, sincroniza tu proyecto para aplicarlos.

Ejecutar Gradle Sync

Abre tu proyecto en Android Studio y espera a que Gradle se sincronice automáticamente. Si no comienza, haz clic en el botón “Sync Project with Gradle Files” en la barra de herramientas.

Después de sincronizar, verifica lo siguiente:

Si la sincronización falla, verifica tu configuración. Por ejemplo, asegúrate de que estos ajustes estén configurados:

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

    lintOptions {
        abortOnError false
    }
}

Para archivos AAR grandes, puede que necesites aumentar la memoria de Gradle en gradle.properties:

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

Cuando la sincronización se complete correctamente, tus archivos AAR deberían estar totalmente integrados y listos para probar.

Conectar funciones AAR a Capacitor

Escribir la clase Plugin

Una vez sincronizados tus archivos Gradle, es hora de conectar la funcionalidad AAR extendiendo la clase Plugin . Este paso vincula JavaScript con el code nativo de 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());
    }
}

Esto es lo que necesitas para inicializar la librería AAR:

Creación de métodos del plugin

A continuación, define métodos en tu plugin usando la @PluginMethod anotación. Estos métodos gestionan el intercambio de datos entre JavaScript y 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);
    }
}

Para tareas que deben ejecutarse de forma asíncrona:

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

Así se convierten los tipos comunes entre JavaScript y Java:

Para liberar recursos, sobrescribe el handleOnDestroy método:

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

Con estos métodos, tu bridge nativo está listo. Prueba tu implementación en el entorno de debug de Android Studio para asegurar que todo funcione correctamente.

Pruebas y corrección de errores

Depuración en Android Studio

Para depurar la integración de tu AAR en Android Studio, comienza habilitando el modo de depuración en tu proyecto: build.gradle archivo:

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

Añade breakpoints en los métodos de tu plugin para seguir el flujo de datos e identificar posibles problemas:

@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 el panel de depuración en Android Studio para supervisar las áreas clave:

Si el debugging no resuelve el problema, sigue los pasos de solución de problemas de la siguiente sección.

Pasos para solucionar problemas

Cuando depurar por tu cuenta no es suficiente, usa estos pasos para resolver problemas comunes:

1. Conflictos de dependencias

Revisa los conflictos de versión en tu build.gradle archivo. Puedes forzar versiones específicas para resolver los conflictos:

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

2. Bibliotecas nativas faltantes

Asegúrate de que el AAR incluya los .so archivos necesarios en los directorios adecuados, como:

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

3. Problemas de fusión de manifiestos

Si encuentras conflictos en el manifiesto, incluye lo siguiente en tu AndroidManifest.xml archivo para sobrescribir bibliotecas problemáticas:

<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. Errores en tiempo de ejecución y gestión de memoria

Usa la pestaña Performance en Android Studio para monitorear la estabilidad en tiempo de ejecución. Para problemas de inicialización, maneja las excepciones con cuidado:

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

Para evitar fugas de memoria, asegúrate de liberar los recursos correctamente. Usa el Memory Profiler en Android Studio para rastrear el uso de la heap e identificar fugas.

Resumen

Para integrar archivos AAR en plugins de Capacitor, debes configurar el entorno de Android, colocar los archivos AAR en la ubicación correcta, configurar Gradle de forma precisa y realizar pruebas exhaustivas.

Fases clave de implementación

Una vez que domines estos conceptos básicos, puedes explorar técnicas más avanzadas.

Próximos pasos

Para mejorar tu plugin, enfócate en estas áreas:

• Optimización del rendimiento
  Usa el profiler de Android Studio para monitorear el uso de memoria y asegurar que los recursos se liberen correctamente.

• Preparación para la distribución
  Documenta todas las configuraciones AAR, genera la documentación de API y prueba la compatibilidad con los niveles de Android API 29–34.

• Estrategia de mantenimiento
  Automatiza las pruebas, gestiona versiones de AAR con control de versiones, mantén un changelog y configura reportes de errores para resolver problemas en producción.

Si planeas compartir tu plugin públicamente, asegúrate de incluir documentación detallada sobre las configuraciones específicas de AAR y cualquier limitación de la plataforma. Esto facilitará que otros desarrolladores adopten y usen tu plugin de forma efectiva.

Continuar desde Cómo usar archivos AAR en plugins de Capacitor

Si estás usando Cómo usar archivos AAR en plugins de Capacitor para planificar el trabajo con plugins nativos, conéctalo con Directorio de plugins de Capgo para el flujo de trabajo del producto en Capgo Plugin Directory, Plugins de Capacitor por Capgo para el detalle de implementación en los Plugins de Capacitor por Capgo, Añadir o actualizar plugins para el detalle de implementación en Agregar o actualizar plugins, Alternativas a plugins de Ionic Enterprise para el flujo de trabajo en Alternativas a plugins de Ionic Enterprise, y Native Builds de Capgo para el flujo de trabajo del producto en Capgo Native Builds.