gihyo.jpサイトのロゴ

HTML5とPhoneGapで作る、iPhone/Androidアプリ開発TIPS

第5回旧バージョン向けPhoneGapプラグインのアップデート手順

2012-10-31

PhoneGapの機能を拡張するにあたり、欠かせないのがPhoneGapプラグインです。サードパーティ製の便利なPhoneGapプラグインが多くリリースされていますが、中には旧バージョン向けに作成されたものもあり、現在のバージョンではうまく動作しないことがあります。最新のPhoneGapでプラグインを動作させるにあたり、必要な手順を確認しましょう。

PhoneGapプラグインのアップデート

旧バージョン向けに作成されたPhoneGapプラグインは、最新のPhoneGapのバージョンではうまく動作しないことがあります。バージョンを遡って、順繰りにプラグインのObjective-CコードやJavaコードを修正する必要があります。

PhoneGapはAdobeの買収やApacheへの寄贈、プロダクト名変更の経緯から、1.5.0以前と以後でコード中の名前空間が変更されました。また、PhoneGap 2.0.0にアップデートされた際にも多くの修正が加わり、ネイティブコードのほか、JavaScriptでプラグインを呼び出せるようにするための書き方も変更されています。

今回は、PhoneGapのアップグレードガイドや開発者のブログ、プラグインリポジトリの各種コミットログより、プラグインのアップデート手順をまとめて紹介します。

プラグインのアップデート手順（iOS）

基本的にCordova Plugin Upgrade Guideに記載されているとおりの手順でアップグレード可能です。JavaScriptのcordova.addPluginに関する部分以外は、公式マニュアルを参照しながらアップグレードを行うことをおすすめします。

iOS向けPhoneGapプラグインのアップデート手順は次のとおりです。

  • PhoneGap 1.5.0以前向けに作成されたプラグインを、1.5.0に対応
  • PhoneGap 1.5.0向けに作成されたプラグインを、1.6.x～1.9.0に対応
  • PhoneGap 1.6.x～1.9.0向けに作成されたプラグインを、2.0.0に対応
  • PhoneGap 2.0.0向けに作成されたプラグインを、2.1.0に対応

PhoneGap 1.5.0以前向けに作成されたプラグインを、1.5.0に対応

プラグイン中のJavaScriptファイル、Objective-Cヘッダファイル（.h⁠）⁠、および実装ファイル（.m）を修正します。

ファイルの種類修正内容
JavaScript文字列「PhoneGap」をすべて「cordova」に置換
ヘッダファイル（.h）, 実装ファイル（.m） 文字列「PHONEGAP_FRAMEWORK」をすべて「CORDOVA_FRAMEWORK」に置換
ヘッダファイル（.h）, 実装ファイル（.m）文字列「<PhoneGap/」をすべて「<Cordova/」に置換
ヘッダファイル（.h）, 実装ファイル（.m）クラス接頭辞「PG」をすべて「CDV」に置換
ヘッダファイル（.h）, 実装ファイル（.m）文字列「[self appViewController]」をすべて「self appViewController」に置換

JavaScriptにおいて、PhoneGap名前空間がPhoneGap 1.5.0ですべてCordovaに変更されました。

// 修正前
PhoneGap.exec(...);
PhoneGap.addConstructor(function(){
    PhoneGap.addPlugin(...);
});
// 修正後
Cordova.exec(...);
Cordova.addConstructor(function(){
    Cordova.addPlugin(...);
});

Objective-Cコードにおいても同様、PhoneGapという名称はすべてCordovaに置きかえる必要があります。

// 修正前
#ifdef PHONEGAP_FRAMEWORK
#import <PhoneGap/PGPlugin.h>
[ super appViewController ] ... ]
// 修正後
#ifdef CORDOVA_FRAMEWORK
#import <Cordova/CDVlugin.h>
[self appViewController ... ]

PhoneGap 1.5.0向けに作成されたプラグインを、1.6.x～1.9.0に対応

プラグイン中のJavaScriptファイルを修正します。

ファイルの種類修正内容
JavaScript文字列「Cordova」をすべて「cordova」に置換

JavaScript中のグローバルCordovaオブジェクト名は、小文字表記のcordovaとなりました。修正例は次のとおりです。

// 修正前
Cordova.exec(...);
Cordova.addConstructor(function(){
    Cordova.addPlugin(...);
});
// 修正後
cordova.exec(...);
cordova.addConstructor(function(){
    cordova.addPlugin(...);
});

PhoneGap 1.6.x～1.9.0向けに作成されたプラグインを、2.0.0に対応

プラグイン中のJavaScriptファイル、Objective-Cヘッダファイル（.h⁠）⁠、および実装ファイル（.m）を修正します。

