How to Use AAR Files in Capacitor Plugins

Android機能をWebアプリに統合したい Capacitor app? このガイドでは、Capacitor プラグインで使用するAndroidアーカイブファイル(AAR)の使い方について説明します。 Capacitor プラグイン Androidネイティブ機能とクロスプラットフォームWebアプリを組み合わせるために使用します。

重要なポイント:

• AARファイルとは? Pre-packaged Android libraries containing code, resources, and native files.
• なぜ使用する? AAR files enable code reuse, simplify maintenance, and protect proprietary features.
• 必要なものは? Android Studioなどのツール __CAPGO_KEEP_0__, Gradle, and Node.js, plus proper project setup.
• How to integrate? Place AAR files in libs, configure Gradle, and connect them to Capacitor plugins.

Quick Steps:

1. 環境を設定する: 必要なツールをインストールし、Android Studioを設定する。
2. プロジェクトを整理する: 明確な構造をプロジェクトに作成する Capacitor プラグイン.
3. AARファイルを追加する: を置く: android/libs Gradle依存関係を更新する。
4. プラグインcodeを書く: JavaScriptとAAR機能をリンクするために CapacitorのAPIを使用する.
5. テストを徹底的に行う: Android Studioのデバッガーを使用して、Smoothな統合を確認する。

このガイドを参考にして、AARファイルをCapacitorプラグインに組み込むことができます。WebアプリケーションにネイティブのAndroid機能を活用できます。

Androidライブラリ(AARファイル)を__CAPGO_KEEP_0__に埋め込む方法 capacitor プラグイン

開発環境の設定要件

AARファイルと取り組む前に、開発環境が適切に設定されていることを確認してください。

必要なソフトウェア

ここでは、AARファイルを使用するために必要なCapacitorプラグインのソフトウェアについて説明します。

さらに、次のコンポーネントが含まれていることを確認してください。SDK マネージャー:

• Android SDK プラットフォーム 33 (Android 13.0)
• Android SDK ビルドツール 33.0.0
• Android SDK コマンドラインツール
• Android エミュレータ
• Android SDK プラットフォーム ツール

プロジェクト設定手順

1. 開発環境の初期化

はじめに、次のディレクトリ構造を作成してください:

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

2. Android Studioの設定を調整

Android Studioを起動し、次の設定を調整してください:

• 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ファイルを取得してください。

CapacitorプラグインでAARファイルを使用する方法については、以下の記事を参照してください。

CapacitorプラグインでAARファイルを使用する方法については、以下の記事を参照してください。

AARファイルは、第三のパーティー製のSDK、カスタムライブラリ、またはMaven依存関係から来ることができます。 そのソース、バージョン、目的をドキュメントすることは、良いアイデアです。 README AARファイルのソースは、以下のファイルに記載されています。 libs AARファイルのソースは、以下のディレクトリに記載されています。

AARファイルが用意でき、ドキュメントが完了したら、プラグインを設定してAARファイルを含めることができます。

プラグインファイルの設定

プラグインファイルを整理して、AAR依存性の平滑な統合を確保しましょう。以下の例は、プラグイン構造の例です。

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

• ARファイルを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

ベンダー固有のサブディレクトリに設定ファイルを保持することで、複数のAR依存関係を扱う際にビルドの競合を回避し、組織を維持することができます。

Gradle 設定手順

build.gradleを更新する

To integrate AAR files into your Capacitor plugin, you need to configure Gradle appropriately. Start by adding these repository settings to android/build.gradle:

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

次に、AR依存関係を含めるブロックに追加してください。 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 プロジェクトのルートディレクトリにファイルを追加し、ライブラリのバージョンを定義してください:

# Library versions
MY_LIBRARY_VERSION=1.2.3
CAPACITOR_VERSION=5.5.0

AARファイルに付随する追加の依存関係がある場合、次のように宣言してください: android/build.gradle 次の変更を実施した後、プロジェクトをsyncして適用してください。

android {
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }

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

Gradle Syncを実行する

Android Studioでプロジェクトを開き、Gradleが自動的にsyncされるのを待ってください。自動syncされない場合は、ツールバーの「Gradleファイルとプロジェクトをsyncする」ボタンをクリックしてください。

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機能をCapacitorに接続する

プラグインクラスを書く

Gradleファイルが同期されたら、AAR機能を接続するためにプラグインクラスを拡張する時間です。 プラグイン class. This step links JavaScript to the 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ライブラリを初期化するために必要なものを紹介します。

プラグインメソッドの作成

次に、プラグインでメソッドを定義するには、 @PluginMethod 注釈を使用します。これらのメソッドは、JavaScriptと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);
    }
}

非同期に実行する必要があるタスクの場合:

@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とJavaの間で一般的な型はどのように変換されるかをご覧ください:

リソースのクリーンアップのために、オーバーライドする 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 __CAPGO_KEEP_0__

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

__CAPGO_KEEP_1__

Capacitor プラグインで AAR ファイルを使用する方法 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 を使用してヒープ使用量を追跡し、リークを特定します。

概要

AAR ファイルを Capacitor プラグインに統合するには、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 native プラグインの作業を計画するには、 Capgo プラグイン ディレクトリ Capgo プラグイン ディレクトリ内での製品ワークフロー Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, __CAPGO_KEEP_0__ プラグイン __CAPGO_KEEP_1__ プラグインの追加または更新 __CAPGO_KEEP_0__ プラグイン Capgo Native Builds for the product workflow in Capgo Native Builds.