Cordova アプリケーションへの MobileFirst Foundation SDK の追加

概説

このチュートリアルでは、Apache Cordova、Ionic、またはその他のサード・パーティー・ツールを使用して作成された新規または既存の Cordova アプリケーションに MobileFirst SDK を追加する方法について学習します。 また、アプリケーションを認識するように MobileFirst Server を構成する方法と、プロジェクト内で変更する MobileFirst 構成ファイルに関する情報を見つける方法についても学習します。

MobileFirst Cordova SDK は、Cordova プラグインのセットとして提供されており、NPM に登録されています。
入手可能なプラグインは次のとおりです。

• cordova-plugin-mfp - コアの SDKプラグイン
• cordova-plugin-mfp-push - プッシュ通知サポートを提供します
• cordova-plugin-mfp-jsonstore - JSONStore サポートを提供します
• cordova-plugin-mfp-fips - Android のみ。 FIPS サポートを提供します
• cordova-plugin-mfp-encrypt-utils - iOS のみ。 暗号化および暗号化解除がサポートされるようにします

サポート・レベル

MobileFirst プラグインでサポートされる Cordova プラットフォームのバージョンは次のとおりです。

• cordova-ios: >= 4.1.1 と < 7.0
• cordova-android: >= 6.1.2 と < 11.0
• cordova-windows: >= 5.0.0 と < 8.0

注: cordova-windows の最新の公開バージョンにはバグがあり、アプリの起動時に例外がスローされます。 Apache Cordova は開発リポジトリーの問題を修正しましたが、まだ公開されていません。 フィックスが含まれるマスター・リポジトリーからの cordova-windows バージョンを使用することをお勧めします。 以下は、cordova-windows プラットフォームを追加してフィックスを設定するために使用できるコマンドです。

cordova platform add https://github.com/apache/cordova-windows

ジャンプ先:

• Cordova SDK コンポーネント
• MobileFirst Cordova SDK の追加
• MobileFirst Cordova SDK の更新
• 生成される MobileFirst Cordova SDK 成果物
• Cordova Browser プラットフォームのサポート
• 次に使用するチュートリアル

注: Xcode 8 を使用する場合、iOS シミュレーターでの iOS アプリケーションの実行中は、キーチェーン共有機能が必須です。Xcode プロジェクトをビルドする前に、この機能を手動で有効にする必要があります。

Cordova SDK コンポーネント

cordova-plugin-mfp

cordova-plugin-mfp プラグインは、Cordova 用のコア MobileFirst プラグインであり、必須です。 他の MobileFirst プラグインのいずれかをインストールすると、cordova-plugin-mfp プラグインも自動的にインストールされます (まだインストールされていない場合)。

次の Cordova プラグインは、cordova-plugin-mfp の依存関係としてインストールされます。

• cordova-plugin-device
• cordova-plugin-dialogs
• cordova-plugin-globalization
• cordova-plugin-okhttp

cordova-plugin-mfp-jsonstore

cordova-plugin-mfp-jsonstore プラグインを使用すると、アプリケーションで JSONstore を使用できるようになります。 JSONstore について詳しくは、JSONStore に関するチュートリアルを参照してください。

cordova-plugin-mfp-push

cordova-plugin-mfp-push プラグインは、Android アプリケーション用の MobileFirst Server からプッシュ通知を使用するために必要な許可を提供します。 プッシュ通知を使用するための追加セットアップが必要です。 プッシュ通知について詳しくは、プッシュ通知に関するチュートリアルを参照してください。

cordova-plugin-mfp-fips

cordova-plugin-mfp-fips プラグインは、Android プラットフォームの FIPS 140-2 をサポートします。 詳しくは、FIPS 140-2 サポートを参照してください。

cordova-plugin-mfp-encrypt-utils

cordova-plugin-mfp-encrypt-utils プラグインは、iOS プラットフォームを使用する Cordova アプリケーションの暗号化のための iOS OpenSSL フレームワークを提供します。 詳しくは、Cordova iOS での OpenSSL の有効化を参照してください。

前提条件:

• Apache Cordova CLI(>=6.x および <11.0) と MobileFirst CLI が開発者のワークステーションにインストールされている。
• MobileFirst Server のローカル・インスタンスまたはリモート・インスタンスが稼働している。
• MobileFirst 開発環境のセットアップ、および Cordova 開発環境のセットアップの両チュートリアルを読む。
• cordova-windows の場合、マシンにインストールされている Visual Studio と .NET のバージョンと互換性のある Visual C++ のバージョンがインストールされている必要があります。
• Universal Windows アプリケーションの Windows Phone SDK 8.0 および Visual Studio Tools の場合、作成された cordova-windows アプリケーションが必要なすべてのサポート・ライブラリーを持つようにしてください。