ファイルの種類修正内容
JavaScriptcordova.addPluginでプラグインを登録している箇所を削除し、別の方法で登録する
ヘッダファイル（.h）, 実装ファイル（.m）#import文の確認
ヘッダファイル（.h）, 実装ファイル（.m）verifyArgumentsメソッド, appViewControllerメソッドが使用されている箇所を、別の方法で実装する

PhoneGap 2.0.0ではcordova.jsよりaddPluginメソッドが削除されました。このため、プラグインのJavaScriptにてcordova.addPluginメソッドを使ってプラグインを登録しているコードは動作しなくなります。

cordova.addPluginでは、windowオブジェクトのplguins以下にプラグインを登録していました。この手法で修正を行えば、最低限の修正で済みます。修正例は次のとおりです。

// 修正前
cordova.addConstructor(function() {
    cordova.addPlugin('MyPlugin', new MyPlugin());
});
// 修正後
if(!window.plugins) 
{
    window.plugins = {};
}
if (!window.plugins.MyPlugin) 
{
    window.plugins.MyPlugin = new MyPlugin();
}

また、PhoneGap 2.0.0ではCordovaLibプロジェクトをサブプロジェクトとして扱います。Objective-CでCORDOVA_FRAMEWORKスタイルのインポートを行うにあたり、#import文を次のように修正します。

// 修正前
#import <Cordova/CDV.h>
// 修正後
#import "CDV.h"

PhoneGap 2.0.0では、verifyArgumentsメソッド, appViewControllerメソッドが削除されました。コード中にこれらのメソッドで機能が実装されている箇所は、ほかの方法で機能を実現する必要があります。

PhoneGap 2.0.0向けに作成されたプラグインを、2.1.0に対応

ファイルの種類修正内容
ヘッダファイル（.h）, 実装ファイル（.m）文字列「cdvjk_JSONString」をすべて「JSONString」に置換

JSONKitと外部ライブラリとの名前空間の問題（CB-1000: Namespace issue of JSONKit and other external libraries / CB-1453: Namespace issue of JSONKit (JSONKitSerializingBlockAdditions)）で、接頭辞にcdvjk_を付けているコードを修正する必要があります。修正例は次のとおりです。

// 修正前
[myDict cdvjk_JSONString];
// 修正後
[myDict JSONString];

PhoneGap 2.1.0ではこのほかにも、プラグインシグネチャが更新されています。旧来のシグネチャは非推奨（deprecated）となっているので、次期バージョンでも利用したい場合は修正しておくと良いでしょう。

// 修正前
- (void) myMethod:(NSMutableArray*)arguments withDict:(NSMutableDictionary*)options;
// 修正後
- (void) myMethod:(CDVInvokedUrlCommand*)command;

プラグインのアップデート手順（Android）

執筆時点ではApache Cordova Documentationにまとまった手順が記述されていません。主要開発者の一人であるSimon MacDonald氏のブログ - Simon Mac DonaldやAndroid版Cordovaリポジトリのコミットログ、Android版PhoneGap/Cordovaプラグインを公開しているGitHubのコミットログなどを参考にすると良いでしょう。

Android向けPhoneGapプラグインのアップデート手順は次のとおりです。

  • PhoneGap 1.5.0以前向けに作成されたプラグインを、1.5.0に対応
  • PhoneGap 1.5.0向けに作成されたプラグインを、1.6.x～1.9.0に対応
  • PhoneGap 1.9.0向けに作成されたプラグインを、2.0.0に対応

PhoneGap 1.5.0以前向けに作成されたプラグインを、1.5.0に対応

プラグイン中のJavaScriptファイル、Javaファイル、プラグインXMLファイル（res/xml/plugins.xml。PhoneGap 2.0.0以降ではres/xml/config.xml）を修正します。また、プラグインを配置するディレクトリ構成も変更する必要があります。

ファイルの種類修正内容
JavaScript文字列「PhoneGap」をすべて「cordova」に置換
Java文字列「com.phonegap」をすべて「org.apache.cordova」に置換
Javaメンバ変数「this.ctx」の呼び出し方を、「⁠this.ctx.getContext()」または「this.ctx.getIntent()」または「((DroidGap)this.ctx).getIntent()」に修正

プラグイン中JavaScriptにおいて、PhoneGap名前空間がPhoneGap 1.5.0ですべてcordovaに変更されました。cordovaのスペルはすべて小文字であることに注意してください。

// 修正前
PhoneGap.exec(...);
PhoneGap.addConstructor(function(){
    PhoneGap.addPlugin(...);
});
// 修正後
cordova.exec(...);
cordova.addConstructor(function(){
    cordova.addPlugin(...);
});

