IBM MobileFirst Platform 中的例子程序 Bluelist 使用指南

前言

IBM MobileFirst Platform for iOS 可以帮助用户快速地构建多平台的，本地的或者混合的的 iOS 应用。用户只需要专注于构建移动端应用，无需关心云端架构的复杂性，同时却可以方便快速地使用预设置的，可扩展的，可管理的云服务。

当用户在云管理平台创建 mobile back-end 应用时，多个服务会相应绑定到该应用上，用户可使用云平台提供的客户端 SDK 去构建 iOS 的本地应用，并使用这些云服务。同时您也可以获得服务器端的应用，方便您构建服务器端的功能，如资源 URI 或者静态文件等。被绑定的云服务包括如下几类：

Data（数据存储）：该服务基于 Cloudant NoSQL DB，用户可以存储，删除，更新，查询存储在云上的数据。

Push iOS 8：该服务可以向移动设备发送消息，当您配置了应用使用 Push 功能时，您就可以向所有注册的移动设备或者应用广播消息。

Security（安全）：该服务确保您的后台系统是加密的。您可以配置使用定制化的账户或者已有的社交账户（Google，Facebook）来登陆应用。

App Monitoring： 该服务可以帮助用户获得应用的性能数据，包括注册的设备，服务器以及客户端的日志等。

本文将使用例子程序 BlueList 来详细介绍如何在云平台上创建 mobile back-end 应用并使用其云服务。

回页首

BlueList 使用指南

BlueList 可在 Bluemix 官方网站获得，有两个版本，分别使用 Swift 和 Objective-c 编写，您可以查看其代码并熟悉它如何调用 iOS SDK 去使用云端服务。该应用会在移动设备上创建一些条目，并使用 Data 服务将这些条目存储在云端；您可以将您的设备注册到 Bluemix 控制台，这样用户便可以从 Bluemix 控制台上向对其进行注册的设备发送 push 通知，您也可以通过该应用熟悉安全服务以及监控服务。

前提条件

使用 BlueList 需要您准备以下的开发以及运行环境：

• Mac 计算机，需要 OSX10 以上的操作系统，并安装有 git 和 CocoaPods。
• BlueMix 的账户（ www.bluemix.net ）。
• DevOps Services 账户（hub.jazz.net）。
• 使用 Facebook 或者 Google 的认证方式需要您拥有 Facebook 和 Google 的开发者账号。

获得 BlueList 示例程序

您可以到 IBM DevOps Services 上使用 git 命令获得 BlueList 示例程序，此处存放有 Swift 和 Objective-C 两个版本。

1. 登陆 Bluemix 官方网站（ https://console.ng.bluemix.net/ ）
2. 点击 SOLUTIONS -> MobileFirst Platform >SAMPLES，您可以获得前往 IBM DevOps Services 的链接，如图 1 所示：

图 1. 获得 BlueList 源代码

1. 点击 Details -> Get the Code，便会前往 DevOps Services 网站，此处可以获得 BlueList sample 所有代码，即 mobilecloud|imf-bluelist 工程，链接为： https://hub.jazz.net/project/mobilecloud/imf-bluelist/overview 。
2. 在 mobilecloud|imf-bluelist 工程主页的右上角点击“Git URL”并复制您获得值，如下所示： https://hub.jazz.net/git/mobilecloud/imf-bluelist 。
3. 打开命令行终端，使用如下命令将 BlueList 示例程序复制到您本地的 Mac 开发环境。

git clone https://hub.jazz.net/git/mobilecloud/imf-bluelist

这里的 URL 就是您从 DevOps Services 中复制的 URL。

此时，您获得了 BlueList 所有的源代码以及配置文件。

构建 BlueList

BlueList 的正确运行需要相关的依赖，这里我们使用 CocoaPods 来获得其所需要的依赖。

1. 从 git 存储库中获得 BlueList 包括 Swift 和 Objective-C 两个版本。这里使用 Swift 版本作为示例。

   1. 如果您想使用 Swift，去如下目录：

      cd imf-bluelist/bluelist-swift

   2. 如果你想使用 Objective-C，去如下目录：

      cd imf-bluelist/bluelist-objective-c

2. 如果 CocoaPods 没有安装，请使用如下的命令进行安装：

   $ sudo gem install cocoapods$ pod setup

