如何将您的BlackBerry WebWorks应用程序与BBM集成

欢迎来到我关于 BlackBerry® Messenger (BBM™) 社交平台系列博文的第三部分。我上一篇博文 集成 BBM 并让您的应用程序病毒式传播 介绍了 BlackBerry Messenger 社交平台 (BBM SP) 的功能以及如何使用它们来推广您的应用程序。如果您还没有阅读过，我建议您读一读。第二部分 如何将您的原生应用程序与 BBM 集成 介绍了 BBM SP 在原生应用程序中的使用。

现在我将介绍如何将您的 BlackBerry® WebWorks™ 应用程序与 BBM SP 集成。本文的大部分内容适用于 BlackBerry® OS 5-7 和 BlackBerry® 10 应用程序。但是，在撰写本文时，此处讨论的某些 BBM SP API 仅适用于 BlackBerry OS 5-7 应用程序 — 我已注明了这种情况。我们计划将这些也添加到 BlackBerry 10 WebWorks SDK 中。

目前，测试 BlackBerry 10 的 BBM SP 应用程序需要真实设备。我们正在努力为 BlackBerry 10 模拟器添加 BBM SP 支持，该支持应在 2012 年底前可用。我们提供的许多 BlackBerry 智能手机模拟器 都支持使用 BBM SP 测试 BlackBerry OS 5-7 应用程序，因此请确保您 下载一个列出了 BBM 支持的模拟器。

配置您的项目

BlackBerry® 10 WebWorks SDK 包含了您入门所需的一切。如果您有 BlackBerry OS 5-7 应用程序，除了常规的 BlackBerry WebWorks 智能手机 SDK 外，您还需要下载 BBM SDK v1.1 for BlackBerry WebWorks。在 Getting Started: BlackBerry WebWorks Development for Smartphones and the BBM Social Platform 中可以找到将这两个 SDK 连接起来以针对 BlackBerry OS 5-7 的说明。

为了让您的应用程序能够访问 BBM SP API，您需要在应用程序的 config.xml 文件中请求相应的权限。您需要添加两个元素：`rim:permissions` 的 `bbm_connect` 和 `feature` 的 `blackberry.bbm.platform`。看起来是这样的

<rim:permissions>
	<rim:permit>bbm_connect</rim:permit>
</rim:permissions>
<feature id="blackberry.bbm.platform" />

注册 BBM 社交平台

注册是连接 BBM 社交平台的第一步，涉及应用程序将自身注册到 RIM 托管的 BBM 基础设施。BlackBerry github 网站上提供了一个 BBM 示例，演示了 BBM SP 注册以及下载邀请功能。在本节阅读完毕后，您可以查看该示例以获取此处使用的代码片段的完整版本。

在使用 BlackBerry WebWorks 时，首先要注册 `onaccesschanged` 事件。如果您尝试在注册该事件之前进行注册，将会抛出 `IllegalStateException`。以下是注册该事件的方法

blackberry.event.addEventListener("onaccesschanged", function (accessible, status) {
	if (status === 'allowed') {
		/* Access allowed. */
	} 
});

此代码示例仅捕获允许状态。您的应用程序需要处理可能由用户超出覆盖范围或用户不允许访问 BBM 引起的不允许状态。 BBM 示例 演示了如何捕获其他状态。

每个应用程序都必须定义自己的通用唯一标识符 (UUID)，以便能够唯一地标识自己。在测试和开发过程中，此 UUID 用于向 BBM SP 服务器注册。BlackBerry App World™ 商店中的应用程序会自动分配自己的 UUID。您可以使用各种网站生成 UUID，例如 此处 提供的网站。在 BlackBerry WebWorks 中，UUID 存储在注册时使用的 options 参数中。

options = {
	uuid: "33490f91-ad95-4ba9-82c4-33f6ad69fbbc"
};

现在我们已准备好完成注册过程的最后一步，即使用我们上面定义的 options 参数调用 register 方法。这将触发 `onaccesschanged` 事件。

blackberry.bbm.platform.register(options);

下载邀请

