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

improve this page | report issue


概述

在此教程中，了解如何将 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 以及 < 6.0
  • cordova-android：>= 6.1.2 以及 < 9.0
  • cordova-windows：>= 4.3.2 以及 < 7.0

跳转至：

注：如果使用 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。

先决条件：

添加 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 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>
元素 描述 配置
widget config.xml 文档的根元素。 此元素包含两个必需属性：
  • id：这是在创建 Cordova 项目时指定的应用程序包名称。 如果在向 MobileFirst Server 注册应用程序之后手动更改了此值，那么必须重新注册应用程序。
  • xmlns:mfp：MobileFirst 插件 XML 名称空间。
mfp:platformVersion 必需。 开发应用程序所用的产品版本。 缺省情况下已设置。 不得更改此值。
mfp:directUpdateAuthenticityPublicKey 可选。 在启用“直接更新真实性”功能时，将在部署期间对直接更新包进行数字签名。 在客户机下载包之后，将运行安全性检查以验证包真实性。 此字符串值是公用密钥，将用于认证直接更新 .zip 文件。 使用 mfpdev app config direct_update_authenticity_public_key key-value 命令设置。
mfp:languagePreferences 可选。 包含用于显示系统消息的语言环境的逗号分隔列表。 使用 mfpdev app config language_preferences key-value 命令设置。
mfp:clientCustomInit 控制如何调用 WL.Client.init 方法。 缺省情况下，将此值设置为 false，将在初始化 MobileFirst 插件之后自动调用 WL.Client.init 方法。 针对客户机代码将此值设置为 true，以显式控制调用 WL.Client.init 的时间。 手动编辑。 您可以将 enabled 属性值设置为 true 或 false。
mfp:server 缺省远程服务器连接信息，客户机应用程序将使用此信息与 MobileFirst Server 进行通信。
  • url：url 值指定缺省情况下客户机将用于连接到服务器的 MobileFirst Server 协议、主机和端口值。
  • runtime：运行时值指定应用程序注册到的 MobileFirst Server 运行时。 有关 MobileFirst 运行时的更多信息，请参阅 MobileFirst Server 概述。
  • 使用 the mfpdev app config server 命令设置服务器 url 值。
  • 使用 mfpdev app config runtime 命令设置服务器运行时值。
mfp:ios 此元素包含针对 iOS 平台的所有与 MobileFirst 相关的客户机应用程序配置。
  • mfp:appChecksum
  • mfp:sdkChecksum
  • mfp:security
mfp:android 此元素包含针对 Android 平台的所有与 MobileFirst 相关的客户机应用程序配置。
  • mfp:appChecksum
  • mfp:sdkChecksum
  • mfp:security
mfp:windows 此元素包含针对 Windows 平台的所有与 MobileFirst 相关的客户机应用程序配置。
  • mfp:appChecksum
  • mfp:windowsphone8
  • mfp:windows8
  • mfp:windows10
mfp:windows8 此元素包含针对 Windows 8.1 平台的所有与 MobileFirst 相关的客户机应用程序配置。
  • mfp:sdkChecksum
  • mfp:security
mfp:windows10 此元素包含针对 Windows 10 平台的所有与 MobileFirst 相关的客户机应用程序配置。
  • mfp:sdkChecksum
  • mfp:security
mfp:windowsphone8 此元素包含针对 Windows Phone 8.1 平台的所有与 MobileFirst 相关的客户机应用程序配置。
  • mfp:sdkChecksum
  • mfp:security
mfp:appChecksum 此值是应用程序 Web 资源的校验和。 在运行 mfpdev app webupdate 时计算。 不是用户可配置的。 该校验和值在运行 mfpdev app webupdate 命令时更新。 有关 mfpdev app webupdate 命令的更多详细信息，请在命令窗口中输入 mfpdev help app webupdate。
mfp:sdkChecksum 此值是用于标识唯一 MobileFirst SDK 级别的 MobileFirst Operations Console SDK 校验和。 不是用户可配置的。 缺省情况下，此值已设置。
mfp:security 此元素包含特定于客户机应用程序平台的配置以确保 MobileFirst 安全性。 包含
  • mfp:testWebResourcesChecksum
mfp:testWebResourcesChecksum 控制每次在移动设备上开始运行应用程序时，应用程序是否验证其 Web 资源的完整性。 属性：
  • enabled：有效值为 true 和 false。 如果将此属性设置为 true，那么应用程序将计算其 Web 资源的校验和，并且会将此校验和与初次运行应用程序时存储的值进行比较。
  • ignoreFileExtensions：校验和计算可能需要几秒钟，这取决于 Web 资源的大小。 要使其更加快速，可以提供要在计算中忽略的文件扩展名列表。 当 enabled 属性值为 false 时，将忽略此值。
  • 使用 mfpdev app config android_security_test_web_resources_checksum key-value 命令设置 enabled 属性。
  • 使用 mfpdev app config android_security_ignore_file_extensions value 命令设置 ignoreFileExtensions 属性。

编辑 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 之后，您现在可以：

▲
Last modified on June 01, 2020