How to Use AAR Files in Capacitor Plugins

Android 기능을 통합하고 싶다면 Capacitor 앱? 이 안내서에서는 Capgo 플러그인에서 사용하는 AAR(Android Archive) 파일을 사용하여 Capacitor 플러그인 을 사용하여 네이티브 안드로이드 기능을 크로스 플랫폼 웹 앱과 결합하는 방법을 설명합니다.

주요 내용:

• AAR 파일이란 무엇인가? AAR 파일은 code, 리소스, 네이티브 파일을 포함하는 미리 패키지 된 안드로이드 라이브러리입니다.
• 왜 사용해야 하나? AAR 파일은 code 재사용, 유지 관리를 단순화하고 비공개 기능을 보호하는 데 도움이 됩니다.
• 무엇이 필요합니까? Android Studio와 같은 도구 이용, Gradle, 그리고 Node.js, 올바른 프로젝트 설정과 함께
• How to integrate? AAR 파일을 위치시키고 libs, Gradle을 구성하고, Capacitor 플러그인과 연결하세요.

Quick Steps:

1. 환경 설정: 필요한 도구를 설치하고 Android Studio를 구성하세요.
2. 프로젝트를 조직하세요: 프로젝트 구조를 명확하게 구성하세요. Capacitor 플러그인.
3. AAR 파일 추가: 그것들을 android/libs 에 넣고 Gradle 의존성을 업데이트하십시오.
4. 플러그인 code을 작성하십시오: JavaScript와 AAR 기능을 연결하기 위해 Capacitor의 API을 사용하십시오..
5. 적극적으로 테스트하십시오: Android Studio의 디버거를 사용하여 smooth한 통합을 확인하십시오.

이 가이드를 따라 AAR 파일을 Capacitor 플러그인에 통합하여 Native Android 기능을 웹 앱에 제공할 수 있습니다.

Android 라이브러리(AAR 파일)를 capacitor에 포함하는 방법 플러그인

개발 환경 설정 요구 사항

AAR 파일과 작업하기 전에 개발 환경이 올바르게 구성되어 있는지 확인하여 문제를 피하십시오.

필요한 소프트웨어

다음 소프트웨어가 Capacitor 플러그인에서 AAR 파일과 작업하기 위해 필요합니다:

추가로, 다음 구성 요소가 SDK 매니저에 포함되어야 합니다.

• 안드로이드 SDK 플랫폼 33 (안드로이드 13.0)
• 안드로이드 SDK 빌드-도구 33.0.0
• 안드로이드 SDK 명령줄 도구
• 안드로이드 에뮬레이터
• 안드로이드 SDK 플랫폼 도구

프로젝트 설정 단계

1. 개발 환경 초기화

시작하기 전에 새로운 폴더를 생성하여 다음 구조로 구성하세요:

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

2. 안드로이드 스튜디오 설정 구성

안드로이드 스튜디오를 시작하고 다음 설정을 조정하세요:

• Gradle JDK 버전을 11 이상으로 설정하세요.
• Android SDK 컴포넌트에 대한 자동 다운로드 기능을 활성화하세요.
• Android SDK 경로가 정확한 시스템 환경 변수로 업데이트하세요.

3. 플러그인 구조를 준비하세요.

AAR 파일 지원을 포함하는 설정을 적용하기 위해 이 파일을 업데이트하세요: android/build.gradle 버전 관리를 설정하세요.

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

4. 프로젝트 디렉토리에서 Git을 초기화하고 불필요한 파일을 제외하기 위해 이 파일을 생성하세요. 여기에는 샘플이 있습니다.

이러한 단계가 완료되면 AAR 파일을 추가하는 단계로 넘어가세요. .gitignore 플러그인에 AAR 파일을 추가하세요. .gitignore:

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

AAR 파일을 가져오세요.

AAR 파일

AAR 파일