下载邀请功能允许您的应用程序用户邀请他们的 BBM 联系人从 BlackBerry App World 下载您的应用程序。接收者通过 BBM 聊天会话接收邀请，其中包含应用程序和发送邀请的用户提供的消息。这是最容易实现的功能之一。注册后，只需调用一个方法即可完成。

blackberry.bbm.platform.users.inviteToDownload();

请注意，要使此功能在 BlackBerry 10 和 BlackBerry OS 5-7 用户之间正常工作，BlackBerry App World 中这两个版本的应用程序 (BAR 和 COD) 的 SKU 必须相同。

个人资料集成

BBM SP 允许对用户的 BBM 个人资料进行读写访问。这允许您的应用程序访问他们的个人资料消息、状态文本、可用性和头像。以下是一些使用这些 API 的示例

第一个代码示例展示了如何访问用户为其 BBM 个人资料设置的图像。

blackberry.bbm.platform.self.getDisplayPicture(function (image) {
    // do something with the image here
});
Now let’s look at how your application could update the user’s BBM profile picture.
blackberry.bbm.platform.self.setDisplayPicture("local:///smiley.jpg", function (accepted) {
    if(accepted) {
        // User allowed the change
    } else {
        // User denied the change
    }
});

如果个人消息是从 BBM 客户端以外的应用程序更新的，则会在更新下方显示一个标签，说明执行更新的应用程序的名称。用户可以点击该标签从 BlackBerry App World 下载该应用程序。这要求发送者已从 BlackBerry App World 安装了该应用程序，因此如果您为了测试而侧载了您的应用程序，该标签将不会带您到 BlackBerry App World。让我们看看如何更新个人消息和状态。

blackberry.bbm.platform.self.setStatus("busy", "Getting a new high score", function (accepted) {
    if(accepted) {
        // User allowed the change
    } else {
        // User denied the change
    }
});
blackberry.bbm.platform.self. setPersonalMessage ("I’m loving this app!", function (accepted) {
    if(accepted) {
        // User allowed the change
    } else {
        // User denied the change
    }
});

个人资料框

个人资料框为应用程序提供了另一种方式来向用户的 BBM 联系人推广自己。它们显示在用户个人资料的“应用”区域内，非常适合共享用户在应用程序中的活动。连接到 BBM SP 的每个应用程序都会出现在列表中。应用程序可以创建出现在其应用程序标题下的个人资料框项目。您可以提供自定义图像和字符串，用于创建个人资料框项目。

使用 BlackBerry WebWorks 添加个人资料框项目的能力在 BlackBerry 10 上尚不支持，但在 BlackBerry OS 5-7 上可以实现。有用于在 BlackBerry 10 上填充个人资料框的 C 和 C++ API，因此您可以通过构建自定义 BlackBerry WebWorks 扩展来实现此目的。

创建个人资料框项目时，图像的使用是可选的。如果您不想包含图像，可以将其从 options 变量中省略。

var options = {text:"No one’s ever beat me at solitare!", icon:"local:///cardshark.jpg", cookie:"unbeatable"};
blackberry.bbm.platform.self.profilebox.addItem(options);

联系人

应用程序可以检索已安装相同应用程序的 BBM 联系人列表。此列表可用作连接以实现多用户体验的选择标准。还会触发事件来通知联系人列表的更改，从而使您的应用程序能够跟踪联系人列表本身中联系人的添加和删除以及/或单个联系人的更改。

目前，使用 BlackBerry WebWorks 在 BlackBerry 10 上处理 BBM 联系人不受支持，但有适用于 WebWorks for BlackBerry OS 5-7 的 API 以及适用于 BlackBerry 10 的 C 和 C++ API。BlackBerry WebWorks for BlackBerry 10 的进一步支持计划在 12 月发布。请关注 BlackBerry WebWorks 路线图 以获取更新。

总结

以上是我关于使用 BlackBerry WebWorks 入门 BlackBerry Messenger 社交平台的介绍性博文。现在，您需要将这些 API 应用于您的下一个热门应用程序，该应用程序可能会在 Connected App Showcase 上展示。