Cordovaアプリケーション

4 Cordovaアプリケーション

Apache Cordovaフレームワークに基づいてハイブリッド・アプリケーションを開発する場合、Oracle Autonomous Mobile Cloud Enterprise (AMCe)がCordovaを提供するクライアントSDKを使用できます。このSDKはAMCeによる認証を簡素化し、AMCeプラットフォームAPI用のCordovaラッパー・クラスと、Data Offline、SyncおよびSync Express用のライブラリを提供します。

Cordovaを初めて使用していて、それもあなたのシステムにインストールする必要がある場合は、「JETハイブリッド・アプリケーションの使い方」チュートリアルに従って、Cordovaアプリケーションを作成し、それをモバイル・バックエンドに接続することについてのエンド・ツー・エンドの情報を参照できます。

注意:

このSDKは、iOSおよびAndroidプラットフォーム用のCordovaアプリをサポートしています。 Microsoft Windowsのアプリはサポートされていません。

SDKの入手

Cordova用のAMCeクライアントSDKを入手するには、OTNの「Oracle Autonomous Mobile Cloud Enterpriseダウンロード・ページ」を参照してください。

バックエンドの作成

バックエンドを作成して、プラットフォームとカスタムAPIなどのアプリケーションとAMCe機能との間の安全なゲートウェイとして機能させます。アプリがこれらのリソースにアクセスするには、バックエンドで認証されます。

をクリックしてサイド・メニューを開き、「開発>バックエンド」を選択します。
「新規バックエンド」をクリックします。
ダイアログが完了し、バックエンドが作成されたら、設定ページを開いたままにします。

この情報の一部を使用してアプリを構成する必要があります。

SDKの追加

介在するフレームワークなしで基本的なアプリケーション設定を前提とすると、CordovaクライアントSDKをアプリケーションに追加するために以下のようになります:

まだ行っていない場合は、Cordova SDK zipをunzipします。
mcs.js (および/またはmcs.min.js)とoracle_mobile_cloud_config.jsを、JavaScriptライブラリを保持するディレクトリにコピーします。
oracle_mobile_cloud_config.jsでバックエンドの詳細を記入してください。
SDKのスクリプト・タグと構成ファイルをアプリケーションのindex.htmlファイルに追加します:
```
<script src="lib/mcs/mcs.js"</script>
<script src="app/oracle_mobile_cloud_config.js"</script>
```
あなたのアプリで通知を使用する場合は、oracle-mcs-notifications-cordova-pluginプラグインをインストールしてください:
```
cordova plugin add PATH_TO_UNZIPPED_SDK/oracle-mcs-notifications-cordova-plugin
```
(オプション)RequireJS環境では、RequireJSを使用してアプリケーション内にmcs.jsをロードします。

注意:
あなたのアプリがSync Expressを使用している場合は、他のスクリプトの前に、アプリケーションのメイン・ページの最初のスクリプトとしてmcs.sync.min.jsを取得して実行する必要があります。 Sync Expressをアプリケーションに追加する方法の詳細は、「Sync Expressを使用してオフラインで作業するアプリケーションの作成」を参照してください。

プッシュ通知のサポートの追加

アプリでプッシュ通知を使用する場合は、これらの追加ステップが必要です。

(Androidの場合)Firebase Cloud Messaging (FCM)コンソールに通知用のアプリを登録します。 Googleの開発者サイトの「AndroidにFirebase Cloud Messaging Clientアプリケーションを設定」を参照してください。

あなたのアプリケーションの構成ファイルを生成するときは、クラウド・メッセージング・サービスを有効にすることを選択してください。

生成が完了すると、「プロジェクト番号」 (別名「発信者ID」)と「APIキー」が表示されます。これらの資格証明はモバイル・アプリに固有のもので、他のアプリに通知を送信するために使用することはできません。 FCMから登録トークンを取得し、AMCeで接続を設定するには、これらの値も必要です。
(Androidの場合)生成されたFirebase構成ファイルをダウンロードし、プロジェクトのルートに配置します。
(Androidの場合)SDKで提供されている通知プラグインをまだインストールしていない場合は、インストールします。
```
cordova plugin add PATH_TO_UNZIPPED_SDK/oracle-mcs-notifications-cordova-plugin
```
(iOSの場合)APNSで通知用にアプリを設定します。 iOS: Apple Secure Certificatesを参照してください
AndroidおよびiOS用のAMCeと通知プロファイルでアプリを作成します。「通知プロファイルの作成」を参照してください。

