10 MAFアプリケーションでのプラグインの使用方法
この章の内容は次のとおりです。
MAFアプリケーションでのプラグインの使用方法の概要
MAFには様々なCordovaプラグインがパッケージ化されているので、MAFアプリケーションはこのプラグインを使用してデプロイ先のデバイスと対話できます。
コア・プラグインは、MAFに用意されているデフォルトのプラグインです。これらのプラグインはmaf-application.xmlの概要エディタで確認します。たとえば、MAFアプリケーションでデバイスの電子メール機能やコンタクト先機能へのアクセスに使用する電子メールプラグインやコンタクト先プラグインなどがあります。Android、iOSおよびWindowsプラットフォームで使用されているCordovaバージョンをmaf-application.xmlファイルの概要エディタで確認します。プラグインの説明を表示するには、「コア・プラグイン」リスト(図10-1を参照)でプラグインを選択します。新規作成したMAFアプリケーションでは、ネットワーク情報プラグインおよび記憶域アクセス・プラグインがデフォルトで有効になっています。
iOSデバイス上のすべてのアプリケーションにネットワーク・アクセスがデフォルトで許可されます。この動作は変更できません。Androidデバイスにデプロイされたアプリケーションでネットワーク・アクセスが不要な場合は、ネットワーク情報プラグインを無効にします。ネットワーク情報プラグインは、Androidエミュレータまたはデバイス上で実行されているアプリケーションのリモート・デバッグを容易にする場合は有効にする必要があります。記憶域アクセス・プラグインは、Androidプラットフォームでローカル記憶域へのアクセスを有効にし、MAFアプリケーションによるSDカード(存在する場合)への書込みを有効にする、Android固有のプラグインです。MAFアプリケーションをiOSまたはWindowsプラットフォームにデプロイした場合、MAFは記憶域アクセス・プラグインの設定を無視します。「MAFアプリケーションでのコア・プラグインの有効化」の説明に従って、コア・プラグインを有効にします。
MAFに用意されているコア・プラグインではMAFアプリケーションの要件を満たさない場合は、追加プラグインを登録できます。「カスタムCordovaプラグイン開発の概要」(http://blogs.oracle.com/mobile/entry/introduction_to_custom_cordova_plugin)および「MAFアプリケーションでの追加プラグインの登録」を参照してください。MAFアプリケーションでコア・プラグインを有効にするかまたは任意の追加プラグインを登録したら、そのプラグインの機能にアクセスするアプリケーション機能内のコンテンツを作成します。「MAFアプリケーションでのプラグインの使用方法」を参照してください。
MAFアプリケーションのデプロイメントは、追加プラグインの登録後、次の理由で失敗する場合があります。
-
MAFアプリケーションが使用するプラグイン間でファイル名の競合があります。
-
登録した追加プラグインは、適切に機能するために依存プラグインが必要です。
詳細は、MAFアプリケーション組込みプラグインのデプロイおよびApache Cordova Plugmanのプロキシ設定の構成を参照してください。「iOSのデバイス機能にアクセスするプラグインの使用方法の説明の指定」で説明しているように、MAFアプリケーションがiOSデバイス上のプライベート・データ(連絡先や写真など)にアクセスするプラグインを使用するときに、使用方法の説明を指定しておかないと、iOSプラットフォームへのデプロイに失敗することがあります。
以前のリリースのMAFで作成したMAFアプリケーションを移行する場合は、『Oracle Mobile Application Frameworkのインストール』の前のリリースからMAF 2.5.1へのCordovaプラグインの移行に関する項を参照してください。
注意:
アプリケーションのプラグインを管理するためにmaf-application.xmlファイルを編集すると、maf-plugins.xmlファイルのリビジョンが作成されます。両方のファイルへのアクセスを行う「アプリケーション・リソース」ペインの「ADF-META-INF」ノードを、次の図に示します。
MAFアプリケーションでのコア・プラグインの有効化
新規作成したMAFアプリケーションでは、2つのコア・プラグインがデフォルトで有効になります(ネットワーク情報および記憶域アクセス・プラグイン)。
MAFアプリケーションでコア・プラグインを有効にする方法
コア・プラグインは、MAFアプリケーションのmaf-application.xmlファイルの概要エディタを使用して有効化します。
MAFアプリケーションでコア・プラグインを有効にする手順:
MAFアプリケーションでコア・プラグインを有効にする場合の処理
概要エディタでプラグインを有効にすると、JDeveloperによってアプリケーションのmaf-plugins.xmlファイルが編集され、MAFアプリケーションで有効なプラグインを特定するエントリが追加されます。
例10-1に、電子メール、ネットワーク情報および記憶域アクセスの各プラグインが有効になっているMAFアプリケーションのエントリを示します。デバイスの電子メール・クライアントを使用し、インターネットおよびAndroidデバイスのデバイス記憶域にアクセスしているMAFアプリケーションでは、これらのプラグインの有効化は必須です。
例10-1 maf-plugins.xmlファイル内の有効なコア・プラグイン
<?xml version="1.0" encoding="UTF-8" ?>
<maf-plugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/adf/mf">
<cordova-plugins>
<core-cordova-plugin id="c1" pluginId="maf-cordova-plugin-network-information"/>
<core-cordova-plugin id="c2" pluginId="maf-cordova-plugin-storage-access"/>
<core-cordova-plugin id="c3" pluginId="com.oracle.maf.email"/>
</cordova-plugins>
</maf-plugins>
MAFアプリケーションでの追加プラグインの登録
MAFに用意されたコア・プラグインでは提供されていない機能がMAFアプリケーションで必要な場合は、MAFアプリケーションに追加プラグインを登録します。
ファイアウォールの内側で作業する場合、Apache Cordova Plugmanのプロキシ設定の構成で説明されているように、MAFが起動するplugmanユーティリティのプロキシ・サーバー設定を構成します。
追加プラグインを登録する方法
MAFアプリケーションの追加プラグインを登録するには、アプリケーションのmaf-application.xmlファイルの概要エディタを使用します。
開始する前に、アプリケーション、およびアプリケーションに登録されるプラグインが同じドライブに格納されていることを確認します。たとえば、Windows環境でC:ドライブにアプリケーションが格納されている場合、そのアプリケーションに登録するプラグインもC:ドライブに格納する必要があります。これにより、JDeveloperでは相対パスを使用してアプリケーションにプラグインを正常に登録できます。
MAFアプリケーションに追加プラグインを登録するには:
- 「アプリケーション」ウィンドウで、「アプリケーション・リソース」パネルを展開します。
- 「アプリケーション・リソース」パネルで「ディスクリプタ」を展開し、「ADF META-INF」を展開します。
- maf-application.xmlファイルをダブルクリックし、表示される概要エディタで「プラグイン」ナビゲーション・タブをクリックします。
- 「追加のプラグイン」セクションを展開し、「追加」アイコンをクリックして、ダイアログを表示します。
- アプリケーションに登録されるプラグインを格納しているディレクトリを参照して選択します。
MAFアプリケーションに追加プラグインを登録する場合の処理
MAFアプリケーションで使用するプラグインのソース・ファイルを選択すると、JDeveloperによってアプリケーションのmaf-plugins.xmlファイルが編集され、MAFアプリケーションで有効なプラグインを特定するエントリが追加されます。
例10-2は、MAFアプリケーションにグローバリゼーション・プラグイン(次の図を参照)が登録されている場合のmaf-plugins.xmlファイル内のエントリを示したものです。
例10-2 maf-plugins.xmlファイル内の追加プラグイン
<?xml version="1.0" encoding="UTF-8" ?>
<maf-plugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/adf/mf">
<cordova-plugins>
<core-cordova-plugin id="c1" pluginId="maf-cordova-plugin-network-information"/>
<cordova-plugin id="c2" pluginId="cordova-plugin-globalization"
path="../../../../CordovaPlugins/cordova-plugin-globalization/">
<platform id="p1" name="android" enabled="true"/>
<platform id="p2" name="ios" enabled="true"/>
<platform id="p3" name="windows" enabled="true"/>
</cordova-plugin>
</cordova-plugins>
</maf-plugins>MAFアプリケーション組込みプラグインのデプロイ
MAFアプリケーション組込みプラグインのデプロイメントは、選択したデプロイメント方法によって異なります。
FARへのデプロイメント
FARへのデプロイメントには、アプリケーションのmaf-plugins.xmlファイルのコピー(ファイル名: jar-maf-plugins.xml)が含まれます。これは、アプリケーションのmaf-plugins.xmlファイルと同じですが、各プラグインのpath属性値が空の文字列である点が異なります。FARデプロイメントにはプラグインのソース・ファイルは含まれません。
モバイル・アプリケーション・アーカイブ・ファイルへのデプロイメント
モバイル・アプリケーション・アーカイブ・ファイルへのデプロイメントには、すべてのpath属性が空の文字列に設定された、アプリケーションのmaf-plugins.xmlファイルのコピーが含まれます。
Android、iOSまたはWindowsデプロイメント・プロファイルを使用したデプロイメント
Android、iOSまたはWindowsデプロイメント・プロファイルを使用したデプロイメント時、JDeveloperはアプリケーションをビルドおよびデプロイするツールを起動します。次に、これらのツールがCordovaプラグイン・ツールを起動して、構成済のプラグインをそのソースの場所からデプロイメント・フォルダにインストールします。
プラグイン間における名前の競合の解決
MAFアプリケーションで使用されている複数のプラグインに同じ名前のリソース・ファイルが含まれている場合、名前の競合が原因でデプロイメントに失敗する可能性があります。たとえば、MAFアプリケーションで2つのプラグインを使用し、両方のリソース・ファイルがarrays.xmlである場合、デプロイメントは失敗します。
このような名前の競合を解決するには、他のプラグインのリソース・ファイル名と競合しているプラグインのリソース・ファイル名を変更します。1番目のプラグインのplugin.xmlファイル内で、リソース・ファイルへの参照を更新します。この例では、1番目のプラグインのarray.xmlリソース・ファイル名をpluginone_arrays.xmlに変更して、プラグインのplugin.xmlファイルを次のように編集する必要があります。
<source-file src="src/android/LibraryProject/res/values/pluginone_arrays.xml"
target-dir="res/values"/>
iOSにデプロイするMAFアプリケーションの使用方法の説明
デバイス機能(連絡先やカメラなど)へのアクセスを要求するプラグインを有効化すると、iOSプラットフォームへのMAFアプリケーションのデプロイメントは失敗します。「iOSのデバイス機能にアクセスするプラグインの使用方法の説明の指定」で説明するように、使用方法の説明を指定してください。
不足している依存プラグインの追加
MAFアプリケーションで使用する追加プラグインに必要なプラグイン(依存プラグイン)が検出されないと、デプロイメントに失敗する場合があります。このシナリオは、ファイアウォールの内側で作業している場合に発生する可能性があります。デプロイメント時に、JDeveloperは、プラグイン依存を管理するためにApache Cordovaのツールを起動します。これらのツールは、依存プラグインのダウンロードを許可するようにプロキシ設定が構成されていないと、依存プラグインのダウンロードに失敗する場合があります。このシナリオを回避するには、Apache Cordova Plugmanのプロキシ設定の構成で説明されているように、plugmanユーティリティのプロキシ・サーバー設定を構成するか、欠落している依存プラグインを個別にダウンロードし、MAFアプリケーションに追加します。不足している依存プラグインの追加は、MAFアプリケーションに他のプラグインを追加する場合と同じ方法で行います。「MAFアプリケーションでの追加プラグインの登録」を参照してください。依存するプラグインを追加したら、例10-3に示すように、maf-plugins.xmlファイル内でそれを必要とするプラグインの前に追加されていることを確認します。
例10-3 MAFアプリケーションへの依存プラグインの追加
<maf-plugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/adf/mf">
<cordova-plugins>
....
<cordova-plugin id="c2" pluginId="com.example.dependent.dependentPlugin"
path="../../../../../plugins/Dependent-Plugin-Required-By-PluginWithID_c3/">
...
<cordova-plugin id="c3" pluginId="com.example.plugin"
path="../../../../../plugins/AdditionalPlugin/">
...
</cordova-plugins>
</maf-plugins>
機能アーカイブ・ファイルからのプラグインのインポート
jar-maf-plugins.xmlファイルが格納されたFARをアプリケーションにインポートすると、jar-maf-plugins.xmlファイルの内容は使用するアプリケーションのmaf-plugins.xmlファイルにマージされます。JDeveloperではマージに関する情報を「メッセージ」ウィンドウに記録します。
FARからインポートするプラグインがすでにコンシューマ・アプリケーションのmaf-plugins.xmlファイルに存在する場合、プラグインはアプリケーションに存在するのでマージされないというメッセージがJDeveloperによってログに記録されます。
FARからインポートするプラグインがコンシューマ・アプリケーションのmaf-plugins.xmlファイルに存在しない場合、JDeveloperはそのプラグインをアプリケーションのmaf-plugins.xmlファイルに追加します。このシナリオでは、「MAFアプリケーションでの追加プラグインの登録」の説明に従って、新しくインポートしたプラグインへのパスを設定する必要があります。
MAFアプリケーションでのプラグインの使用方法
MAFアプリケーションで有効化されたプラグインを呼び出し、カメラなどのデバイス機能と対話したり、電子メール、バーコード・スキャナ・アプリケーションなど、デバイスの他のアプリケーションを使用したりすることができます。
Java、MAF AMXページおよびローカルHTMLからプラグインを起動する方法の詳細は、「カスタムCordovaプラグインのMAFアプリへの統合」(http://blogs.oracle.com/mobile/entry/integrating_a_custom_cordova_plugin)を参照してください。
BarcodeDemoサンプル・アプリケーションでは、このタスクを実現する方法も示しています。
次の図はmaf-feature.xmlファイルを示しています。ここでは、「スキャナ」機能用に、様々なプラットフォームのコンテンツと制約を定義できます。
図は、BarcodeDemoサンプル・アプリケーションの実行時にユーザーのデバイス上にレンダリングされるMAF AMXページのボタン(Scan)を示しています。このボタンは、管理対象Beanのメソッドを起動し、その管理対象のBeanメソッドは、BarcodeScannerプラグインをコールするJavaScript関数を起動します。
例10-4に、BarcodeDemoサンプル・アプリケーションから抽出したいくつかのコードを示します。
BarcodeDemoサンプル・アプリケーション以外に、MAFアプリケーションで追加プラグインを使用する方法を示すその他のサンプル・アプリケーションとして、BeaconDemo、FakeBeaconおよびDatePickerがあります。「サンプルのMAFアプリケーション」を参照してください。
例10-4 バーコード・スキャナ・プラグインの使用方法
<!-- The following code snippet from the scanner.amx file shows how the Scan button invokes the scanBarcode method in the managed bean -->
<amx:commandButton text="Scan" id="cl2" actionListener="#{viewScope.BarcodeBean.scanBarcode}"/>
<!-- The following code snippet from the BarcodeBean.java file shows how the scanBarcode managed bean method invokes a JavaScript function -->
public void scanBarcode (ActionEvent event)
{
// Invokes a JavaScript function named ���scanBarcodeFromJavaBean���
AdfmfContainerUtilities.invokeContainerJavaScriptFunction(AdfmfJavaUtilities.getFeatureId(),
"scanBarcodeFromJavaBean",
new Object[] { });
}
<!-- The following code snippet from the scanner.js file shows how the JavaScript function accesses the barcode scanner and sets the resulting value in a managed bean field.-->
function scanBarcodeFromJavaBean(options)
{
cordova.plugins.barcodeScanner.scan(
function(result)
function onSuccess(result) {
adf.mf.api.setValue( { "name": "#{viewScope.BarcodeBean.barcodeError}",
"value": ""},
function() {},
function() {});
adf.mf.api.setValue( { "name": "#{viewScope.BarcodeBean.barcodeResult}",
"value": result.text},
function() {},
function() {});
adf.mf.api.setValue( { "name": "#{viewScope.BarcodeBean.barcodeFormat}",
"value": result.format},
function() {},
function() {});
adf.mf.api.setValue( { "name": "#{viewScope.BarcodeBean.barcodeCancelled}",
"value": result.cancelled == 1 ? "Yes" : "No"},
function() {},
function() {});
}
function onError(error) {
adf.mf.api.setValue( { "name": "#{viewScope.BarcodeBean.barcodeError}",
"value": "ERROR: " + error.text},
function() {},
function() {});
}
// Callable externally
scanBarcodeFromJavaBean = function() {
cordova.plugins.barcodeScanner.scan(onSuccess, onError);
}
iOSのデバイス機能にアクセスするプラグインの使用方法の説明の指定
iOSにデプロイするMAFアプリケーションは、そのMAFアプリケーションがユーザーのデータにアクセス可能なハードウェア機能(デバイスのカメラなど)を使用する場合、使用方法の説明が必要になります。
iOSプラットフォームでは、アプリケーションが機能と潜在的に機密性の高いユーザー・データにアクセスする許可をエンド・ユーザーに求めるために使用するシステム・ダイアログに表示するために、こうした説明を必要とします。図は、テキスト「This application allows the user to upload photos from their photo library」がMAFアプリケーションからの使用方法の説明である場合の例を示しています。
MAFの基本的な使用方法では、使用方法の説明の指定が必要になる機能は有効化されていません。ただし、使用方法の説明が必要になるコア・プラグインや、使用方法の説明が必要になるその他のプラグインを有効化している場合は、アプリケーションを正常にデプロイするために使用方法の説明を指定する必要があります。使用方法の説明を指定していないと、アプリケーションがクラッシュすることや、Apple App Storeに拒否されることがあります。
カメラ、連絡先、地理的位置のコア・プラグインは、使用方法の説明を必要とします。MAFは、こうしたコア・プラグインに対して、次に示す汎用的な使用方法の説明を指定しています。
-
Camera: カメラ・プラグインは、デバイスのカメラとフォト・ライブラリへのアクセスが可能です。このプラグインは、Cocoaキーの
NSCameraUsageDescriptionとNSPhotoLibraryUsageDescriptionに対する使用方法の説明を必要とします。 -
Contacts: 連絡先プラグインは、デバイス上のアドレス帳へのアクセスが可能です。このプラグインは、Cocoaキーの
NSContactsUsageDescriptionに対する使用方法の説明を必要とします。 -
Geolocation: 地理的位置プラグインは、デバイス上のデバイス位置情報サービスを使用します。このプラグインはCocoaキーの
NSLocationWhenInUseUsageDescriptionに対する使用方法の説明を必要とします。
これらの汎用的な使用方法の説明は、これらの汎用的な使用方法の説明は、MAFアプリケーションを正常にデプロイするためのiOSプラットフォームの技術的要件を満たしています。具体的な使用方法の説明を指定することをお薦めします(プラグインが要求する機能やデータへのアクセスをアプリケーションが必要としている理由を説明してください)。MAFアプリケーションに登録する追加のプラグインが使用方法の説明を必要とする場合は、使用方法の説明を指定する必要があります。
使用方法の説明は、アプリケーションのリソース・バンドル.XLFファイルで指定します。使用方法の説明は、trans-unit要素のid属性の値として、iOSプラットフォームのCocoaキーを使用します。次の例は、MAFアプリケーションがユーザーのフォト・ライブラリへのアクセス許可をエンド・ユーザーに求めるときに表示される使用方法の説明を示しています。
<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="1.1" xmlns="urn:oasis:names:tc:xliff:document:1.1">
<file source-language="en" original="mobile.ViewControllerBundle" datatype="x-oracle-adf">
<body>
<trans-unit id="NSPhotoLibraryUsageDescription">
<source>This application allows the user to upload photos from their photo library.</source>
...
また、MAFアプリケーションで複数のロケールをサポートする場合は、ロケール固有のリソース・バンドルにも使用方法の説明を指定します。次の例は、対応する使用方法の説明を示しています。これは、ロケールがFrenchの場合にレンダリングされます。
...
<file source-language="fr" original="mobile.ViewControllerBundle_fr" datatype="x-oracle-adf">
<body>
<trans-unit id="NSPhotoLibraryUsageDescription">
<source>Cette application permet �� l'utilisateur de t��l��charger des photos ��
partir de leur biblioth��que de photos.</source>
...
デプロイメント時に、MAFは、リソース・バンドルで定義されている使用方法の説明を、iOSデバイスにデプロイされるアプリケーションのinfo.plistファイルに移入します。
MAFアプリケーションのリソース・バンドルの作成の詳細と、ロケール固有のリソース・バンドルの作成方法は、「MAFアプリケーションのローカライズ」を参照してください。
使用方法の説明を識別するCocoaキーのリストは、Apple社のCocoaキーのドキュメントで、キーの名前にUsageDescriptionが付加されたキーについて参照してください(https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html)。
CordovaプラグインにWindowsプラットフォーム上のネイティブUIでの実行を許可する
Windowsプラットフォーム上でネイティブUIを表示または使用する必要があるプラグイン用に、windows-run-in-core-window="enabled"属性をmaf-plugins.xmlファイル・エントリに追加する必要があります。
そのようなプラグインの例はcordova-plugin-media-captureで、Windows上でアプリケーションによるイメージ、ビデオまたはオーディオのキャプチャを開始します。
Windowsプラットフォーム上で実行する標準のCordovaアプリケーションは、CordovaとそのプラグインがメインHTMLページ内で実行する、1ページ・アプリケーションのように実行します。AndroidおよびiOSプラットフォームで実行するCordovaアプリケーションは、コンテナ内で実行します。これらの最新の2つのプラットフォームのWebViewは、カメラなど、プラグインによりアクセスできるようになる機能をユーザーが呼び出せるように、UIを表示し、Cordovaプラグインをロードします。
MAFアプリケーションは、アプリケーションがインストールされているデバイス(Android、iOSまたはWindowsデバイス)上のコンテナ内で実行します。Windows上で実行しネイティブUIを使用するMAFアプリケーション内のCordovaプラグインを有効にするときは、MAFアプリケーションがWindowsデバイスで必要なアプリケーションを呼び出せるように、図に示すコアWindowsで実行チェックボックスを選択する必要があります。プライマリ・プラグインが正常に機能するように、プライマリ・プラグインが必要とする追加のプラグインに対するこの属性も設定する必要があります。
図10-6 プラグインがWindowsでネイティブUIにアクセスするためのコアWindowsで実行チェックボックス
「図10-6 プラグインがWindowsでネイティブUIにアクセスするためのコアWindowsで実行チェックボックス」の説明
次の例に示すように、上の図に示すコアWindowsで実行チェックボックスを選択すると、アプリケーションのAppRootDirectory\.adf\META-INFディレクトリのmaf-plugins.xmlファイルが更新されます。
この属性のデフォルト値はdisabled (windows-run-in-core-window="disabled")です。
例10-5 WindowsでネイティブUIにアクセスするためのmaf-plugins.xmlファイルの構成
<maf-plugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/adf/mf">
<cordova-plugins>
<cordova-plugin id="c3" pluginId="cordova-plugin-media-capture" path="../../plugins/cordova-plugin-media-capture/"
windows-run-in-core-window="enabled">
<platform id="p1" name="android" enabled="true"/>
<platform id="p2" name="ios" enabled="true"/>
<platform id="p3" name="windows" enabled="true" />
</cordova-plugin>
...
// The cordova-plugin-media-capture requires the cordova-plugin-file plugin be enabled so that media files
// can be saved on the device. For that reason, you must also configure the additional Windows-specific attribute here.
<cordova-plugin id="c4" pluginId="cordova-plugin-file" path="../../plugins/cordova-plugin-file/"
windows-run-in-core-window="enabled">
...
Apache Cordova Plugmanのプロキシ設定の構成
ファイアウォールの内側で作業する場合、構成ファイルにプロキシ・サーバー設定を入力して、MAFが起動するApache Cordova plugmanユーティリティに渡します。これにより、MAFアプリケーションに追加のプラグインを登録する際に、plugmanが必要な依存性をすべてダウンロードできます。
次のエントリを指定して、configファイルを/jdeveloperInstallDir/jdev/extensions/oracle.maf/tools/plugmanディレクトリに作成します。
proxy=http://your.proxy.server.com:80 https-proxy=https://your.proxy.server.com:80
追加プラグインをMAFアプリケーションに登録し、追加プラグインまたは他の依存性のダウンロードが必要になる場合、これにより、MAFが起動するplugmanユーティリティがそのタスクを正常に実現できます。