AAR 파일은 제 3 자 SDK, 사용자 지정 라이브러리 또는 Maven 의존성을 통해 올 수 있습니다. 그들의 출처, 버전 및 목적을 README 파일에 문서화하는 것이 좋습니다. README AAR 파일의 출처, 버전 및 목적을 문서화하는 것이 좋습니다. libs AAR 파일의 출처, 버전 및 목적을 문서화하는 것이 좋습니다.

AAR 파일이 준비되고 문서화되면, 플러그인을 구성하여 포함할 수 있습니다.

플러그인 파일 설정

AAR 의존성을MOOTH하게 통합하기 위해 플러그인 파일을 조직하세요. 예를 들어, 플러그인 구조는 다음과 같이 생길 수 있습니다.

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

AAR 파일 위치

AAR 기능을 활성화하려면 플러그인의 디렉토리에 파일을 위치시키세요. 다음 단계를 따르세요: android/libs 명확하고 일관된 이름 형식을 사용하세요. 예를 들어,

• 버전 관리 libraryname-version.aar.
• 파일을 사용하세요. 예를 들어: versions.properties file. For example:

library1=1.2.3
library2=2.0.0

• ARF 파일을 사용하는 Capacitor 플러그인에 추가하는 방법 dependencies.gradle 다른 의존성에 대한 파일을 추가하세요:

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

• 판매자별 파일을 관리하기 위해 하위 디렉토리로 판매자별 파일을 분류하세요:

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

판매자별 서브 디렉토리에 구성 파일을 유지하면 여러 AAR 의존성을 작업할 때 빌드 충돌을 피하고 관리를 유지할 수 있습니다.

Gradle 구성 단계

build.gradle을 업데이트하세요

ARF 파일을 Capacitor 플러그인에 통합하려면 Gradle을 적절히 구성해야 합니다. 먼저 다음 저장소 설정을 추가하세요: android/build.gradle:

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

그 다음, AAR 의존성을 포함하세요: 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"
}

버전 관리를 위해 더 나은 관리를 위해 AAR 의존성을 생성하세요: gradle.properties 프로젝트 루트 폴더에 파일을 추가하고 라이브러리 버전을 정의하세요:

# Library versions
MY_LIBRARY_VERSION=1.2.3
CAPACITOR_VERSION=5.5.0

AAR 파일이 추가 의존성을 포함한다면, 다음과 같이 선언하세요: android/build.gradle 이러한 변경 사항을 적용하려면 프로젝트를 싱크하세요:

android {
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }

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

Gradle Sync를 실행하세요:

Android Studio에서 프로젝트를 열고 Gradle이 자동으로 싱크를 시작할 때까지 기다리세요. 자동 싱크가 시작되지 않으면, 툴바의 "Gradle 파일과 프로젝트를 싱크하세요" 버튼을 클릭하세요.

싱크가 완료되면 다음을 확인하세요:

체크 포인트:

Sync가 실패하면, 설정을 다시 확인하세요. 예를 들어, 다음 설정이 올바르게 설정되어 있는지 확인하세요:

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

    lintOptions {
        abortOnError false
    }
}

대형 AAR 파일의 경우, Gradle의 메모리 할당량을 증가시켜야 할 수 있습니다. gradle.properties:

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

Sync가 성공적으로 완료되면, AAR 파일이 완전히 통합되어 테스트를 위해 준비되어야 합니다.

AAR 기능을 Capacitor에 연결

플러그인 클래스를 작성

Gradle 파일이 동기화되면 AAR 기능을 연결하기 위해 Plugin 클래스를 확장하는 시간입니다. 플러그인 이 단계는 자바스크립트를 네이티브 안드로이드 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());
    }
}

AAR 라이브러리를 초기화하는 데 필요한 것은 다음과 같습니다.

플러그인 메서드 정의

다음으로, 플러그인 메서드를 정의하세요. 이 메서드는 JavaScript와 Java 간 데이터 교환을 처리합니다. @PluginMethod 비동기적으로 실행해야 하는 작업에 대해:

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

JavaScript와 Java 간에 일반적인 타입은 어떻게 변환되는지 알아보세요:

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

JavaScript 타입