あなたのアプリケーション・コードでは、通知の登録:

...
document.addEventListener("deviceready", handleDeviceReady, false);
...
function handleDeviceReady(){
  MCSNotificationsCordovaPlugin.onTokenRefresh(handleTokenRefresh, handleError);
}
...
function handleTokenRefresh(token){
    console.log('NotificationsService Token refreshed', token);
    mcs.mobileBackend.notifications.registerForNotifications(token, packageName, appVersion, 'FCM')
        .then(handleRegisterForNotifications)
        .catch(handleError);
}
 
function handleRegisterForNotifications(response){
    console.log('NotificationsService, device registered for notifications');
}
function handleError(error){
    console.error('NotificationsService Error', error);
}

あなたのアプリケーション・コードで、通知イベントをサブスクライブしてください:

...
function handleDeviceReady(){
    MCSNotificationsCordovaPlugin.onMessageReceived(handleMessageReceived, handleError);
}
...
function handleMessageReceived(data){
    console.log('NotificationsService Message received', data);
}
 
function handleError(error){
    console.error('NotificationsService Error', error);
}

SDKプロパティの構成

CordovaアプリでクライアントSDKを使用するには、oracle_mobile_cloud_config.js構成ファイルをアプリに追加し、AMCeでバックエンドの環境の詳細を入力します。次に、SDKクラスはこの情報を使用して、AMCeに対して行われたREST呼び出し用のHTTPヘッダーを作成します。

注意:

いずれかのアプリケーションがブラウザ・ベースの場合は、AMCe APIへのアクセスのためにクロス・オリジン・リソース共有(CORS)を管理する必要があります。「クロスサイト・リクエスト偽造攻撃に対するブラウザベースのアプリケーションのセキュリティ保護」を参照してください。

構成ファイルをmcs.min.jsファイルと同じフォルダにパッケージします。

このファイルは、基本的に次の部分に分かれています:

logLevelやoAuthTokenEndpointなど、構成全体に適用されるプロパティ。これらのキーは、通常、ファイルの先頭に表示されますが、必ずしもその必要はありません。
mobileBackendプロパティとその内容。

この部分は、アプリケーションでバックエンドを使用している場合に含める必要があります。 SDKクラスでは、そこで指定した環境と認証の詳細を使用して、バックエンドにアクセスし、APIに対するREST呼び出しのHTTPヘッダーを構成します。

次の例は、一般的なoracle_mobile_cloud_config.jsファイルの構造を示しています:

var mcs_config = {
  "logLevel": mcs.LOG_LEVEL.NONE,
  "logHTTP": true,
  "oAuthTokenEndPoint": "OAUTH_BASE_URL",
  "mobileBackend": {
    "name": "NAME",
    "baseUrl": "BASE_URL",
    "authentication": {
      "type": mcs.AUTHENTICATION_TYPES.oauth,
      "oauth": {
        "clientId": "CLIENT_ID",
        "clientSecret": "CLIENT_SECRET"
      }
    }
  },
  "syncExpress": {
    "handler": "OracleRestHandler",
    "policies": [
      {
        "path": '/mobile/custom/firstApi/tasks/:id(\\d+)?',
      },
      {
        "path": '/mobile/custom/secondApi/tasks/:id(\\d+)?',
      }
    ]
  }
};

ファイルの要素に関するいくつかの注意があります。

