ユーザー Cordova プラグイン

Cordova プラグインを利用すると、ネイティブ機能をプログラムに簡単に組み込めます。ここでは、ユーザー Cordova プラグインの作成方法とプロジェクトへの組み込み方法を解説します。

ユーザー Cordova プラグインのご利用には、対応するプランへの加入が必要です ( 料金プラン を参照のこと )。

ユーザー Cordova プラグインは、以下の要件を満たす必要があります。

• Cordova 4.2 以上との互換性

• plugin.xml ファイルを使用すること、および、plugman ( コマンドライン ツール ) を使用してインストールができること

• iOS と Android のサポート

さまざまな Cordova プラグインをインターネット上で見つけることができますが、メンテナンスが不十分だったり、バージョンが古い場合があります。そのため、ここでは、プラグインを最初から自作する方法について解説します。

ユーザー Cordova プラグインの構成

Cordova プラグインの典型的なディレクトリー構成を、次に記します ( ディレクトリー名には、太字を使用 )。

• plugin_name

  • src

    • ios

      • plugin_name.h

      • plugin_name.h

  • www

    • plugin_name.js

  • plugin.xml

最初にサンプルプラグインのコードをダウンロードします ( zip ファイル)。

https://github.com/monaca-samples/cordova-plugin-hello-world/archive/refs/heads/main.zipgithub.com

パッケージを解凍すると、次のようなディレクトリー構成が表示されます。

plugin.xml ファイル

plugin.xml ファイルとは、プラグインの設定ファイルであり、プラグインの詳細が定義されています。詳細は、Cordova プラグインの仕様 ( 英語サイト ) をご確認ください。

先ほどダウンロードしたサンプルプラグインの plugin.xml ファイルの内容を、次に記します。

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
  id="jp.co.asial.helloworld"
  version="0.0.1">

    <name>HelloWorldPlugin</name>
    <description>HelloWorldPlugin Description</description>
    <author>Asial Corporation</author>
    <license>Apache 2.0 License</license>
    <engines>
        <engine name="cordova" version=">=3.5.0" />
    </engines>
    <js-module src="www/hello_world.js" name="helloworld">
        <clobbers target="HelloWorld" />
    </js-module>

    <platform name="ios">
        <config-file target="config.xml" parent="/*">
            <feature name="HelloWorldPlugin">
                <param name="ios-package" value="HelloWorldPlugin"/>
            </feature>
    </config-file>
    <header-file src="src/ios/HelloWorldPlugin.h" target-dir="src/ios" />
        <source-file src="src/ios/HelloWorldPlugin.m" target-dir="src/ios" />
    </platform>
    <platform name="android">
        <config-file target="res/xml/config.xml" parent="/*">
            <feature name="HelloWorldPlugin">
                <param name="android-package" value="mobi.monaca.HelloWorldPlugin"/>
            </feature>
        </config-file>
        <source-file src="src/android/mobi/monaca/HelloWorldPlugin.java" target-dir="src/mobi/monaca" />
    </platform>

</plugin>

hello_world.js ファイル

hello_world.js は、plugin.xml ( 前述のプラグインの定義ファイル ) 内の js-module で指定されています。このため、 cordova.js から自動で読み込まれます ( この処理は、 loader.js 内に記述されています )。

var HelloWorld = function() {};

HelloWorld.prototype.say = function(success, fail) {
    cordova.exec(success, fail, "HelloWorldPlugin","say", []);
};

var helloWorld = new HelloWorld();
module.exports = helloWorld;

Cordova のコールバック関数の記法については、プラグインの開発ガイド (英語サイト) をご確認ください。

iOS と Android のネイティブコード

プラットフォームにもよりますが、ネイティブコードは、Objective-C または Java になります。関数名は、JavaScript ファイルで定義した名と同じものを使用します。また、コールバック関数は非同期で呼び出されます。

ネイティブコードの開発に関しては、次のリンクをご確認ください。

• Android 向けプラグインの開発 ( 英語サイト )

• iOS 向けプラグインの開発 ( 英語サイト )

ユーザー Cordova プラグインのインポート

ユーザー Cordova プラグインをインポートする場合、次の手順に従います。

1. Monaca クラウド IDE のメニューから、 設定 → Cordova プラグインの管理 を選択します。

2. Cordova プラグインページが表示されます。Cordova プラグインのインポート ボタンをクリックします。

3. プラグインファイル ( zip ファイル ) を選択し、OK をクリックします。

ユーザー Cordova プラグインと Monaca デバッガー

App Store または Google Play で入手できる Monaca デバッガーは、通常版のデバッガーです。こちらの通常版 Monaca デバッガーには、基本プラグインとサードパーティー製プラグイン ( Monaca 側であらかじめ提供しているサードパーティー製のプラグインとその詳細は、サードパーティー製プラグイン を参照のこと ) のみが実装されています。このため、デフォルトの状態では、ユーザー Cordova プラグインまたは外部の Cordova プラグイン ( 第三者が提供する、Monaca 側で用意しているプラグイン以外 ) は、デバッガー上で使用できません。これらのプラグインを使用する場合、Monaca デバッガーをカスタムビルドする必要があります。

カスタムビルド版の Monaca デバッガーは、Monaca クラウド IDE 上でビルドするデバッガーです ( ユーザー Cordova プラグインまたは外部の Cordova プラグインを組み込んだプロジェクトを使用してビルドします )。カスタムビルド版デバッガーのビルド方法、および、通常版とカスタムビルド版のデバッガーの相違に関しては、次のリンク先をご確認ください。

• iOS 用カスタムビルド版 Monaca デバッガーのビルド方法

• Android 用カスタムビルド版 Monaca デバッガーのビルドとインストール

カスタムビルド版デバッガーをビルドする前に、ユーザー Cordova プラグインまたは外部の Cordova プラグインを必ず 「 インポート 」 してください。

また、ユーザー Cordova プラグイン開発の技術支援 ( 有料 ) も、弊社にて承っております。サポートチームまで、お気軽に詳細を お問い合わせ ください。

ユーザー Cordova プラグインの検証

1. Monaca クラウド IDE上でプロジェクトを作成します。ここでは、最小限のテンプレート を使用します。

2. ユーザー Cordova プラグインの構成 でダウンロードしたユーザー Cordovaプラグインのサンプルをインポートします。

3. index.html ファイルへ次のコードを追加します ( ユーザー Cordova プラグインのサンプルを使用して、メッセージダイアログを表示するコードです )。

<script>
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    window.HelloWorld.say(
        function(result) { alert( "success: " + result ); },
        function(error) { alert( "error: " + error ); }
    );
}
</script>

4. 通常版の Monaca デバッガー上でプロジェクトを実行してみましょう。ユーザー Cordova プラグインが標準デバッガーに存在しないため、メッセージダイアログは表示されません。

5. カスタムビルド版 Monaca デバッガーをビルドします。ビルド方法につきましては、次のリンク先をご確認ください。

• iOS 用カスタムビルド版 Monaca デバッガーのビルド方法

• Android 用カスタムビルド版 Monaca デバッガーのビルドとインストール

6. カスタムビルド版 Monaca デバッガーをインストールします。

7. デバッガーを起動させ、ログイン画面上で デバッガー情報 をタップします。

8. デバッガー情報に、追加したユーザー Cordova プラグインが表示されていることを確認します ( 下のスクリーンショットを参照のこと )。

9. デバッガーにログインして、ユーザー Cordova プラグインを追加したプロジェクトを実行します。メッセージダイアログが表示されることを確認します。