将 BlackBerry PaymentService 与 Adobe AIR 用于 PlayBook

引言

BlackBerry 的 AppWorld 服务之一是能够让您的用户在您的应用程序中购买商品。此服务提供了一个 API，供您在 PlayBook 应用程序的 AIR 中使用。继续阅读，了解使用此新 API 的基础知识，该 API 是 Beta 3 或 Tablet OS SDK for Adobe AIR 0.9.2 中新增的。

要真正测试 API，您必须作为供应商在 BlackBerry 注册您的商品。我现在不熟悉该过程，留待以后发布博客文章。以下是有关支付服务的更多信息链接。

尽管上述链接中的当前文档并未说明如何使用 Tablet OS SDK for AIR 进行特定于支付的 API 调用，但该 API 确实可用。本帖的其余部分将引导您完成一个可以在 github 的 PaymentService 文件夹下找到的示例应用程序。

PaymentService 应用程序外观如下

上图显示了两个标签和 3 个箭头图像。用户将点击一个特定的箭头来购买他们选择的箭头。

使用我关于 QNX 和 MXML 的帖子中的代码，我这样布局了应用程序

<?xml version="1.0" encoding="utf-8"?>
				<r:QApplication
  xmlns:fx="http://ns.adobe.com/mxml/2009"
  xmlns:r="http://ns.renaun.com/mxml/2010"
  margins="{Vector.&lt;Number&gt;([12,12,12,12])}"
  flow="{ContainerFlow.VERTICAL}"
  align="{ContainerAlign.NEAR}"
  size="100" sizeUnit="{SizeUnit.PERCENT}"
  xmlns:text="qnx.ui.text.*">
  
  <fx:Script source="PaymentServiceSource.as" />
  
  <text:Label text="Click to Purchase an Arrowhead:" 
      autoSize="{TextFieldAutoSize.LEFT}" />
  <r:Image source="com/renaun/embed/blue_arrowhead.png" 
       click="purchaseObject(event)" />
  <r:Image source="com/renaun/embed/green_arrowhead.png" 
       click="purchaseObject(event)" />
  <r:Image source="com/renaun/embed/red_arrowhead.png" 
       click="purchaseObject(event)" />
  <text:Label id="lblOutput" text="messages will show up here" 
      autoSize="{TextFieldAutoSize.LEFT}" />
				</r:QApplication>

这声明了一个具有垂直流的 QNX 容器，并添加了标签和图像。MXML 中的Image类（注意 r 命名空间）实际上是一个扩展了 QNX Image类的类，允许通过设置source属性来设置图像。实际逻辑发生在单击按钮时。以下是PaymentServiceSource.as文件的代码

import net.rim.blackberry.events.PaymentErrorEvent;
import net.rim.blackberry.events.PaymentSuccessEvent;
import net.rim.blackberry.payment.PaymentSystem;
import qnx.ui.core.ContainerAlign;
import qnx.ui.core.ContainerFlow;
import qnx.ui.core.SizeUnit;
import qnx.ui.data.DataProvider;

private var paymentService:PaymentSystem;

private var goods:Array = [{sku:"1001", name: "Blue Arrowhead", 
   meta: "saleprice", app: "Arrow R US", 
   icon: "/com/renaun/embed/blue_arrowhead_small.png"},
  {sku:"1002", name: "Green Arrowhead", meta: "saleprice", app: "Arrow R US", 
   icon: "/com/renaun/embed/green_arrowhead_small.png"},
  {sku:"1003", name: "Red Arrowhead", meta: "saleprice", app: "Arrow R US", 
   icon: "/com/renaun/embed/red_arrowhead_small.png"}]
  
protected function purchaseObject(event:MouseEvent):void
{
  if (!paymentService)
  {
    paymentService = new PaymentSystem();
    paymentService.addEventListener(
        PaymentErrorEvent.PAYMENT_SERVER_ERROR, paymentErrorHandler);
    paymentService.addEventListener(PaymentErrorEvent.USER_CANCELLED, 
        paymentErrorHandler);
    paymentService.addEventListener(PaymentErrorEvent.PAYMENT_ERROR, paymentErrorHandler);
    paymentService.addEventListener(PaymentErrorEvent.DIGITAL_GOOD_NOT_FOUND, 
        paymentErrorHandler);
    paymentService.addEventListener(PaymentSuccessEvent.PAYMENT_SUCCESS, 
        paymentSuccessHandler);
    // Set to local mode to test each event/state
    paymentService.setConnectionMode(PaymentSystem.CONNECTION_MODE_LOCAL);
  }
  // Very brittle way to look up the object i know.
  var obj:Object = goods[getChildIndex(event.target as DisplayObject)-1];
  paymentService.purchase(obj.sku, null, obj.name, obj.meta, obj.app, 
      "file://" + File.applicationDirectory.nativePath + obj.icon);
}
private function paymentSuccessHandler(event:PaymentSuccessEvent):void
{
  lblOutput.text = "Success: " + event.purchase.date + " - " + event.purchase.licenseKey;
}
private function paymentErrorHandler(event:PaymentErrorEvent):void
{
  lblOutput.text = "Error[" + event.type + "]: " + event.message;
}