3. 使用 pod install 命令安装 BlueList 需要的所有的依赖库，包括 IBM SDK。如图 2 所示：

   图 2. 使用 CocoaPods 安装 BlueList 需要的依赖库

   
4. 依赖库安装成功，在同一目录下可生成 BlueList.xcworkspace 文件，您可以双击该文件或者使用命令 open BlueList.xcworkspace 在 Xcode 中打开该工作空间。
5. 选择 bluelist-swift 工程文件夹，您可以看到 Bundle Identifier 和版本信息。Bundle Identifier 是识别该应用程序的唯一标识，Push 推送功能将根据 Bundle Identifier 来识别设备和应用并推送消息。BlueList 的 Bundle Identifier 为“com.ibm.BlueList”。版本信息为 1.0.0。如图 3 所示：

   图 3. Bluelist-swift 应用程序概览

   

创建 Mobile back-end 应用。

您可以通过两种途径来创建 Mobile back-end 应用。第一是通过图 1 所示中点击 Run on Bluemix，可以帮助您直接生成应用。本文将介绍第二种，用户自己创建应用，方便用户熟悉应用创建流程。

1. 使用 Blumix 账号登陆 https://www.bluemix.net/ 。
2. 从控制面板中点击 Create an App。如图 4 所示：

   图 4. 创建 back-end 应用

   
3. 选择 Mobile，如图 5 所示：

   图 5. 选择 back-end 应用类型

   
4. 选择 iOS 8，如图 6 所示：

   图 6. 选择 back-end 应用为 iOS 8 类型

   
5. 如果开发者准备使用 Goole OAuth 或者 Facebook OAuth 作为移动应用程序的认证方式，则可以点击 Continue 继续下一步；反之，如果开发者希望使用 Custom OAuth 方式认证移动应用程序，则需要确保 Advanced Mobile Access 服务的 Plan 是 Gold，此时需点击 View Details in Catalog，如图 7 所示。

   图 7. 选择 back-end 应用的 Catalog 属性

   
6. 选择 Advanced Mobile Access，确保 Plan 选择了 Gold。如上一条解释的原因所述，如果 Advanced Mobile Access 的 Plan 是 Bronze，则开发者只能选择使用 Google OAuth 或者 Facebook OAuth 方法认证移动应用程序。本例中我们选择使用 Custom OAuth 方法进行认证。在右边输入任何名字，确保您并未在 Bluemix 中使用过该名字创建应用，点击 Create 完成应用的创建。如图 8 所示。应用创建成功会提供给您一页信息页，您可以从该页获得如何使用 Bluemix 的基本指南。

   图 8. Advanced Mobile Access 的 Plan 名称和应用名字

   
7. 点击回到控制面板进入刚才创建的应用，您可以从图 9 中看到该应用绑定了三个服务，分别为 Advanced Mobile Access，Cloudant NoSQL DB 和 Push iOS 8.

   图 9. 应用 BlueListTestGN 的概览

   

配置用户权限

默认情况下，连接到新创建的 back-end 应用的客户端应用是不需要认证的，但是 BlueList 例子程序是需要配置用户认证机制的。这里，我们可以使用 Facebook，Google 或者 Custom 的认证方式。这也是 MobileFirst Platform 提供的安全服务，也即是 Advanced Mobile Access 服务。

• 如果您使用 Facebook 的认证方式，您需要 Facebook 应用以及其应用 ID。
• 如果您使用 Google 的认证方式，您需要 Google 应用。

三种认证方式您任选一种即可，本文将详细介绍 Custom 的认证方式，其余两种认证方式将由本系列文章中的另外一篇文章进行详细介绍。

1. 从图 10 中点击进入 Advanced Mobile Access 配置页面，点击 New Mobile Client，如图 10 所示。其中注意这里面的 Route 值和 UID 值，后续配置将会使用。

   图 10. 创建新的移动客户端

   
2. 输入名字，这里我们使用 BlueList，然后点击 Next，如图 11 所示：

   图 11. 给客户端命名

   
3. 这里输入 Bundle ID，为 com.ibm.BlueList，Version 为 1.0.0，即为您在 BlueList 工作空间中获得的 Bundle Identifier 和版本信息，如图 12 所示。点击页面右下角的 Done 完成配置。

   图 12. Bundle ID 和 Version 等信息

   
