How to Use AAR Files in Capacitor Plugins

Androidの機能をウェブアプリに統合したい 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? AARファイルを置く場所 libsGradleを設定し、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プラグインに組み込むことができます。 これにより、WebアプリケーションにネイティブのAndroid機能を提供できます。

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

開発環境の設定要件

AARファイルを使用する前に、開発環境を適切に設定して、障害を回避するようにしてください。

必要なソフトウェア

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

Additionally, make sure the following components are included in your SDK Manager:

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

AARファイル

AARファイルの

AARファイルは、第三者製のSDK、カスタムライブラリ、またはMaven依存関係から得られることがあります。ソース、バージョン、目的を記録するREADMEファイルを作成することをお勧めします。 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

• AARファイルをCapacitorプラグインに統合するには、Gradleを適切に設定する必要があります。まず、次のリポジトリ設定を追加してください。 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を更新する

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

次に、AAR依存関係を次のブロックに含めてください: dependencies バージョン管理が容易になるため、AARファイルを管理するためのディレクトリを作成してください。

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

これらの変更を適用するには、プロジェクトをSyncする必要があります。

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

ここでは、JavaScriptとネイティブのAndroidを__CAPGO_KEEP_0__でリンクするステップです。

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

次に、プラグインでメソッドを定義するには、 @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_0__

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 を使用して、ヒープ使用量を追跡し、リークを特定します。

概要

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 native プラグインの作業を計画するには、__CAPGO_KEEP_0__ に接続します。 Capgo プラグイン ディレクトリ Capgo プラグイン ディレクトリ内での製品ワークフロー Capacitor プラグイン、Capgo Capacitor プラグイン、Capgo の実装詳細 プラグインの追加または更新 プラグインの追加または更新の実装詳細 Ionic Enterprise プラグインの代替 Ionic Enterprise プラグインの代替の製品ワークフロー Capgo ネイティブ ビルド Capgo ネイティブ ビルドの製品ワークフロー