oAuthTokenEndPoint - アプリケーションが認証トークンを取得するOAuthサーバーのURL。このキーは、OAuthを使用して認証するすべてのアプリケーションに提供する必要があります。これはバックエンドの「設定」ページから取得します。エンドポイントはベースURL (https://host.domain:portの形式)のみにする必要があります。
logLevel - アプリケーション・コンソールに表示されるSDKロギングの量を決定します。デフォルト値はmcs.LOG_LEVEL.INFOです(重要なイベントのみが記録されます)。可能な他の値は、mcs.LOG_LEVEL.NONE、mcs.LOG_LEVEL.ERROR (エラーのみが記録されます)またはmcs.LOG_LEVEL.VERBOSEです。
enableLogger - trueに設定すると、アプリにロギングが組み込まれます。
logHTTP - trueに設定すると、SDKはリクエストとレスポンスにHTTPヘッダーとHTTPSヘッダーを記録します。
mobileBackend - バックエンドの認証の詳細とその他のオプションの詳細(同期プロパティなど)を含む要素。

バックエンドの「設定」ページから資格証明(OAuthやHTTP資格証明など)を取得します。
mobileBackend/baseUrl - バックエンド経由で呼び出すすべてのAPIのベースURL。これはバックエンドの「設定」ページから取得します。
mobileBackend/authentication - 次のサブ要素が含まれています:
- mcs.AUTHENTICATION_TYPES.oauth、basic、facebook、またはtokenの可能な値を持つtypeサブエレメント。
- 認証資格証明を含む1つ以上のサブ要素。
- (オプション)offlineEnabledキーを追加し、その値をtrueに設定することができます。
各認証タイプの詳細と例については、「認証のプロパティ」を参照してください。

同期要素の詳細については、「Sync Expressを使用してオフラインで作業するアプリケーションの作成」を参照してください。

認証のプロパティ

authenticationの内容とサブ要素は、アプリケーションがどのような種類の認証を使用するかによって異なります。

OAuth

typeプロパティの値をmcs.AUTHENTICATION_TYPES.oauthに設定します。
typeプロパティと同じレベルで、oauthというプロパティを作成し、バックエンドによって提供されるclientIDおよびclientSecret資格証明を入力します。
ファイルの最上位レベルで、「設定」の値を提供しますが、バックエンドの「設定」ページに追加されるoauth2/v1/tokenなしにoAuthTokenEndPointを提供します。

結果のauthentication要素は次のようになります:

var mcs_config = {
...
  "oAuthTokenEndPoint": "BASE_OAUTH_URL_WITH_oauth2/v1/token_REMOVED",
  "mobileBackend": {
    "name": "NAME",
    "baseUrl": "BASE_URL",
    "authentication": {
      "type": mcs.AUTHENTICATION_TYPES.oauth,
      "oauth": {
        "clientId": "CLIENT_ID",
        "clientSecret": "CLIENT_SECRET"
      }
    }
  }
};

HTTP Basic

typeプロパティの値をmcs.AUTHENTICATION_TYPES.basicに設定します。
typeプロパティと同じレベルで、basicというプロパティを作成し、バックエンドによって提供されるmobileBackendIDとanonymousKeyを入力します。

結果のエントリは次のようになります:

var mcs_config = {
   ...
  "mobileBackend": {
    "name": "NAME",
    "baseUrl": "BASE_URL",
    "authentication": {
      "type": mcs.AUTHENTICATION_TYPES.basic,
      "basic": {
        "mobileBackendId": "MOBILE_BACKEND_ID",
        "anonymousKey": "ANONYMOUS_KEY"
      }
    }
  }
};

トークン交換

サードパーティ・トークンを使用して認証する場合は、次の操作を行います:

typeプロパティの値をmcs.AUTHENTICATION_TYPES.tokenに設定します。
バックエンドによって提供されるmobileBackendIdとanonymousKeyを入力します。

結果のプロパティは次のようになります:

var mcs_config = {
...
  "mobileBackend": {
    "name": "NAME",
    "baseUrl": "BASE_URL",
    "authentication": {
      "type": mcs.AUTHENTICATION_TYPES.token,
      "token":{
        "mobileBackendId": "YOUR_BACKEND_ID",
        "anonymousKey": "ANONYMOUS_KEY"
      }
    }
  }
};

Facebookログイン

typeプロパティの値をmcs.AUTHENTICATION_TYPES.facebookに設定します。
バックエンドが提供するHTTP基本認証資格証明および/またはOAuth資格証明を入力します。
FacebookアプリのappIDを入力します。
関連するscopesを記入してください。

結果のauthenticationエントリは、次のようになります:

var mcs_config = {
  ....
  "mobileBackend": {
    "name": "NAME",
    "baseUrl": "BASE_URL",
    "authentication": {
      "type": mcs.AUTHENTICATION_TYPES.facebook,
      "facebook":{
        "appId": "YOUR_FACEBOOK_APP_ID",
        "mobileBackendId": "YOUR_BACKEND_ID",
        "anonymousKey": "YOUR_ANONYMOUS_KEY",
        "scopes": "public_profile,user_friends,email,user_location,user_birthday"
      }
    }
  }
};

モバイルAPIの呼び出し

AMCeでは、バックエンドとは、アプリケーションで使用できるカスタムAPI、ストレージ・コレクション、その他のリソースを論理的にグループ化したものです。バックエンドは、これらのリソースにアクセスするためのセキュリティ・コンテキストも提供します。

Cordovaアプリケーションでバックエンドを使用する一般的なステップは次のとおりです:

アプリにクライアントSDKを追加します。
バックエンドの環境と認証の詳細をoracle_mobile_cloud_config.jsに入力します。
SDKコールをアプリケーションに追加して、構成情報をロードします。
SDKコールをアプリに追加して、認証を処理します。
使用する他のSDK呼び出しを追加します。

バックエンド構成のロード

CordovaクライアントSDKを使用してAMCe APIを呼び出す前に、使用するバックエンドの構成をロードする必要があります。次のスニペットでは、mcs_configは、アプリケーションに追加したoracle_mobile_cloud_config.jsファイルで定義されている構成の名前です。

mcs.init(mcs_config);

認証とログイン

次に、CordovaクライアントSDKのAuthorizationクラスの使用例をいくつか示します。これらの例では、「SDKプロパティの構成」で説明されているように、使用している認証タイプのSDK構成ファイルがすでに構成されていることを前提としています。

OAuthとHTTP Basic

バックエンドの認証タイプをoauth (またはbasic)に設定します:

mcs.mobileBackend.setAuthenticationType(mcs.AUTHENTICATION_TYPES.oauth);

次に、バックエンドでAuthorization.authenticateを呼び出し、それにユーザー名を渡し、成功と失敗のコールバックを指定する関数を追加します:

mcs.mobileBackend.authorization.authenticate(username, password).then(callback).catch(errorCallback);

匿名認証を使用する場合、呼び出すメソッドはauthenticateAnonymousです。

mcs.mobileBackend.authorization.authenticateAnonymous().then(callback).catch(errorCallback);

サードパーティのトークンを使用するSSO

サードパーティ・トークンでSSOを使用するには、まずサードパーティ・トークン発行者からトークンを取得する必要があります。トークンを取得する方法は、発行者によって異なります。サードパーティのトークンを取得し、アイデンティティ・プロバイダをAMCeで構成する方法の詳細については、「サードパーティのSAMLトークンとJWTトークン」を参照してください。

バックエンドの認証タイプをtokenに設定し、許可呼び出しでトークンを渡します:

mcs.mobileBackend.setAuthenticationType(mcs.AUTHENTICATION_TYPES.token);
mcs.mobileBackend.authorization.authenticate(token).then(callback).catch(errorCallback);

Facebook

バックエンドの認証タイプをfacebookに設定し、次にauthenticate()を呼び出します:

mcs.mobileBackend.setAuthenticationType(mcs.AUTHENTICATION_TYPES.facebook);
mcs.mobileBackend.authorization.authenticate().then(callback).catch(errorCallback);

クロスサイト・リクエスト偽造攻撃に対するブラウザベースのアプリケーションのセキュリティ保護

いずれかのアプリケーションがブラウザベースの場合は、クロスサイト・リクエスト偽造(CSRF)攻撃から保護するために、AMCe APIにアクセスするためのCORS (cross-origin resource sharing)を管理する必要があります。これを行うには、Security_AllowOrigin環境をdisallow (デフォルト値)に設定するか、クロスサイト・リクエストを行うことができる信頼できるURLのカンマ区切りのホワイトリストに設定します。ワイルドカード文字(*)の使用方法の詳細および詳細については、「AMCe APIへのクロスサイト・リクエストの保護」を参照してください。

注意:

便宜上、ブラウザ・ベースのアプリケーションの開発中またはブラウザで実行されているハイブリッド・アプリケーションのテスト中に、Security_AllowOriginをhttp://localhost:[port]に設定できますが、プロダクションの値を必ず更新してください。

プラットフォームAPIの呼び出し

CordovaクライアントSDKライブラリをアプリケーションに組み込み、構成を調整すると、アプリケーションでSDKクラスを使用する準備が整います。

これらのクラスを使用して、モバイル・バックエンドのStorageコレクションからオブジェクトを取得する方法の例を次に示します:

mcs.mobileBackend.storage.getCollection(<collection id>)
.then(function(collection){
  return collection.getObject(<object id>, ‘blob’);
})
.then(function(object){
  console.log(object);
})
.catch(function(response){
  console.error(response);
})

カスタムAPIの呼び出し

CordovaクライアントSDKは、カスタムAPIの呼び出しを簡単にするCustomCodeクラスを提供します。リクエスト・ペイロードがJSONまたは空で、レスポンス・ペイロードがJSONまたは空のエンドポイントでRESTメソッド(GET、PUT、POST、またはDELETE)を呼び出すことができます。

カスタムAPIエンドポイントを呼び出すには、次のようなものを使用できます:

mcs.mobileBackend.CustomCode.invokeCustomCodeJSONRequest("TaskApi1/tasks/100" , "GET" , null).then(function(response){
    //The response parameter returns the status code and HTTP payload from the HTTP REST Call.
    console.log(response);
    // Example: { statusCode: 200, data: {} }
    //Depends on the response format defined in the API.
  }).catch(function(response){
  //The response parameter returns the status code and HTTP payload, if available, or an error message, from the HTTP REST Call.
  console.log(response);
  /*
    Example:
      { statusCode: 404,
        data: {
      "type":"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",
        "status":404,"title":"API not found",
        "detail":"We cannot find the API cordovaJSApi2 in Mobile Backend CordovaJSBackend(1.0). Check that this Mobile Backend is associated with the API.",
        "o:ecid":"005Bojjhp2j2FSHLIug8yf00052t000Jao, 0:2", "o:errorCode":"MOBILE-57926", "o:errorPath":"/mobile/custom/cordovaJSApi2/tasks" } }
   */
  //Depends on the response format defined in the API.
  });

TypeScriptの使用

TypeScriptオブジェクトをCordovaおよびJavaScriptクライアントSDKとともに使用することもできます。

ここでは、SDKでTypeScriptを使用するための基本的なステップと例を示します。この例では、あなたのアプリがIonicフレームワークを使用していると仮定しています(ただし、TypeScriptを使用せずに使用することもできます)。

SDKの設定

プロジェクト・フォルダに次のコマンドを実行して、プロジェクトにSDKをインストールします:
```
npm install {path to unzipped SDK location}
```
SDKタイプをインポートするためのインポート・ステートメントをサービスに追加する:
```
import {IMCS} from 'mcs'
```

アプリの構成ファイルを作成します:

import {IMCS,
  IOracleMobileCloudConfig,
  IMobileBackendConfig,
  IAuthenticationConfig,
  IBasicAuthConfig,
  IOAuthConfig,
  import * as mcssdk from 'mcs'
const mcs: IMCS = mcssdk;

export const mcsConfig: IOracleMobileCloudConfig = {
  logLevel: mcs.LOG_LEVEL.NONE,
  logHTTP: true,
  oAuthTokenEndPoint: 'OAUTH_URL',
  mobileBackend: <IMobileBackendConfig>{
    name: 'NAME',
    baseUrl: 'BASE_URL',
    authentication: <IAuthenticationConfig>{
      type: mcs.AUTHENTICATION_TYPES.basic,
      basic: <IBasicAuthConfig>{
        mobileBackendId: 'MOBILE_BACKEND_ID',
        anonymousKey: 'ANONYMOUS_KEY'
      }
    }
  }
};

構成をアプリケーションにインポートします。上記のファイルがmcs-config.tsの場合、インポートは次のようになります :
```
import { mcsConfig } from "../mcs-config";
```

モバイルAPIの呼び出し

これらのインポート文をサービスまたはコンポーネントに追加します:

import {IMCS} from 'mcs';
import * as mcssdk from 'mcs';  And in your class add declaration statement:

あなたのクラスに宣言文を追加してください:
```
export class ComponentClass{
   mcs: IMCS = mcssdk; 
}
```
構成を使用してSDKライブラリを初期化します:
```
this.mcs.init(mcsConfig);
```

コールバック・エンド機能:

this.mcs.mobileBackend.setAuthenticationType(this.mcs.AUTHENTICATION_TYPES.basic);
this.mcs.mobileBackend.authorization.authenticate(username, password);

ロケーション・サービスのサポートの追加(オンのみ)

ionic cordova plugin add cordova-plugin-geolocation

プッシュ通知のサポートの追加(Ionicのみ)

(Androidの場合)Firebase Cloud Messaging (FCM)コンソールに通知用のアプリを登録します。 Googleの開発者サイトの「AndroidにFirebase Cloud Messaging Clientアプリケーションを設定」を参照してください。

あなたのアプリケーションの構成ファイルを生成するときは、クラウド・メッセージング・サービスを有効にすることを選択してください。

生成が完了すると、「プロジェクト番号」 (別名「発信者ID」)と「APIキー」が表示されます。これらの資格証明はモバイル・アプリに固有のもので、他のアプリに通知を送信するために使用することはできません。 FCMから登録トークンを取得し、AMCeで接続を設定するには、これらの値も必要です。
(Androidの場合)生成されたFirebase構成ファイルをダウンロードし、プロジェクトのルートに配置します。
(Androidの場合)SDKで提供されている通知プラグインをまだインストールしていない場合は、インストールします。
```
cordova plugin add PATH_TO_UNZIPPED_SDK/oracle-mcs-notifications-cordova-plugin
```
(iOSの場合)APNSで通知用にアプリを設定します。 iOS: Apple Secure Certificatesを参照してください
AndroidおよびiOS用のAMCeと通知プロファイルでアプリを作成します。「通知プロファイルの作成」を参照してください。

あなたのアプリケーション・コードでは、通知の登録:

...
MCSNotificationsCordovaPlugin.onTokenRefresh(this.handleTokenRefresh.bind(this), this.handleError.bind(this));
...
handleTokenRefresh(token: string){
    console.log('NotificationsService Token refreshed', token);
    this.mcs.mobileBackend.notifications.registerForNotifications(token, packageName, appVersion, 'FCM')
        .then(this.handleRegisterForNotifications.bind(this))
        .catch(this.handleError.bind(this));
}

handleRegisterForNotifications(response: INetworkResponse){
    console.log('NotificationsService, device registered for notifications');
}
handleError(error: any){
    console.error('NotificationsService Error', error);
}

あなたのアプリケーション・コードで、通知イベントをサブスクライブしてください:

...   
MCSNotificationsCordovaPlugin.onMessageReceived(this.handleMessageReceived.bind(this), this.handleError.bind(this));
...
handleMessageReceived(data: any){
    console.log('NotificationsService Message received', data);
}
handleError(error: any){
    console.error('NotificationsService Error', error);
}

ライブラリ

CordovaクライアントSDKには、次のアイテムが含まれています。

jsdocs.zip - ライブラリのコンパイルされたドキュメント。
loki-cordova-fs-adapter - CordovaのSync Express機能で使用可能なストレージの量を拡張するために使用されるプラグイン。
mcs.js - SDKの非圧縮バージョンです。このバージョンにはコード・コメントが含まれており、アプリの開発とデバッグに最適です。
mcs.sync.js - 非圧縮バージョンのSDK Data OfflineとSync and Sync Expressライブラリ。
mcs.min.js - SDKの圧縮されたバージョン。完了したアプリをデプロイするときは、このバージョンを使用します。
mcs.sync.min.js - SDK Data OfflineとSync and Sync Expressライブラリの圧縮バージョン。
oracle-mcs-notifications-cordova-plugin - iOSとAndroidの通知を有効にするCordovaプラグイン。
oracle_mobile_cloud_config.js - AMCe構成ファイル。アプリでアクセスするモバイル・バックエンドの環境と認証の詳細を挿入できます。
types - SDKモジュールとプラグインのTypeScript定義が含まれています。

次のステップ

Cordova SDKを設定したら、それを使用してアプリにAMCe機能を追加することができます。