Mobile Foundation Cordova SDK の追加

以下の手順に従って、新規または既存の Cordova プロジェクトに Mobile Foundation Cordova SDKを追加し、そのプロジェクトを MobileFirst Server に登録します。

開始する前に、MobileFirst Server が稼働していることを確認します。
ローカルにインストールされているサーバーを使用する場合: コマンド・ライン・ウィンドウで、サーバーのフォルダーに移動し、コマンド ./run.sh を実行します。

注: SDK を既存の Cordova アプリケーションに追加すると、プラグインによって、Android 用の MainActivity.java ファイルと iOS 用の Main.m ファイルが上書きされます。

SDK の追加

MobileFirst Cordova アプリケーション・テンプレートを使用することによってプロジェクトを作成することを検討します。 テンプレートを使用すると、MobileFirst 固有の必須プラグイン・エントリーが Cordova プロジェクトの config.xml ファイルに追加され、MobileFirst 固有の、使用準備の整った index.js ファイル (MobileFirst アプリケーション開発用に調整されている) が提供されます。

新規アプリケーション

1. 次のコマンドで Cordova プロジェクトを作成します。cordova create projectName applicationId applicationName --template cordova-template-mfp
   例えば、次のとおりです。

   cordova create Hello com.example.helloworld HelloWorld --template cordova-template-mfp
   

   • 「Hello」は、アプリケーションのフォルダー名です。
   • 「com.example.helloworld」は、アプリケーションの ID です。
   • 「HelloWorld」は、アプリケーションの名前です。
   • –template を指定すると、MobileFirst 固有の追加によってアプリケーションが変更されます。

   テンプレートとして用意された index.js を使用することで、アプリケーションのマルチリンガル・トランスレーションや初期化オプションといった、MobileFirst の追加機能を使用できます (詳しくはユーザー向け資料を参照してください)。

2. cd hello コマンドで、ディレクトリーを Cordova プロジェクトのルートに変更します。

3. 次の Cordova CLI コマンドを使用して、サポートされているプラットフォームを 1 つ以上 Cordova プロジェクトに追加します。cordova platform add ios|android|windows 例えば、次のとおりです。

   cordova platform add ios
   

   注: このアプリケーションは MobileFirst テンプレートを使用して構成されたため、ステップ 3 でプラットフォームが追加されたときに MobileFirst のコア Cordova プラグインが自動的に追加されます。

4. 次のように cordova prepare コマンドを実行することで、アプリケーション・リソースを準備します。

   cordova prepare
   

アプリケーションの終了

1. 既存の Cordova プロジェクトのルートに移動し、次のように MobileFirst コア Cordova プラグインを追加します。

   cordova plugin add cordova-plugin-mfp
   

2. www\js フォルダーに移動し、index.js ファイルを選択します。

3. 次の関数を追加します。

   function wlCommonInit() {
   
   }
   

MobileFirst API メソッドは、MobileFirst クライアント SDK がロードされた後で使用可能になります。 これで wlCommonInit 関数が呼び出されます。
この関数を使用して、各種 MobileFirst API メソッドを呼び出します。

SDK の手動での追加

ローカル・パスからプラグインをインストールするオプションもあります。 cordova-plugin-mfp は MFP コンソールからダウンロードできます。それを Cordova アプリケーションにインストールします。

1. MFP サーバー・コンソール Dashboard で、「ダウンロード・センター」をクリックし =>「SDK」タブをクリックし => Cordova SDK をダウンロードします。

2. 既存の Cordova プロジェクトのルートに移動し、次のように MobileFirst コア Cordova プラグインを追加します。

   cordova plugin add [path-to downloaded mfp cordova plugin]/mfp-cordova/plugins/cordova-plugin-mfp
   

アプリケーションの登録

1. コマンド・ライン・ウィンドウを開き、Cordova プロジェクトのルートに移動します。

2. 次のコマンドで、MobileFirst Server にアプリケーションを登録します。

   mfpdev app register
   

   • リモート・サーバーを使用する場合は、mfpdev server add コマンドを使用して、そのサーバーを追加します。

mfpdev app register CLI コマンドは、まず最初に MobileFirst Server に接続してアプリケーションを登録した後、MobileFirst Server を識別するメタデータを使用して、Cordova プロジェクトのルートにある config.xml ファイルを更新します。

各プラットフォームはアプリケーションとして MobileFirst Server に登録されます。

ヒント: 次のように、MobileFirst Operations Console からアプリケーションを登録することもできます。

1. MobileFirst Operations Console をロードします。
2. 「アプリケーション」の横の「新規」ボタンをクリックして、新規アプリケーションを登録し、画面に表示される指示に従います。

SDK の使用