4. 点击 Allows Unauthenticated access to the backend，进入授权信息配置页面。如图 13 所示：

   图 13. 进行认证配置

   
5. 点击 New Authentication，如图 14 所示。

   图 14. 创建新的认证方式

   
6. 选择 Custom 方式，如图 15 所示。如果您使用其他两种认证方式，您可以从这里进行选择。

   图 15. 选择认证方式

   
7. 输入 Realm Name，这里为 customeAuthRealm_1，URL 值即为图 16 中所示的 Route 值。

   图 16. Custom 方式的 Realm Name 值和 URL 值

   
8. 点击 Save 完成 Custom 认证方式的配置。如图 17 所示。

   图 17. Custom 认证方式概览

   

将 Bluelist 连接到 Bluemix

要将 BlueList 程序链接到 Bluemix 上并使用其提供的 Cloudant NoSQL DB 服务，需要对该程序进行一些配置的修改。

1. 在 Xcode 中已经打开的 BlueList 工作空间中，找到 bluelist-swift->Supporting Files 下面的 bluelist.plist 文件。其中 applicationRoute 和 applicationId 都是空白。
2. 前往 mobile back-end 应用 BlueListTestGN 的控制台，进入 Advanced Mobile Access，从 Client Registration 中您可以看到 Route 和 UID 两项值，如图 18 所示。

   图 18. Advanced Mobile Access 配置页面的应用 Route 和 UID 信息

   
3. 拷贝其中的 Route 值，如 https://bluelisttestgn.mybluemix.net 设置为 bluelist.plist 文件的 applicationRoute 的值；UID 的值，如 b66eeb39-4289-4ad3-a6e2-9b3d3c81e61b 设置为 bluelist.plist 文件中 applicationId 的值。
4. 使用 custom 的认证方式需要您将认证服务放到 Node.js 运行环境中。您下载的该 BlueList 示例程序包含这样一个 Node.js 应用，在目录 imf-bluelist/custom-auth-nodejs 文件夹下面。更新 manifest.yml 文件使其值和您所创建的 mobile back-end 应用保持一致。如代码片段 1 所示：

   清单 1.代码片段 1

   applications:   - disk_quota: 1024M   host: BlueListTestGN  name: BlueListTestGN  command: node app.js   path: .   domain: mybluemix.net   instances: 1   memory: 128M

5. 更新 bluelist.plist 同目录下的 Info.plist 文件。将其中的 CustomAuthenticationRealm 值设置为 customAuthRealm_1，该值必须保证同您在 Bluemix 上 mobile back-end 应用中设置的值以及 Node.js 应用中 app.js 文件中设置的值一样。文件 app.js 如代码片段 2 所示，从该代码片段中可以看到 customRealm = 'customAuthRealm_1'；同时您也可以得到使用 custom 方式来认证的用户名和密码放在变量 users 里面进行定义。

   清单 2. 代码片段 2

   点击查看代码清单

   关闭 [x]

   清单 2. 代码片段 2

   var express = require('express'),   passport = require('passport'),   ImfBackendStrategy = require('passport-imf-token-validation').ImfBackendStrategy,   customRealm = 'customAuthRealm_1';      passport.use(new ImfBackendStrategy());    // setup middleware   var app = express();    app.use(passport.initialize());   app.use(express.bodyParser());   app.use(app.router);   app.use(express.errorHandler());    app.post('/apps/:tenantID/'+customRealm+'/startAuthorization',   passport.authenticate('imf-backend-strategy', {session: false}),   function(req, res) {   console.log ("tenantID " + req.param("tenantID"));   var returnedJSON = startAuthorization(req.body.headers);   res.json(returnedJSON);   });    app.post('/apps/:tenantID/'+customRealm+'/handleChallengeAnswer',   passport.authenticate('imf-backend-strategy', {session: false}),   function(req, res) {   console.log ("tenantID " + req.param("tenantID"));   var returnedJSON = handleChallengeAnswer(req.body.headers, req.body.stateId, req.body.challengeAnswer);   res.json(returnedJSON);   });    var users = {   "john": {  password: "123",   displayName: "John Lennon"  },   "paul": {   password: "456",   displayName: "Paul McCartney"  }   };    var startAuthorization = function(headers) {   return {   status: "challenge",   challenge: {   message: "wrong_credentials"  }, stateId : "myStateId"  };   };    var handleChallengeAnswer = function(headers, stateId, challengeAnswer) {   console.log('State id ' + stateId);   if (challengeAnswer && users[challengeAnswer.userName] && challengeAnswer.password === users[challengeAnswer.userName].password) {   return {   status: "success",   userIdentity: {   userName: challengeAnswer.userName,   displayName: users[challengeAnswer.userName].displayName   }   };   } else {   return {   status: "challenge",   challenge: {   message: "wrong_credentials"  }   }   }   };    // There are many useful environment variables available in process.env.   // VCAP_APPLICATION contains useful information about a deployed application.   var appInfo = JSON.parse(process.env.VCAP_APPLICATION || "{}");   // TODO: Get application information and use it in your app.    // VCAP_SERVICES contains all the credentials of services bound to   // this application. For details of its content, please refer to   // the document or sample of each service.   var services = JSON.parse(process.env.VCAP_SERVICES || "{}");   // TODO: Get service credentials and communicate with bluemix services.    // The IP address of the Cloud Foundry DEA (Droplet Execution Agent) that hosts this application:   var host = (process.env.VCAP_APP_HOST || 'localhost');   // The port on the DEA for communication with the application:   var port = (process.env.VCAP_APP_PORT || 3001);   // Start server   app.listen(port, host);   console.log('Custom authentication App started on port ' + port);