首先要注意的是net.rim.blackberry.payment.PaymentSystem类。这是进行购买的 API。您创建一个PaymentSystem的新实例，然后调用purchase()方法。看起来很简单，其实复杂性在于处理所有成功和错误情况。此示例添加了对所有不同事件的侦听器，并将不同的消息输出到底部标签。

注意：0.9.2 SDK 中存在一个错误，如果您自动导入net.rim.blackberry.payments.PaymentSuccessEvent而不是net.rim.blackberry.events.PaymentSuccessEvent。这是一个元数据拼写错误，很可能在未来版本中得到修复，目前需要手动修复import语句中的拼写错误。

PaymentService在本地模式下运行，允许开发人员在连接到您已向 BlackBerry 注册为供应商的真实 SKU 之前测试所有不同的场景。这通过paymentService.setConnectionMode(PaymentSystem.CONNECTION_MODE_LOCAL);这行代码完成。如果您注释掉这行代码（这是默认设置），您将以生产模式运行，连接到实时 AppWorld 服务器。但在 BlackBerry Tablet OS PlayBook 模拟器上，如果您尝试这样做，会收到此消息

让我们仔细看看paymentService.purchase()方法调用。以下是来自BlackBerry Tablet OS SDK for Adobe AIR asdocs的当前文档信息。

digitalGoodID:String (default = null) — Digital Good ID

只需要要购买的数字商品的 ID 或 SKU；无需同时提供两者。如果同时提供了 ID 和 SKU，则 ID 具有优先权；仅当 Payment Service 无法根据 ID 定位数字商品时，才会使用 SKU。

digitalGoodSKU:String (default = null) — Digital Good SKU

请参阅digitalGoodID的说明。

可选参数

digitalGoodName:String (default = null) — Digital Good Name

在单个 ID/SKU 代表 Payment Service 服务器上的多个数字商品，并且购买屏幕上应显示更具体的数字商品名称的情况下，应提供数字商品名称。例如，如果一款游戏通过 Payment Service 出售额外的关卡，但价格相同，那么所有这些关卡都可以使用一个通用的“我的游戏关卡”数字商品。但是，在购买时，游戏应用程序应将“我的游戏关卡”替换为正在购买的关卡名称。这样，最终用户在购买确认屏幕上会确切地知道他们正在购买什么。

metaData:String (default = null) — Metadata

元数据为应用程序开发人员提供了一种将有关每个购买的信息存储在 Payment Service 服务器上的方法，并通过net.rim.blackberry.api.payment.PaymentSystem.getExistingPurchases(boolean)检索该数据。例如，假设一家图书供应商以单一价格提供多种图书，并在供应商门户网站上将它们表示为一个数字商品。在这种情况下，可以提供图书的 ISBN 作为元数据，它唯一标识所购买的数字商品。然后，可以通过获取先前的购买记录，通过getExistingPurchases方法，按图书的数字商品内容 ID 进行过滤，最后枚举每个购买记录的元数据中的 ISBN 来随时检索整个购买的图书列表。

purchaseAppName:String (default = null) — Purchase Application Name

为了在应用内购买期间为最终用户提供更多上下文，购买屏幕和 BlackBerry ID 登录屏幕的顶部会显示一个横幅，其中包含正在进行购买的应用程序的名称和图标（即，购买应用程序）。要自定义显示的名称和图标，只需将它们作为参数提供即可。如果未将名称或图标作为参数提供，则会从购买应用程序的描述符中检索它们。但是，对于动态注册到主屏幕的应用程序，这可能不起作用；在这种情况下，强烈建议购买应用程序在购买参数中显式提供名称和图标。

purchaseAppIcon:String (default = null) — Purchase Application Icon

请参阅purchaseAppName的说明。

在上面的代码示例中，所有参数都如所述工作。除了一点，我无法测试元数据参数数据。通过将PaymentService设置为本地连接模式，您可以模拟真实购买、取消购买、找不到商品和服务器错误。这是调用purchase()后外观如下。

以下是可用于测试的选项（按取消按钮也会发送消息）。

我不知道应用内购买 UI 是否会完全这样显示给用户，尤其是当文本提到“立即购买”按钮时。但您应该注意到，我能够通过 purchase 方法参数定义应用程序名称、商品名称和商品图标。价格似乎来自 AppWorld，并且可能由作为供应商注册商品和获得 SKU 的过程驱动。

无论如何，这就是关于如何开始使用新的PaymentService API 的当前信息。随着我们发现有关此 API 的更多信息，将有更多内容。

历史

• 2011 年 4 月 14 日：初始版本