MobileFirst API メソッドは、MobileFirst クライアント SDK がロードされた後で使用可能になります。 これで wlCommonInit 関数が呼び出されます。
この関数を使用して、各種 MobileFirst API メソッドを呼び出します。

MobileFirst Cordova SDK の更新

MobileFirst Cordova SDK を最新リリースで更新するには、cordova plugin remove cordova-plugin-mfp コマンドを実行して cordova-plugin-mfp プラグインを削除した後、cordova plugin add cordova-plugin-mfp コマンドを実行してこのプラグインを再度追加します。

SDK のリリースは、SDK の NPM リポジトリーで調べることができます。

生成される MobileFirst Cordova SDK 成果物

config.xml

Cordova 構成ファイルは、アプリケーション・メタデータを含む必須の XML ファイルであり、アプリケーションのルート・ディレクトリーに保管されています。
MobileFirst Cordova SDK がプロジェクトに追加されると、Cordova が生成した config.xml ファイルは、名前空間 mfp: で識別された新規エレメントのセットを受け取ります。 追加されるエレメントには、MobileFirst の各種フィーチャーおよび MobileFirst Server に関連した情報が含まれています。

config.xml ファイルに追加される MobileFirst 設定の例

<?xml version='1.0'encoding='utf-8'?>
<widget id="..." xmlns:mfp="http://www.ibm.com/mobilefirst/cordova-plugin-mfp">
    <mfp:android>
        <mfp:sdkChecksum>3563350808</mfp:sdkChecksum>
        <mfp:appChecksum>0</mfp:appChecksum>
        <mfp:security>
            <mfp:testWebResourcesChecksum enabled="false" ignoreFileExtensions="png, jpg, jpeg, gif, mp4, mp3" />
        </mfp:security>
    </mfp:android>
    <mfp:windows>
        <mfp:sdkChecksum>3563350808</mfp:sdkChecksum>
       <mfp:windows10>
          <mfp:sdkChecksum>...</mfp:sdkChecksum>
          <mfp:security>
             <mfp:testWebResourcesChecksum/>
          </mfp:security>
    </mfp:windows>
    <mfp:platformVersion>8.0.0.00-20151214-1255</mfp:platformVersion>
    <mfp:clientCustomInit enabled="false" />
    <mfp:server runtime="mfp" url="http://10.0.0.1:9080" />
    <mfp:directUpdateAuthenticityPublicKey>the-key</mfp:directUpdateAuthenticityPublicKey>
    <mfp:languagePreferences>en</mfp:languagePreferences>
</widget>

config.xml ファイルの MobileFirst 設定の編集

MobileFirst CLI を使用して次のコマンドを実行することで、上記の設定を編集できます。

mfpdev app config

Cordova Browser プラットフォームのサポート

MobileFirst Platform では、Cordova Windows、Cordova Android、および Cordova iOS のサポートされるプラットフォームと共に、Cordova Browser プラットフォームがサポートされるようになりました。

MobileFirst Platform (MFP) と共に Cordova Browser プラットフォームを使用することは、他のプラットフォームのいずれかと共に MFP を使用することに似ています。 この機能を示すサンプルを以下に示します。

以下のコマンドを使用して、Cordova アプリケーションを作成します。

cordova create <your-appFolder-name> <package-name>

これによって、簡素な Cordova アプリが作成されます。

以下のコマンドを使用して、MFP プラグインを追加します。

cordova plugin add cordova-plugin-mfp

MFP サーバーを ping するために使用できるボタンを追加します (このサーバーは、ローカルにホストされているサーバーであっても、IBM Cloud にあるサーバーであってもかまいません)。 このボタンがクリックされたときに MFP サーバーを ping します。 以下のサンプル・コードを使用できます。

index.html

<!DOCTYPE html>
<html>

<head>
   <meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">
  <meta name="format-detection" content="telephone=no">
  <meta name="msapplication-tap-highlight" content="no">
  <meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width">


  <link rel="stylesheet" type="text/css" href="css/index.css" />

  <!-- load script with wlCommonInit defined before loading cordova.js -->
  <script type="text/javascript" src="js/index.js"></script>
  <script type="text/javascript" src="cordova.js"></script>

  <title>MFP Starter - Cordova</title>
</head>

<body>

  <div id="main">
    <div id="main_title">Hello MobileFirst</div>
    <div id="main_status"></div>
    <div id="main_info"></div>
  </div>

  <div id="button_content">
    <button id="ping_button" style="display:none">Ping MobileFirst Server</button>
  </div>

</body>

</html>

index.js

var Messages = {
  // Add here your messages for the default language.
  // Generate a similar file with a language suffix containing the translated messages.
  // key1 : message1,
};