6. 使用 cf 命令行工具输入如下命令连接 bluemix 将 nodejs 应用上传。

   cf api https://api.ng.bluemix.net

   cf login – a your_username – p your_password

   cf push

运行 BlueList

为方便读者，本示例将使用模拟器运行该 iOS 应用。应用成功运行后，您可以添加条目并且对条目进行优先级排序，这些数据将会存储在 iOS 设备本地，同时也保存到云端，这里使用的是 Cloudant NoSQL DB 的服务。

1. 从 Xcode 中选择模拟器，这里面我们使用 iPhone6，然后点击 Run 按钮。如图 19 所示。

   图 19. 运行 BlueList

   
2. BlueList 启动之后会需要您输入用户名和密码认证，该用户名和密码可以在 app.js 文件中获得。请前往代码片段 2 中找到 users 变量下面所定义的用户名和密码，如用户名是 John，密码是 123。输入之后点击 OK 确认登陆 BlueList 应用。如图 20 所示。

   图 20. BlueList 登陆界面

   

3. 使用 BlueList 应用，您可以添加条目并且进行优先级排序。其中红色是 High 的优先级，黄色是 Medium 的优先级。如图 21 所示 .

   图 21. 输入任意的条目并设置优先级

   

   同步您刚才保存的本地数据到云端，从模拟器上面向下拉即可，如图 22 所示。

   图 22. 同步在移动客户端的数据到云端

   
4. 在 Bluemix 上的 Coudant NoSQL DB 查看刚才存储的数据。
   1. 从控制面板，点击 Coudant NoSQL DB 服务。如图 23 所示。

      图 23. 选择 Cloudant NoSQL DB 服务

      
   2. 从左边的目录中选择 Objects and Documents。如图 24 所示。

      图 24. 选择查看数据的选项 Objects and Documents

      
   3. 在 Objects and Documents 页面上，选择一个查询，查询的值已经出现在查询框的下拉框里面，选择数据库库（todosdb_john），@datatype 等于 TodoItem，这时您将看到您刚才从客户端应用上存储的条目，即 the first try 和 the second try，同样，其优先级分别为 2 和 1 代表其不同的优先级。如图 25 所示。

      图 25. 根据条件过滤移动客户端同步的数据

      

配置和使用 Push 通知

在 BlueList 中使用 push 通知，您必须有一个唯一的 App Bundle ID 和一个 Apple Push Notification service（APNs）的证书（.p12）。这个 App Bundle ID 是从 Apple 官方获得用来测试 Push 通知功能，证书也是从 Apple 开发者中心获得。

Push 功能只适用于 iOS8 及以上的版本，并且应用只能安装在真实的 iOS 设备上，而非模拟器，该设备也必须是已经在 Apple 官网进行注册的设备。

