Cómo usar archivos AAR en plugins Capacitor

¿Quiere integrar características de Android en su Capacitor aplicación? Esta guía explica cómo usar archivos AAR (Android Archive) en plugins __CAPGO_KEEP_0__ Capacitor plugins ¿Qué es __CAPGO_KEEP_0__?

Resumen clave:

• ¿Qué son los archivos AAR? Archivos de Android preempaquetados que contienen code, recursos y archivos nativos.
• ¿Por qué utilizarlos? Los archivos AAR permiten el reutilización de code, simplifican la mantenimiento y protegen características propietarias.
• ¿Qué se requiere? Herramientas como Android Studio, Gradle, y Node.js, más una configuración de proyecto adecuada.
• ¿Cómo integrar? Coloque los archivos AAR en libs, configure Gradle y conecte a los plugins Capacitor.

Pasos rápidos:

1. Configura tu entorno: Instale las herramientas necesarias y configure Android Studio.
2. Organiza tu proyecto: Crea una estructura clara para tu Capacitor plugin.
3. Agregar archivos AAR: Colóquelos en android/libs y actualice las dependencias de Gradle.
4. Escriba el plugin code: Conecte la funcionalidad de AAR a JavaScript con Capacitor’s API.
5. Pruebe exhaustivamente: Utilice el depurador de Android Studio para asegurarse de una integración suave.

Siguiendo esta guía, puede incorporar archivos AAR de manera fluida en sus plugins Capacitor, desbloqueando capacidades de Android nativas para sus aplicaciones web.

Cómo incorporar una biblioteca de Android (archivo AAR) en un capacitor plugin

Requisitos de configuración de desarrollo

Antes de trabajar con archivos AAR, asegúrese de que su entorno de desarrollo esté correctamente configurado para evitar cualquier problema.

Requisitos de Software

Aquí está el software que necesitará para trabajar con archivos AAR en plugins de Capacitor:

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

• Plataforma de Android SDK 33 (Android 13.0)
• Herramientas de construcción de Android SDK 33.0.0
• Herramientas de Línea de Comando para Android SDK
• Emulador de Android
• Plataforma de Herramientas de Android SDK

Pasos para Configurar el Proyecto

1. Inicie su Entorno de Desarrollo

Comience creando un nuevo directorio con esta estructura:

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

2. Configure los ajustes de Android Studio

Inicie Android Studio y ajuste los siguientes ajustes:

• Establezca la versión JDK de Gradle en 11 o superior.
• Active la característica de descarga automática para los componentes de Android SDK.
• Actualice las variables de entorno del sistema con la ruta correcta de Android SDK.

3. Prepare la estructura de su plugin

Actualice el archivo con estas configuraciones para incluir el soporte de archivo AAR: android/build.gradle Configuración de la versión de control

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

4. Inicie Git en su directorio de proyecto y cree un archivo para excluir archivos innecesarios. Aquí hay un ejemplo:

Una vez que haya completado estos pasos, estará listo para pasar a agregar sus archivos AAR. .gitignore Agregar archivos AAR a su plugin .gitignore:

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

Obtener archivos AAR

Los archivos AAR pueden provenir de SDKs de terceros, bibliotecas personalizadas o dependencias de Maven. Es una buena idea documentar su origen, versión y propósito en un archivo ubicado en la carpeta:

Tipo de origen

Set Up Version Control README Initialize Git in your project directory and create a libs file to exclude unnecessary files. Here’s a sample

Una vez que sus archivos AAR estén listos y documentados, puede configurar su plugin para incluirlos.

Configuración de Archivos de Plugin

Organiza tus archivos de plugin para garantizar una integración suave de dependencias AAR. Aquí tienes un ejemplo de cómo 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 del Archivo AAR

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

• Utiliza un formato de nombres claro y consistente, como libraryname-version.aar.
• Administra versiones en un versions.properties archivo. Por ejemplo:

library1=1.2.3
library2=2.0.0

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

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

• Organiza archivos específicos de proveedores en subdirectorios para una mejor gestión:

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

Mantener archivos de configuración en subdirectorios específicos de proveedores ayuda a mantener la organización y evita conflictos de compilación al trabajar con múltiples dependencias AAR.

Gradle Pasos de configuración

Actualizando build.gradle

Para integrar archivos AAR en tu plugin Capacitor, debes configurar Gradle adecuadamente. Comienza agregando estos ajustes 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 bibliotecas:

# Library versions
MY_LIBRARY_VERSION=1.2.3
CAPACITOR_VERSION=5.5.0

