How to Use AAR Files in Capacitor Plugins

안드로이드 기능을 통합하여 앱을 만들고 싶다면? Capacitor app? 앱을 만들고 싶다면? Capacitor 플러그인 Key Takeaways:

AAR 파일이란?

• 이미 컴파일된 안드로이드 라이브러리입니다. 안드로이드 라이브러리를 포함한 code가 미리 패키징되어 있으며, 리소스 및 네이티브 파일이 포함되어 있습니다.
• AAR 파일을 사용하면 __CAPGO_KEEP_0__ 재사용이 가능하고 유지보수가 간편하며 비공개 기능을 보호할 수 있습니다. AAR 파일은 code 재사용을 가능하게 하며 유지 관리를 간소화하고 사유 특허 기능을 보호합니다.
• Capgo를 사용하는 방법 Capgo를 사용하려면 안드로이드 스튜디오, GradleNode.js Capgo를 사용하려면AAR 파일을 __CAPGO_KEEP_0__에 넣고 Gradle을 설정한 후 플러그인을 연결하세요.
• 빠른 단계: 환경 설정: libs, Gradle을 구성하고 Capacitor 플러그인을 연결하세요.

Capacitor

1. Capacitor Android Studio를 설치하고 설정하세요.
2. 프로젝트를 구성하세요: 프로젝트에 대한 명확한 구조를 만드세요. Capacitor 플러그인.
3. AAR 파일을 추가하세요: AAR 파일을 android/libs 그리고 Gradle 의존성을 업데이트하세요.
4. 플러그인 code을 작성하세요: AAR 파일 기능을 자바스크립트와 연결하세요 Capacitor의 API.
5. Android Studio의 디버거를 사용하여 smooth한 통합을 확인하세요. __CAPGO_KEEP_0__은 Capgo에서 사용하는 플러그인입니다.

이 안내서를 따라 AAR 파일을 Capacitor 플러그인에 통합할 수 있습니다. 이로써 웹 앱에서 네이티브 안드로이드 기능을 사용할 수 있습니다.

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

개발 환경 설정 요구 사항

AAR 파일을 사용하기 전에 개발 환경을 올바르게 구성하여 문제를 피하십시오.

필요한 소프트웨어

AAR 파일을 Capacitor 플러그인과 함께 사용하기 위한 소프트웨어

또한, 다음 구성 요소가 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 이상으로 설정하세요.
• 안드로이드 SDK 컴포넌트에 대한 자동 다운로드 기능을 활성화하세요.
• 시스템 환경 변수를 업데이트하여 올바른 안드로이드 SDK 경로를 설정하세요.

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

업데이트 하세요 android/build.gradle 버전 관리를 설정하세요

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

4. 프로젝트 디렉토리에 Git을 초기화하고 불필요한 파일을 제외하기 위해

파일을 생성하세요. 여기에는 샘플 .gitignore 이 있습니다. .gitignore:

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

이 단계를 완료한 후 AAR 파일을 추가하는 것을 시작할 수 있습니다.

AAR 파일 추가

AAR 파일 가져오기

AAR 파일은 제 3 자 SDK, 사용자 지정 라이브러리 또는 Maven 의존성에서 나올 수 있습니다. README AAR 파일의 원천, 버전 및 목적을 설명하는 파일을 포함하는 libs 디렉토리

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

플러그인 파일 설정

플러그인 파일을 조직하여 AAR 의존성을 smooth하게 통합할 수 있습니다. 예를 들어, 플러그인 구조는 다음과 같습니다.

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 파일을 사용하세요. 예를 들어:

library1=1.2.3
library2=2.0.0

• 다른 의존성에 대한 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 업데이트

Capacitor 플러그인을 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"
}

버전 관리를 위해 더 나은 관리를 위해 프로젝트 루트에 파일을 만들고 라이브러리 버전을 정의하세요. gradle.properties AAR 파일이 추가 의존성을 포함한다면 다음처럼 선언하세요.

# Library versions
MY_LIBRARY_VERSION=1.2.3
CAPACITOR_VERSION=5.5.0

이러한 변경 사항을 적용하려면 프로젝트를 싱크하세요. android/build.gradle 이런 식으로.

android {
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }

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

프로젝트를同步하세요.

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

체크 포인트

예상 결과

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

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

Connecting AAR Features to Capacitor

AAR 기능을 연결하는 방법

AAR 기능을 연결하는 방법 Plugin 자바스크립트는 이 단계에서 native Android 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 annotation을 사용합니다.

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

동기화되지 않은 작업을 위해:

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

자바스크립트와 자바 간의 일반적인 유형은 다음과 같이 변환됩니다:

자원 정리 위해, 다음 메서드를 오버라이드하세요. handleOnDestroy 메서드:

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

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

테스트 및 문제 해결

디버깅 안드로이드 스튜디오

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

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

Plugin 메서드에서 데이터 흐름을 추적하고 잠재적인 문제를 식별하기 위해 브레이크 포인트를 추가하십시오:

@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의 Debug 패널을 사용하여 주요 영역을 모니터링하십시오:

디버깅이 문제를 해결하지 못한다면, 다음 섹션의 문제 해결 단계를 따르세요.

문제 해결 단계

디버깅만으로 충분하지 않다면, 다음 단계를 사용하여 일반적인 문제를 해결하세요:

1. 의존성 충돌

버전 충돌이 있는지 확인하세요. 의존성 버전을 강제로 지정하여 충돌을 해결할 수 있습니다. build.gradle 2. 미리 설치된 네이티브 라이브러리

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

3. 의존성 충돌

ARF 파일을 사용하는 Capacitor 플러그인에 통합하기 .so ARF 파일을 사용하는 Capacitor 플러그인에 통합하기

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

3. Manifest Merger 문제

manifest 충돌이 발생하는 경우, 다음을 파일에 포함하여 문제가 있는 라이브러리를 오버라이드하세요: AndroidManifest.xml 4. 런타임 충돌 및 메모리 관리

<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의 Memory Profiler를 사용하여 힙 사용량을 추적하고 누수를 식별하세요.

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

결과

Summary

To integrate AAR files into Capacitor plugins, you’ll need to set up the Android environment, place AAR files correctly, configure Gradle accurately, and test thoroughly.

단계

이 기본 사항들을 마스터한 후, 더 고급된 기술들을 탐색할 수 있습니다.

다음 단계

플러그인을 향상시키려면 다음 영역에 집중하세요:

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

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

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

플러그인을 공개적으로 공유하려면 AAR-특정 설정에 대한 자세한 문서와 플랫폼 제약을 제공하여 다른 개발자들이 플러그인을 효과적으로 사용할 수 있도록 도와주세요.

Capgo를 사용하여 AAR 파일을 Capacitor 플러그인에 계속 사용하세요.

Capacitor 플러그인을 사용 중이라면 Capacitor 플러그인에서 AAR 파일 사용 방법 Capacitor 플러그인을 사용하여 native 플러그인 작업을 계획하고 연결하려면 Capgo 플러그인 디렉토리 for the product workflow in Capgo Plugin Directory, Capacitor 플러그인들에 의해 Capgo for the implementation detail in Capacitor Plugins by Capgo, Capacitor 플러그인에 대한 implementation detail Capacitor 플러그인에 대한 implementation detail Capacitor 플러그인 추가 또는 업데이트 Capacitor 플러그인에 대한 implementation detail Capgo 네이티브 빌드 Capgo 네이티브 빌드의 제품 워크플로우.