1. 从 Bluemix 控制面板，点击 Push iOS 8 service。如图 26 所示。

   图 26. 选择 Push iOS 8 服务

   
2. 从左侧菜单中选择 Configuration，然后点击 Configuration Push。如图 27 所示 .>

   图 27. 配置 Push

   
3. 上传 APNS 的证书，为一个 .p12 文件，输入该证书的密码，点击 Save 进行保存。如图 28 所示。

   图 28. 配置 APNs 证书

   
4. 保存后的配置如图 29 所示：

   图 29. Push 配置概览

   
5. Push 功能需要真实的 iOS 设备，所以这里需要您准备一台 iOS8 或者以上的设备，本示例中使用的是 iPad3。在 Xcode 中选择您连接到开发用电脑上的 iOS 设备，如图 30 所示。

   图 30. 选择真实设备

   
6. 在 Targets 中选择 bluelist-swift，在 General 标签页，选择你所属的开发者团队，如图 31 所示。这里我们假设您已经具有苹果的开发账号，可以在真实的设备上运行其应用。

   图 31. 配置开发者团队

   
7. 在 Build Settings 标签页，选择您所属的开发团队所使用的正确的 provisioning profile 和 code signing 证书。如图 32 所示：

   图 32. 配置 code signing 和 provisioning profile

   
8. 点击 Run 按钮运行 BlueList 程序，该程序将运行在你连接的 iOS 设备上，在运行的同时 BlueList 会向 Bluemix 的 Push iOS 8 服务进行注册，因此后续您可以通过 Bluemix 控制面板向该设备发送 notification 通知。应用在真实设备上运行起来之后，同本文前边所述步骤一样，输入用户名和密码登陆应用。
9. BlueList 应用成功运行起来后，从 BlueListTestGN 应用的 Push iOS 8 服务控制面板，点击左侧菜单栏中 Notifications，然后点击 Send Notification。如图 33 所示。

   图 33. 发送 notification

   
10. 选择 All Registered mobile Devices，点击 Next。如图 34 所示。

    图 34. 选择要发送 notification 的设备

    
11. 在 Message Test 中输入您想广播的消息，如本文示例使用 This is for test，点击 Next。如图 35 所示。

    图 35. 配置待发送的消息

    
12. 确认页面确认您输入的信息的正确性，然后点击 Send，如图 36 所示。

    图 36. 发送 notification 通知

    
13. 当信息发送到移动苹果设备后，您将会得到确认信息，确认您所发送的消息已经成功送达。同时，您也可以从所连接的 iOS 设备上查看到您所发送的通知。如图 37 所示。

    图 37. 发送成功验证页面

    
14. 在上面所述的第 6 步，如果您想查询注册的设备有哪些，可以根据其提供的选项进行查询。如这里可以使用 By consumer ID 来查询，由于之前是 Advanced Mobile Access 进行认证的用户是 John，所以您可以输入 J 可见其会将该用户注册的设备过滤出来从而方便用户选择设备进行消息的广播。如图 38 所示。

    图 38. 过滤注册在同一个 back-end 上的设备

    

监控和分析服务

IBM MobileFirst Platform 向用户提供监控和分析工具，您可以从应用的控制面板获得该项服务。这里将结合 BlueList 给出一个简单的示例，详尽的功能介绍请参阅我们的系列文章或者 Bluemix 的文档。

1. 从应用的控制面板进入 Advanced Mobile Access 服务，左侧菜单栏中选择 monitoring。同样，您也可以进入 Cloudant NoSQL DB 或者 Push iOS 8 服务。如图 39 所示。

   图 39. Monitoring 服务

   
2. 从这里您将可以观察，分析该应用以及连接到该应用的设备的数据，包括其使用情况，网络，设备，日志以及性能等等信息。如图 40 是一个简单的示例。

   图 40. 应用数据概览

   

回页首

总结

现在您已经了解了如何安装并运行例子程序 BlueList，同时也了解了 BlueList 赖以运行的后台云端服务，并清楚如何创建 mobile back-end 应用和配置各项服务。为深入理解 IBM MobileFirst Platform 提供的 SDK 以及各项服务，我们建议您阅读一下 BlueList 的源代码或者官方提供的文档（有代码片段），方便您更好的利用 IBM MobileFirst Platform 开发自己的移动端应用。