Si el archivo AAR viene con 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.

Ejecutando Sincronización de Gradle

Abra su proyecto en Android Studio y espere a que Gradle se sincronice automáticamente. Si no comienza, haga clic en el botón "Sincronizar proyecto con archivos de Gradle" en la barra de herramientas.

Después de sincronizar, verifique lo siguiente:

Si el sincronización falla, comprueba tu configuración. Por ejemplo, asegúrate de que estos ajustes estén en su lugar:

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

    lintOptions {
        abortOnError false
    }
}

Para archivos AAR grandes, es posible que debas aumentar la asignación de memoria de Gradle en gradle.properties:

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

Una vez que la sincronización se complete con éxito, tus archivos AAR deberían estar completamente integrados y listos para la prueba.

Conectar características de AAR a Capacitor

Crear la clase del plugin

Una vez que tus archivos Gradle estén sincronizados, es hora de conectar tu funcionalidad de AAR extendiendo la Plugin class. Este paso vincula JavaScript a la Android nativa 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());
    }
}

Estos son los datos necesarios para inicializar la biblioteca de AAR:

Crear Métodos de Plugin

A continuación, define métodos en tu plugin utilizando la @PluginMethod anotación. Estos métodos manejan 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 necesitan 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);
        }
    });
}

Aquí se muestra cómo se convierten los tipos comunes entre JavaScript y Java:

Para la limpieza de recursos, sobreescriba el método: handleOnDestroy método:

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

Con estos métodos en su lugar, su puente nativo está listo. Pruebe su implementación en el entorno de depuración de Android Studio para asegurarse de que todo funciona como se espera.

Pruebas y resolución de problemas de problemas

Depuración en Android Studio

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

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

Agrega puntos de interrupción en tus métodos de plugin para seguir el flujo de datos y 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);
}

Utiliza la pestaña de depuración en Android Studio para monitorear áreas clave:

Si la depuración no resuelve el problema, siga los pasos de depuración en la sección siguiente.

Pasos de depuración

Cuando depurar solo no es suficiente, utilice estos pasos para abordar problemas comunes:

1. Conflictos de dependencias

Verifique conflictos de versiones en su build.gradle archivo. Puede forzar versiones específicas para resolver conflictos:

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

2. Bibliotecas nativas faltantes

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

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

3. Problemas con la fusión de manifestos

Si encuentra conflictos de manifestos, incluya lo siguiente en su AndroidManifest.xml archivo para superar 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. Ralentizaciones en tiempo de ejecución y gestión de memoria

Utilice la pestaña de rendimiento en Android Studio para monitorear la estabilidad en tiempo de ejecución. Para problemas de inicialización, maneje 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úrese de que los recursos se liberan correctamente. Utilice el Profilador de Memoria en Android Studio para rastrear el uso de la pila y identificar cualquier fuga.

Resumen

Para integrar archivos AAR en los plugins Capacitor, necesitará configurar el entorno de Android, colocar los archivos AAR correctamente, configurar Gradle con precisión y probar exhaustivamente.

Fases de Implementación Clave

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

Pasos siguientes

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

• Optimización de rendimiento
  Utiliza el perfilador de Android Studio para monitorear el uso de memoria y asegurarte de que los recursos se limpien correctamente.

• Distribución de Preparación
  Documente todas las configuraciones de AAR, genere API documentación y pruebe la compatibilidad con Android API niveles 29–34.

• Estrategia de Mantenimiento
  Automatice las pruebas, gestione las versiones de AAR con control de versiones, mantenga un registro de cambios y configure el informe de errores para abordar problemas de producción.

Si planea compartir su complemento públicamente, asegúrese de proporcionar documentación detallada sobre las configuraciones específicas de AAR y cualquier limitación de plataforma. Esto facilitará que otros desarrolladores adopten y utilicen su complemento de manera efectiva.

Siga adelante desde Cómo utilizar archivos AAR en Capacitor complementos

Si está utilizando Cómo utilizar archivos AAR en Capacitor complementos para planificar el trabajo de plugin nativo, conecte con Directorio de Complementos Capgo para el flujo de trabajo del producto en Directorio de Complementos Capgo Complementos Capacitor por Capgo para los detalles de implementación en Capacitor Plugins por Capgo, Agregar o Actualizar Plugins para los detalles de implementación en Agregar o Actualizar Plugins, Alternativas de Plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas de Plugins de Ionic Enterprise, y Capgo Compilaciones Nativas para el flujo de trabajo del producto en Capgo Compilaciones Nativas.