자원 정리에는 다음을 재정의하세요. handleOnDestroy 메서드:

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

이 메서드들을 설정하면 네이티브 브리지가 준비됩니다. Android Studio의 디버그 환경에서 테스트하여 모든 것이 예상대로 작동하는지 확인하세요.

테스트 및 문제 해결

디버깅에서 Android Studio

Android Studio에서 AAR 통합을 디버깅하려면 프로젝트의 디버그 모드를 활성화하세요. build.gradle 파일:

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

플러그인 메서드에서 데이터 흐름을 추적하고 잠재적인 문제를 식별하기 위해 브레이크 포인트를 추가하세요:

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

Android Studio의 디버그 패널을 사용하여 중요한 영역을 모니터링하세요:

디버깅이 문제를 해결하지 못한 경우, 다음 섹션의 문제 해결 단계를 따르십시오.

문제 해결 단계

디버깅만으로 충분하지 않은 경우, 다음 단계를 사용하여 일반적인 문제를 해결하십시오:

1. 의존성 충돌

버전 충돌이 있는지 확인하십시오. 의존성 파일에서 특정 버전을 강제로 지정하여 충돌을 해결하십시오: build.gradle 2. 미리 컴파일된 네이티브 라이브러리 누락

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

AAR 파일이 필요한 파일을 포함하고 있는지 확인하십시오. 다음 디렉토리와 같은 위치에 파일이 포함되어야 합니다:

3. 매니페스트 병합 문제 .so 3. 매니페스트 병합 문제

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

3. 매니페스트 병합 문제

만약 매니페스트 충돌이 발생하면 다음을 포함하여 문제가 있는 라이브러리를 오버라이드하세요: AndroidManifest.xml 파일에 포함하여 문제가 있는 라이브러리를 오버라이드하세요:

<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. 런타임 충돌 및 메모리 관리

Android Studio의 Performance 탭을 사용하여 런타임 안정성을 모니터링하세요. 초기화 문제의 경우 예외를 주의 깊게 처리하세요:

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

메모리 누수를 방지하려면 리소스를 올바르게 해제하십시오. Android Studio의 Memory Profiler를 사용하여 힙 사용량을 추적하고 누수를 식별하세요.

요약

Capacitor 플러그인에 AAR 파일을 통합하려면 Android 환경을 설정하고 AAR 파일을 올바르게 위치시키고 Gradle을 정확하게 구성하고 철저히 테스트해야 합니다.

주요 구현 단계

이 기본적인 개념을 마스터한 후에는 더 고급적인 기술을 탐색할 수 있습니다.

다음 단계

플러그인을 개선하기 위해 다음 영역에 집중하세요:

• 성능 최적화
  Android Studio의 프로파일러를 사용하여 메모리 사용량을 모니터링하고 리소스가 올바르게 정리되는지 확인하세요.

• 배포 준비
  AAR 구성에 대한 모든 문서를 작성하고 API 문서를 생성하고 Android API 29-34 버전과 호환성을 테스트하세요.

• 유지 관리 전략
  테스트를 자동화하고 AAR 버전을 버전 관리로 관리하고 변경 로그를 유지하고 오류 보고를 설정하여 생산 문제를 해결하세요.

플러그인을 공유하기로 계획되면 AAR-특정 설정에 대한 자세한 문서와 플랫폼 제한에 대한 문서를 제공하여 다른 개발자가 플러그인을 쉽게 채택하고 사용할 수 있도록 하세요.

Keep going from How to Use AAR Files in Capacitor Plugins

Capacitor 플러그인에서 AAR 파일을 사용하는 방법에 대해 설명합니다. How to Use AAR Files in Capacitor Plugins Capgo 플러그인 개발을 계획하려면 Capgo Plugin Directory for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트에서 구현 세부 정보 이오닉 엔터프라이즈 플러그인 대안 이오닉 엔터프라이즈 플러그인 대안에서 제품 워크플로우 Capgo Native Builds for the product workflow in Capgo Native Builds.