How to Use AAR Files in Capacitor Plugins

Android機能をあなたの Capacitor アプリに統合したい? このガイドでは、Capacitorプラグイン Capacitor plugins AARファイルとは?

プリパックされたAndroidライブラリで、

• Capacitor、リソース、ネイティブファイルが含まれます。 Pre-packaged Android libraries containing code, resources, and native files.
• AARファイルはCapacitorの AAR files enable code reuse, simplify maintenance, and protect proprietary features.
• どのようなものが必要ですか? ツールとしては Android Studio, Gradle, および Node.js, さらに適切なプロジェクト設定
• 統合方法 AARファイルを libsに置き、Gradleを設定し、Capacitor プラグインに接続する

クイックステップ

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

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

How to embed an Android library (AAR file) into a capacitor plugin

Development Setup Requirements

Before working with AAR files, make sure your development environment is properly configured to avoid any hiccups.

Required Software

Here’s the software you’ll need to work with AAR files in Capacitor plugins:

さらに、次のコンポーネントがあなたの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 __CAPGO_KEEP_0__ .gitignore:

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

__CAPGO_KEEP_0__

アンドロイド プラグインに AAR ファイルを追加する方法

AAR ファイルを取得する方法

AAR ファイルは、第三者の SDK、カスタム ライブラリ、または Maven の依存関係から得られることがあります。 AAR ファイルの元のソース、バージョン、目的を README に記述することをお勧めします。 README AAR ファイルの元のソース、バージョン、目的を記述するファイルは、 libs ディレクトリ

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 明確で一貫した命名形式を使用することをお勧めします。たとえば

• Capacitorプラグインのディレクトリ libraryname-version.aar.
• バージョンを管理する versions.properties ファイル内です。例えば:

library1=1.2.3
library2=2.0.0

• AARファイルの依存関係のために 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 block:

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

これらの変更を実施した後、プロジェクトをSyncして適用してください。 android/build.gradle Gradle Syncを実行する

android {
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }

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

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

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

Syncが成功した場合、AARファイルは完全に統合され、テスト用に準備されています。

Capacitorを接続する

プラグインクラスを書く

GradleファイルがSyncされると、AAR機能を接続するためにプラグインクラスを拡張する時間です。このステップはJavaScriptをネイティブのAndroid__CAPGO_KEEP_0__とリンクします。 ここで、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());
    }
}

目的

プラグインメソッドを定義する

次に、プラグインで使用するメソッドを定義します。 @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);
}

Capacitorプラグインで使用するAARファイルの使い方

メモリリーク

デバッグが解決しない場合は、次のセクションのトラブルシューティング ステップに従ってください。

トラブルシューティング ステップ

デバッグだけでは十分ではない場合は、次のステップを使用して一般的な問題を解決します:

1.依存関係の競合 build.gradle バージョンが競合しているかどうかを確認するには、ファイルを確認してください。バージョンを強制することで競合を解決できます:

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

2.ネイティブ ライブラリの欠如

AARが必要なライブラリを含んでいることを確認してください .so Capacitorプラグインで使用するAARファイル

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

3. マニフェストマージャー問題

問題が発生した場合、次の内容を含むファイルを使用して、問題のあるライブラリを上書きします。 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>

Android StudioのPerformanceタブを使用して、ランタイムの安定性を監視します。初期化問題の場合、例外を慎重に処理します。

ランタイムクラッシュを防ぐには、リソースを適切にリリースすることを確認し、Android StudioのMemory Profilerを使用してヒープの使用状況を追跡し、リソースのリークを特定します。

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

概要

AARファイルを__CAPGO_KEEP_0__プラグインに統合するには、Android環境を設定し、AARファイルを正しく配置し、Gradleを正確に設定し、徹底的にテストする必要があります。

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固有の設定とプラットフォームの制限について、詳細なドキュメントを提供してください。これにより、他の開発者がプラグインを効果的に使用して採用することが容易になります。

Keep going from How to Use AAR Files in Capacitor Plugins

Capacitorプラグインを使用している場合 How to Use AAR Files in Capacitor Plugins ネイティブプラグインの作業計画に Capgo Plugin Directory for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, Capacitorプラグイン プラグインの追加または更新 プラグインの実装詳細 Ionic Enterpriseプラグインの代替 Capgo Native Builds for the product workflow in Capgo Native Builds.