var wlInitOptions = {
  // Options to initialize with the WL.Client object.
  // For initialization options please refer to IBM MobileFirst Platform Foundation Knowledge Center.
   mfpContextRoot : '/mfp', // "mfp" is the default context root in the MobileFirst Development server
    applicationId : 'io.cordova.hellocordova' // Replace with your own app id/package name.
};

function wlCommonInit() {
  app.init();
}

var app = {
  //initialize app
  "init": function init() {
    var buttonElement = document.getElementById("ping_button");
    buttonElement.style.display = "block";
    buttonElement.addEventListener('click', app.testServerConnection, false);
  },
  //test server connection
  "testServerConnection": function testServerConnection() {

    var titleText = document.getElementById("main_title");
    var statusText = document.getElementById("main_status");
    var infoText = document.getElementById("main_info");
    titleText.innerHTML = "Hello MobileFirst";
    statusText.innerHTML = "Connecting to Server...";
    infoText.innerHTML = "";

    WLAuthorizationManager.obtainAccessToken()
      .then(
        function (accessToken) {
          titleText.innerHTML = "Yay!";
          statusText.innerHTML = "Connected to MobileFirst Server";
        },
        function (error) {
          titleText.innerHTML = "Bummer...";
          statusText.innerHTML = "Failed to connect to MobileFirst Server";
        }
        );
    },
 }

注: index.js ファイルの wlInitOptions で mfpContextRoot および applicationId を記述することは重要です。

index.css

body {
    position: static;
    font-family: "HelveticaNeue-Light", "Helvetica Neue Light", "Helvetica Neue", Helvetica, Arial, "Lucida Grande", sans-serif;
    font-weight: 300;
    margin: 0px;
	padding: 0px;
}

#button_content {
  position: absolute;
  bottom: 10%;
  width: 100%;
}

#ping_button {
  display: block;
  margin: 0 auto;
  height: 50px;
  width: 240px;
  font-size: 20px;
  color: white;
  background-color: #325c80;
}

#main {
  top: 10%;
  position: absolute;
  text-align: center;
  width: 100%
}

#main_title {
  font-size: 40px;
}

#main_status {
  font-size: 20px;
  margin-top: 10px;
}

#main_info {
  font-size: 14px;
  margin-top: 10px;
}

以下のコマンドを使用して、Browser プラットフォームを追加します。

cordova platform add browser

アプリケーションを手動で登録するには、以下のようにします。

• MFP サーバーのコンソールにログインします。
• _「アプリケーション」_オプションの横の「新規」ボタンをクリックします。
• アプリケーションの名前を指定し、プラットフォームとして「Web」を選択し、アプリケーションの ID (index.js 内の wlInitOptions 関数で定義されたもの) を指定します。

注意: サーバー詳細をアプリケーションの config.xml に追加してください。

注: ブラウザー・プラットフォーム・アプリを登録するための mfpdev-cli はまもなくリリースされる予定です。

次に、以下のコマンドを実行します。

cordova prepare
cordova build
cordova run

これにより、プロキシー・サーバー (ポート 9081) で実行するブラウザーが起動され、MFP サーバーに接続されます。 Cordova ブラウザーのデフォルトのプロキシー・サーバー (ポート 8000 で実行) は、same-origin-policy が原因で MFP サーバーに接続できないため抑止されました。

実行されるデフォルト・ブラウザーは、Chrome に設定されます。 異なるブラウザー上で実行するには、以下のコマンドで --target オプションを使用できます。

 cordova run --target=Firefox

次のコマンドを使用して、アプリをプレビューできます。

mfpdev app preview

サポートされるブラウザー・オプションは「Simple Browser Rendering」 のみです。 「Mobile Browser Support」オプションは Browser プラットフォームではサポートされません。

Cordova ブラウザー・リソースにサービス提供するための WebSphere Liberty の使用

このチュートリアルの WebSphere Liberty 使用手順に従い、以下の変更を行います。

このチュートリアルの『Building the Maven webapp with the web application’s resources』セクションのステップ 1 に記述されているように、ブラウザー・プロジェクトの www フォルダーの内容を [MyWebApp] → src → Main → webapp に追加します。 最後に、Liberty サーバーでアプリケーションを登録し、パス localhost:9080/MyWebApp を指定してブラウザーで実行することによってアプリケーションをテストします。 また、sjcl フォルダーと jssha フォルダーを親フォルダーに追加し、ibmmfpf.js ファイル内でのそれらの参照を変更します。

次に使用するチュートリアル

これで MobileFirst Cordova SDK が組み込まれたので、以下の作業を行うことができます。

• Mobile Foundation SDK の使用に関するチュートリアルを検討する
• アダプター開発に関するチュートリアルを検討する
• 認証とセキュリティーに関するチュートリアルを検討する
• 通知に関するチュートリアルを検討する
• すべてのチュートリアルを検討する