また、JavaファイルではPhoneGapのクラス名が変更されています。import文にてPhoneGapのクラスを参照している箇所を、すべて次のように修正します。

// 修正前
import com.phonegap.api.Plugin;
import com.phonegap.api.PluginResult;
// 修正後
import org.apache.cordova.api.Plugin;
import org.apache.cordova.api.PluginResult;

クラス名の変更に伴ってプラグインの名前を変更した場合は、プラグインを配置するディレクトリ構成も修正する必要があります。たとえばcom.phonegap.MyPluginの場合、srcディレクトリ以下の構成は

com/phonegap/MyPlugin/MyPlugin.java

となっています。これをorg.apache.cordova.MyPluginに修正した場合、srcディレクトリ以下の構成は次のように修正します。

org/apache/cordova/MyPlugin/MyPlugin.java

同じ要領で、res/xml/plugins.xml（PhoneGap 2.0.0以降ではres/xml/config.xml）でプラグインを追加するマークアップを修正します。

// 修正前
<plugin name="MyPlugin" value="com.phonegap.plugin.MyPlugin" />
// 修正後
<plugin name="MyPlugin" value="org.apache.cordova.plugin.MyPlugin" />

最後に、メンバ変数の呼び出し方を修正します。PhoneGap 1.5以降ではメンバ変数this.ctxはCordavaInterfaceになります。this.ctxでコンテキストを取得しているプラグインはエラーが起きます。this.ctxでコンテキストを取得しているプラグインでは、コードを次のように修正します。

// 修正前
this.ctx
// 修正後
this.ctx.getContext()
// または
this.ctx.getIntent()
// または
((DroidGap)this.ctx).getIntent()

PhoneGap 1.5.0向けに作成されたプラグインを、1.6.x～1.9.0に対応

プラグイン中のJavaファイルを修正します。

ファイルの種類修正内容
Java文字列「ctx.getContext()」をすべて「cordova.getContext() 」に置換
Java文字列「ctx.startActivity()」をすべて「cordova.getActivity().startActivity() 」に置換
Java文字列「ctx.getSystemService()」をすべて「cordova.getActivity().getSystemService() 」に置換
Java文字列「ctx.getAssets()」をすべて「cordova.getActivity().getAssets()」に置換
Java文字列「ctx.runOnUiThread()」をすべて「cordova.getActivity().runOnUiThread() 」に置換
Java文字列「ctx.getApplicationContext()」をすべて「cordova.getActivity().getApplicationContext()」に置換
Java文字列「ctx.getPackageManager()」をすべて「cordova.getActivity().getPackageManager()」に置換
Java文字列「ctx.getSharedPreferences()」をすべて「cordova.getActivity().getSharedPreferences()」に置換
Java文字列「ctx.unregisterActivity()」をすべて「cordova.getActivity().unregisterActivity()」に置換
Java文字列「ctx.getResources()」をすべて「cordova.getActivity().getResources()」に置換

CordovaInterfaceのメンバ変数「ctx」が「cordova」となりました。これに伴い、いくつかのメソッドの呼び出し方が変更になります。上記の表に従って、各箇所を修正します。

PhoneGap 1.9.0向けに作成されたプラグインを、2.0.0に対応

プラグイン中のJavaScriptファイルを修正します。

ファイルの種類修正内容
JavaScriptcordova.addPluginでプラグインを登録している箇所を削除し、別の方法で登録する

PhoneGap 2.0.0ではプラグイン設定ファイル「res/xml/plugins.xml」と、外部リソース制限設定ファイル「res/xml/cordova.xml」が、「⁠res/xml/config.xml」に統合されました。またiOSと同様、重要な更新としてcordova.jsよりaddPluginメソッドが削除されています。

Failed to run constructor: TypeError: Object #<Object> has no method 'addPlugin'

iOS版と同様、cordova.addPluginではwindowオブジェクトのplguins以下にプラグインを登録していました。修正例は次のとおりです。

// 修正前
cordova.addConstructor(function() {
    cordova.addPlugin('MyPlugin', new MyPlugin());
});
// 修正後
if(!window.plugins) 
{
    window.plugins = {};
}
if (!window.plugins.MyPlugin) 
{
    window.plugins.MyPlugin = new MyPlugin();
}

PhoneGapでは新バージョンがリリースされるにあたり、さまざまな機能が追加されていきます。Cordova APIに用意されていない機能や、JavaScriptで実現が難しい機能はプラグインを開発・導入することで解決の糸口がつかめるかも知れません。オープンソース開発者の方達に敬意を払い、PhoneGapを有効的に活用し、コミュニティに参加していきましょう。

おすすめ記事

記事・ニュース一覧