デバイスのネイティブ機能を診断するCordova diagnostic pluginを試す

BluetoothやNFCなどのネイティブ機能を利用したMonacaアプリを開発する場合、まずはじめに確認しなければならないのが、端末側が対象の機能をサポートしているかどうかです。
開発中はつい自分の環境がデファクトだと思ってしまいがちですが、端末によってはネイティブ機能そのものが利用できないといったこともありえます。
そうした際にエラーハンドリングを行うためには、まずその機能が存在しているのか、使えるのかと言った診断を行われなければなりません。

そのためのCordovaプラグインが Cordova diagnostic plugin になります。

プラグインのインストール方法

Monaca IDEの「Cordovaプラグインの管理」画面から cordova.plugins.diagnostic をインポートしてください。

なお、今回の検証環境は以下の通りです。

Cordovaバージョン：7.1.0
Cordovaプラグインバージョン：4.0.3
検証端末：Galaxy S6 (Android 7.0) / iPhone 7 Plus (iOS 11.4.1)

上記の検証環境以外では、本記事に掲載されている通りに動作しない可能性があります。あらかじめご了承ください。

診断できる機能

Cordova diagnostic plugin で診断できる機能は以下の通りです。

位置情報
Bluetooth
WiFi
カメラ
通知
マイク
アドレス帳
カレンダー
リマインダー（iOSのみ）
モーション（iOSのみ）
NFC（Androidのみ）
外部ストレージ（Androidのみ）

ただし機能によってはiOSでサポートされていないものもあります。

基本的な使い方

対象の機能が有効かどうかを調べるときは、ほとんどの場合以下のような名前のメソッドを使います。

is{機能名}Enabled()

位置情報の場合は次のようになります。

cordova.plugins.diagnostic.isLocationEnabled(function(enabled){
    // trueなら有効。falseなら無効
    console.log("Location setting is " + (enabled ? "enabled" : "disabled"));
}, function(error){
    console.error("The following error occurred: "+error);
});

また、機能が有効であってもパーミッション設定でアプリに対して対象機能へのアクセスが許可されていない場合もあります。
そういったときは以下のような名前のメソッドで利用可能かどうかを調べます。

is{機能名}Available()

位置情報の場合は次のようになります。

cordova.plugins.diagnostic.isLocationAvailable(function(available){
    // trueなら利用可。falseなら利用不可
    console.log("Location is " + (available ? "available" : "not available"));
}, function(error){
    console.error("The following error occurred: "+error);
});

一つ目の引数が成功時のコールバック、二つ目が失敗時のコールバックになります。
有効かどうか、利用可能かどうかをチェックする程度であればどの機能でもメソッドの使い方はほぼ同じです。

Bluetooth

iOSの場合、Bluetoothに関する診断には多くの制限があります。Bluetoothのステータス（有効／無効）はiOSでも取得できます。

cordova.plugins.diagnostic.bluetoothState

BluetoothとBLEがそれぞれサポートされているかどうかを診断するメソッドはAndroidでしか使えません。

// Bluetoothがサポートされているかどうか
cordova.plugins.diagnostic.isBluetoothEnabled

// LTEがサポートされているかどうか
cordova.plugins.diagnostic.hasBluetoothLESupport

基本的には診断をするのみなのですが、一部の機能については設定もできます。Bluetoothのステータス変更は cordova.plugins.diagnostic.setBluetoothState で可能です。

cordova.plugins.diagnostic.requestBluetoothAuthorization

iOSの場合、Bluetoothを使う前に確認ダイアログを出します。OKすれば、ステータス変更を受け取れるようになります。

cordova.plugins.diagnostic.registerBluetoothStateChangeHandler(function(state){
   if(state === cordova.plugins.diagnostic.bluetoothState.POWERED_ON){
     console.log("Bluetoothに接続できます");
   }
});

WiFi

WiFiの診断方法もBluetoothとほとんど同じです。Androidであれば設定を変更できます。iOSでは状態を取得することのみ可能で、状態変更時の通知機能も利用できません。

cordova.plugins.diagnostic.isWifiAvailable
cordova.plugins.diagnostic.isWifiEnabled
cordova.plugins.diagnostic.setWifiState // Androidのみ
cordova.plugins.diagnostic.switchToWifiSettings // Androidのみ

カメラ

カメラの場合は、端末に搭載されているかどうかをチェックする機能があります。（一部のAndroidデバイスにはカメラがついていないケースがあるため）

