将 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
跳转至:
- 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 并且 <10.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 文件。
新建应用程序
-
创建 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 功能,如多语言应用程序翻译和初始化选项(请参阅用户文档以获取更多信息)。
-
将目录更改为 Cordova 项目的根目录:
cd hello
-
使用 Cordova CLI 命令将一个或多个受支持的平台添加到 Cordova 项目:
cordova platform add ios|android|windows
。 例如:cordova platform add ios
注:由于已使用 MobileFirst 模板配置应用程序,因此将自动添加 MobileFirst 核心 Cordova 插件,因为已在步骤 3 中添加平台。
-
通过运行
cordova prepare
命令来准备应用程序资源:cordova prepare
现有应用程序
-
浏览至现有 Cordova 项目的根目录并添加 MobileFirst 核心 Cordova 插件:
cordova plugin add cordova-plugin-mfp
-
浏览至 www\js 文件夹并选择 index.js 文件。
-
添加以下函数:
function wlCommonInit() { }
在装入 MobileFirst 客户机 SDK 之后,MobileFirst API 方法将可用。 然后将调用 wlCommonInit
函数。
使用此函数调用各种 MobileFirst API 方法。
注册应用程序
-
打开命令行窗口并浏览至 Cordova 项目的根目录。
-
向 MobileFirst Server 注册此应用程序:
mfpdev app register
- 如果使用的是远程服务器,请使用命令
mfpdev server add
进行添加。
- 如果使用的是远程服务器,请使用命令
mfpdev app register
CLI 命令将先连接到 MobileFirst Server 以注册应用程序,然后使用标识 MobileFirst Server 的元数据更新 Cordova 项目根目录的 config.xml 文件。
会在 MobileFirst Server 中将每个平台注册为应用程序。
提示:您还可以从 MobileFirst Operations Console 注册应用程序:
- 装入 MobileFirst Operations Console。
- 单击应用程序旁边的新建按钮以注册新应用程序,并遵循屏幕上的指示信息。
使用 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 文档的根元素。 此元素包含两个必需属性:
|
|
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 进行通信。
|
|
mfp:ios | 此元素包含针对 iOS 平台的所有与 MobileFirst 相关的客户机应用程序配置。
|
|
mfp:android | 此元素包含针对 Android 平台的所有与 MobileFirst 相关的客户机应用程序配置。
|
|
mfp:windows | 此元素包含针对 Windows 平台的所有与 MobileFirst 相关的客户机应用程序配置。
|
|
mfp:windows8 | 此元素包含针对 Windows 8.1 平台的所有与 MobileFirst 相关的客户机应用程序配置。
|
|
mfp:windows10 | 此元素包含针对 Windows 10 平台的所有与 MobileFirst 相关的客户机应用程序配置。
|
|
mfp:windowsphone8 | 此元素包含针对 Windows Phone 8.1 平台的所有与 MobileFirst 相关的客户机应用程序配置。
|
|
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 | 控制每次在移动设备上开始运行应用程序时,应用程序是否验证其 Web 资源的完整性。 属性:
|
|
结束部分
编辑 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 教程
- 查看适配器开发教程
- 查看认证和安全教程
- 查看通知教程
- 查看所有教程