将 MobileFirst Foundation SDK 添加到 Cordova 应用程序

概述

在此教程中，了解如何将 MobileFirst SDK 添加到新的或现有的使用 Apache Cordova、Ionic 或其他第三方工具创建的 Cordova 应用程序。 您还可以了解如何配置 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 SDK 组件
• 添加 MobileFirst Cordova SDK
• 更新 MobileFirst Cordova SDK
• 已生成 MobileFirst Cordova SDK 工件
• Cordova 浏览器平台支持
• 接下来要学习的教程

注：如果使用 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++ 版本。
• 如果使用 Windows Phone SDK 8.0 和 Visual Studio Tools for Universal Windows Apps，请确保创建的 cordova-windows 应用程序具有所有必需的支持库。

添加 Mobile Foundation Cordova SDK

遵循下面的指示信息将 Mobile Foundation Cordova SDK 添加到新的或现有的 Cordova 项目，然后在 MobileFirst Server 中进行注册。

在您开始之前，确保 MobileFirst Server 正在运行。
如果使用本地安装的服务器：从命令行窗口，浏览至服务器的文件夹，然后运行命令：./run.sh。

注：如果要将 SDK 添加到现有的 Cordova 应用程序，那么插件将覆盖 MainActivity.java 文件（针对 Android）和 Main.m 文件（针对 iOS）。

添加 SDK

考虑使用 MobileFirst Cordova 应用程序模板创建项目。 此模板会将必需的特定于 MobileFirst 的插件条目添加到 Cordova 项目的 config.xml 文件，并提供特定于 MobileFirst 并针对 MobileFirst 应用程序开发进行了调整的现成可用的 index.js 文件。

新建应用程序

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”是应用程序的标识。
   • “HelloWorld”是应用程序的名称。
   • –template 将使用特定于 MobileFirst 的新增项来修改应用程序。

   模板化的 index.js 使您能够使用其他 MobileFirst 功能，如多语言应用程序翻译和初始化选项（请参阅用户文档以获取更多信息）。

2. 将目录更改为 Cordova 项目的根目录：cd hello

3. 使用 Cordova CLI 命令将一个或多个受支持的平台添加到 Cordova 项目：cordova platform add ios|android|windows。 例如：

   cordova platform add ios
   

   注：由于已使用 MobileFirst 模板配置应用程序，因此将自动添加 MobileFirst 核心 Cordova 插件，因为已在步骤 3 中添加平台。

4. 通过运行 cordova prepare 命令来准备应用程序资源：

   cordova prepare
   

现有应用程序

1. 浏览至现有 Cordova 项目的根目录并添加 MobileFirst 核心 Cordova 插件：

   cordova plugin add cordova-plugin-mfp
   

2. 浏览至 www\js 文件夹并选择 index.js 文件。

3. 添加以下函数：

   function wlCommonInit() {
   
   }
   

在装入 MobileFirst 客户机 SDK 之后，MobileFirst API 方法将可用。 然后将调用 wlCommonInit 函数。
使用此函数调用各种 MobileFirst API 方法。

注册应用程序

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 客户机 SDK 之后，MobileFirst API 方法将可用。 然后将调用 wlCommonInit 函数。
使用此函数调用各种 MobileFirst API 方法。

更新 MobileFirst Cordova SDK

要使用最新发行版更新 MobileFirst Cordova SDK，请除去 cordova-plugin-mfp 插件：运行 cordova plugin remove cordova-plugin-mfp 命令，然后运行 cordova plugin add cordova-plugin-mfp 命令以重新添加。

可以在 SDK 的 NPM 存储库中找到 SDK 发行版。

已生成 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 浏览器平台支持

MobileFirst 平台现在支持 Cordova 浏览器平台以及受支持的 Cordova Windows、Cordova Android 和 Cordova iOS 平台。

将 Cordova 浏览器平台用于 MobileFirst Platform (MFP) 类似于将 MFP 用于任何其他平台。 下面解释了用于演示此功能的样本。

使用以下命令来创建 cordova 应用程序：

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

这将创建一个 vanilla cordova 应用程序。

使用以下命令来添加 MFP 插件：

cordova plugin add cordova-plugin-mfp

添加一个可用于 ping MFP 服务器（此服务器可能是本地托管的服务器或 IBM Cloud 上的服务器）的按钮。 单击此按钮以 Ping 您的 MFP 服务器。 您可以使用以下样本代码：

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;
}

使用以下命令来添加浏览器平台：

cordova platform add browser

要手动注册您的应用程序：

• 登录到您的 MFP 服务器控制台。
• 单击_应用程序_选项旁边的新建按钮。
• 为应用程序提供名称，选择 Web 作为平台，然后提供应用程序的标识（在 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

唯一受支持的浏览器选项是简单浏览器呈现。 该浏览器平台不支持移动浏览器支持选项。

使用 WebSphere Liberty 提供 cordova 浏览器资源

按照指示信息使用本教程中的 WebSphere Liberty，然后进行以下更改。

将浏览器项目的 www 文件夹内容添加到 [MyWebApp] → src → Main → webapp，如本教程中使用 Web 应用程序资源构建 Maven Web 应用程序部分的步骤 1 中所述。 最后，在 Liberty 服务器上注册您的应用程序，并在浏览器中使用路径 localhost:9080/MyWebApp 运行该应用程序以进行测试。 另外将 sjcl 和 jssha 文件夹添加到其父文件夹，并更改其在 ibmmfpf.js 文件中的引用。

接下来要学习的教程

集成 MobileFirst Cordova SDK 之后，您现在可以：

• 查看使用 Mobile Foundation SDK 教程
• 查看适配器开发教程
• 查看认证和安全教程
• 查看通知教程
• 查看所有教程