cordova.plugins.diagnostic.isCameraPresent(function(present){
  // trueならある。falseならなし
  console.log("Camera is " + (present ? "present" : "absent"));
}, function(error){
  console.error("The following error occurred: "+error);
});

その他のメソッドの種類はBluetoothと変わりません。iOSの場合はカメラロールにアクセスするための権限を別途指定できます。

cordova.plugins.diagnostic.isCameraAvailable
cordova.plugins.diagnostic.isCameraAuthorized
cordova.plugins.diagnostic.getCameraAuthorizationStatus
cordova.plugins.diagnostic.requestCameraAuthorization
cordova.plugins.diagnostic.isCameraRollAuthorized // iOSのみ

通知

通知に関するメソッドはほぼiOS向けのものになります。

cordova.plugins.diagnostic.remoteNotificationType // iOSのみ
cordova.plugins.diagnostic.isRemoteNotificationsEnabled
cordova.plugins.diagnostic.isRegisteredForRemoteNotifications // iOSのみ
cordova.plugins.diagnostic.getRemoteNotificationTypes // iOSのみ
cordova.plugins.diagnostic.getRemoteNotificationsAuthorizationStatus // iOSのみ
cordova.plugins.diagnostic.requestRemoteNotificationsAuthorization // iOSのみ

マイク/アドレス帳/カレンダー

マイク/アドレス帳/カレンダーはiOS/Androidで共通です。アクセス許可されているかどうかの診断、ステータスの取得、そしてアクセス許可を求めるという用途の3つのメソッドが用意されています。

マイク

cordova.plugins.diagnostic.isMicrophoneAuthorized
cordova.plugins.diagnostic.getMicrophoneAuthorizationStatus
cordova.plugins.diagnostic.requestMicrophoneAuthorization

アドレス帳

cordova.plugins.diagnostic.isContactsAuthorized
cordova.plugins.diagnostic.getContactsAuthorizationStatus
cordova.plugins.diagnostic.requestContactsAuthorization

カレンダー

cordova.plugins.diagnostic.isCalendarAuthorized
cordova.plugins.diagnostic.getCalendarAuthorizationStatus
cordova.plugins.diagnostic.requestCalendarAuthorization

リマインダー

リマインダーはiOS向けのみ提供されています。

cordova.plugins.diagnostic.isRemindersAuthorized
cordova.plugins.diagnostic.getRemindersAuthorizationStatus
cordova.plugins.diagnostic.requestRemindersAuthorization

モーション

徒歩などのモーションデータを診断します。これもiOSのみです。他の機能に比べると若干使い方が複雑です。

cordova.plugins.diagnostic.motionStatus
cordova.plugins.diagnostic.isMotionAvailable
cordova.plugins.diagnostic.isMotionRequestOutcomeAvailable
cordova.plugins.diagnostic.requestMotionAuthorization
cordova.plugins.diagnostic.getMotionAuthorizationStatus

NFC

NFCはAndroidでのみ使える機能になります。NFCもBluetoothのようにステータスの変更を受け取れるようになっています。

cordova.plugins.diagnostic.NFCState
cordova.plugins.diagnostic.isNFCPresent
cordova.plugins.diagnostic.isNFCEnabled
cordova.plugins.diagnostic.isNFCAvailable
cordova.plugins.diagnostic.registerNFCStateChangeHandler
cordova.plugins.diagnostic.switchToNFCSettings

外部ストレージ

外部ストレージもAndroidでのみ使える機能になります。なお、筆者の端末Galaxy S6ではステータスは取得できましたが、ストレージの詳細は取得できませんでした。

cordova.plugins.diagnostic.isExternalStorageAuthorized
cordova.plugins.diagnostic.getExternalStorageAuthorizationStatus
cordova.plugins.diagnostic.requestExternalStorageAuthorization
cordova.plugins.diagnostic.getExternalSdCardDetails

Cordova diagnostic pluginは、対象デバイスでどの機能が使えるのかを診断するときに便利です。診断をするだけで実際にデータを取得できる訳ではありませんが、デバイスの状態に応じた細やかな制御を行う場合に役立つでしょう。インタフェースがほぼ共通というのも使い勝手が良いです。

今回のサンプルコードは GitHub で公開しています。また、お使いのMonacaアカウントに直接インポートするURLはこちらです。実装時の参考にしてください。

今回ご紹介したCordovaプラグインは、サードパーティ製であるためアプリストア版のMonacaデバッガーでは動作しません。動作検証の際にはProプラン以上で利用可能なカスタムビルドデバッガーをご利用ください。