开发者控制台

亚马逊应用内购买组件

亚马逊应用内购买组件

四: 添加组件以获得更多功能

亚马逊应用内购买组件使用亚马逊的应用内购买 (IAP) API将购买选项集成到您的应用中。

可用的购买选项

应用内购买组件在您的应用中提供两种不同的购买选项:

  • Daily Pass(每日通行证): 允许用户观看应用中的任何媒体一天(从购买之时起24小时)。这类似于24小时无限制电影租赁。
  • Go Premium(高级版): 允许用户支付订阅费,从而可以在订阅期限间观看应用中的任何媒体。在亚马逊开发者控制台中设置应用程序内商品时,您可以定义订阅时间段。

借助应用内购买组件,您不必再为处理与用户的交易而烦恼。用户通过在配置Fire TV时设置的亚马逊账户进行购买。您应用中的所有交易细节都由应用内购买API负责处理。

亚马逊应用内购买组件的用户体验

在应用中实现亚马逊应用内购买组件后,用户会在Content Details(内容详情)屏幕上看到“Daily Pass”(每日通行证)和“Go Premium”(高级版)(而非Watch Now(立即观看)按钮)。

图1. 用户可以在Content Details(内容详情)屏幕上选择订阅或购买每日通行证。

当用户单击“Daily Pass”(每日通行证)或“Go Premium”(高级版)按钮时,系统会提示用户使用其Fire TV账户进行购买。例如,如果用户单击“Go Premium”(高级版),则会出现以下屏幕:

图2. 对用户显示的订阅选项对话框。

如果用户单击“Daily Pass”(每日通行证),则会出现以下屏幕:

图3. 对用户显示的租赁选项对话框。

用户使用自己的亚马逊账户通过Fire TV对话框完成交易,该账户是用户在设置Fire TV时输入的账户。当交易完成时,用户会看到以下屏幕:

图4. 订购完成。

用户现在可以开始观看内容。

应用内购买的注意事项和限制

请注意有关亚马逊应用内购买组件的以下详细信息:

  • 您必须同时为您的媒体提供Daily Pass(每日通行证)(24小时访问)和Go Premium(高级版)(订阅)选项。
  • 当用户购买了Daily Pass(每日通行证)和Go Premium(高级版)时,他们就可以访问您应用中的所有媒体。您不能在保持其他商品免费的同时,单独分离出一些商品供用户订阅或租赁。
  • 在用户重启应用或尝试播放内容之前,在其他设备上进行的购买不会在应用中得到确认。(当进入后台状态时,应用不会刷新已购买的商品。)
  • 如果用户在Daily Pass(每日通行证)或订阅到期时正在看电影,用户可以将当前所观看的电影看完。应用内购买组件无法将他们正在观看的电影停止。
  • 您不能为同一媒体提供多种订阅类型。例如,您不能为用户观看的内容提供SD(标清)或HD(高清)选项,也不能提供每月或每年订阅。
  • Daily Pass(每日通行证)只能在进行购买的设备上使用。用户无法登录其他Fire TV设备并期望Daily Pass(每日通行证)正常生效。
  • Go Premium(高级版)订阅可跨设备生效(这意味着用户可以在一台Fire TV设备上购买订阅,并在另一台Fire TV设备上获得相同的权益)。但是,登录到另一台设备的用户需要重新启动应用才能让订阅生效。
  • 如果用户购买了Daily Pass(每日通行证),但Fire TV应用崩溃,数据丢失,则用户将无法再使用该应用上的Daily Pass(每日通行证)。但是,如果拥有Go Premium(高级版)(订阅),应用崩溃不会导致用户在重新启动应用后无法访问内容。
  • 如果用户订阅了内容,然后单击Back(后退)按钮,该用户将再次看到Go Premium(高级版)按钮。但是,如果用户尝试第二次订阅,应用将识别出用户已经是订户,并将对其提供媒体的访问权限。

亚马逊应用内购买组件工作流程

以下步骤描述了亚马逊应用内购买组件的付款工作流程:

  1. 当应用启动时,应用使用应用内购买API来获取当前登录用户的现有购买情况,并使用最新的收据更新产品。
  2. 在Content Details(内容详情)屏幕上,用户单击Daily Pass(每日通行证)或Go Premium(高级版)按钮(假设用户尚未购买媒体)。
  3. 应用调用应用内购买API,与用户进行商品交易。用户通过自己设置好的Fire TV账户选项来完成购买。
  4. 如果交易成功,应用内购买API会将交易的收据ID返回给应用。
  5. (可选)为确保收据有效,您可以设置自己的服务,向收据验证服务发送请求并检查收据ID是否有效。
  6. 如果收据ID有效,则应用允许用户观看媒体。

配置概述

要设置应用内购买组件,请在开发者门户的应用程序内商品部分创建Daily Pass(每日通行证)商品(消费品)和Go Premium(高级版)商品(订阅)。您可以使用这些商品的SKU信息配置您的应用。该组件将必要信息发送到应用内购买API。

亚马逊应用内购买组件在IAP API上使用包装器。IAP仅提供有限的功能集;因此,这里的文档是IAP文档的经修改子集。

Daily Pass(每日通行证)(消费品)和Go Premium(高级版)(订阅)

应用内购买提供3种类型的商品:消费品、权利和订阅。只有消费品和订阅与Fire App Builder中的应用内购买组件相关(该组件是IAP API之上的包装器,因此并非所有IAP API功能都适用)。消费品和订阅商品(非权利)都映射到亚马逊应用内购买组件。

以下是消费品和订阅之间的区别:

  • 消费品(对应Daily Pass(每日通行证))在应用内消费,可以多次购买。在Fire App Builder中消费品映射到“Daily Pass”(每日通行证)。如果您希望用户在24小时访问期内访问您的所有媒体,请选择此类型的商品。
  • 订阅(对应Go Premium(高级版))允许在有限时间内访问一组高级内容或功能。在Fire App Builder中订阅对应于“Go Premium”(高级版)。如果您希望用户在整个订阅期限内访问您的所有媒体,请选择此类型的商品。

亚马逊应用内购买组件配置

要配置应用内购买组件,请按照以下步骤操作:

步骤1.在开发者门户中创建应用

如果您已经创建了应用,则可以跳过本部分,前往下一个部分。

  1. 登录开发者门户。
  2. 单击添加新应用程序,然后在“Choose a Platform”(选择平台)对话框中选择Android。然后单击下一步
  3. 填写应用的基本字段:

    • 应用标题: 您的应用的名称。
    • 应用SKU: 您应用的唯一标识符(例如,mycalypsomediapp1234)。SKU的最大长度为150个字符,可包含a-z、A-Z、0-9、下划线、句点和短划线。SKU区分大小写。
    • 类别: 选择适合您的应用和媒体的类别。
  4. 对于客服联系信息,可以选择使用我的默认客服信息或自定义字段。然后单击保存

步骤2.创建Daily Pass(每日通行证)消费品型应用程序内商品

  1. 登录开发者门户,进入主信息页面,然后单击您的应用。
  2. 单击应用中的应用程序内商品选项卡。
  3. 单击添加消费品按钮(适用于Daily Pass(每日通行证))。

    图5. 对用户显示的租赁选项对话框。
  4. 为下表中定义的字段输入值:

    字段 描述
    标题 指代此商品的名称。该标题不会显示给用户。出于方便起见,可键入Daily Pass(每日通行证)。
    SKU 您应用的唯一字符串,会成为商品的ID。例如“com.amazon.example.iap.mydailypassitem”。应用使用的SKU必须与您提交到亚马逊应用商店的SKU匹配。与之前(创建应用时)相同的SKU字符要求在这里也适用。
    Content delivery(内容交付) 选择No additional file required(无需额外文件),因为要交付的内容是作为应用的一部分加入。
  5. 单击保存。​

  6. 单击销售国家 (地区) 和标价选项卡并填写下表所述的详细信息。

    字段 描述
    Are you charging for this consumable/entitlement?(您是否对此消费品/权利收费?) 选择是,我的基本价格为...,则系统将显示为商品设置基本价格和币种的字段。在设置了基本价格后,您可以手动设置其他币种的价格,或让亚马逊应用商店根据汇率和税款为您设置这些价格。有效价格可以是0.00美元,也可以在0.99美元到400美元之间。
    您希望此商品何时可用? 指定商品在应用中可供购买的日期(IAP使用PST时区)。如果您将此字段留空,则商品将在获得亚马逊应用商店批准后立即可用。
  7. 单击保存。​
  8. 单击描述选项卡。
  9. 填写显示标题描述字段。

    这些字段在用户单击Daily Pass(每日通行证)之后显示在对话框中:

    图6. 向用户显示的“标题”和“描述”字段。
  10. 单击保存。​
  11. 单击图像选项卡。
  12. 根据尺寸要求上传两张图像。只有114像素的图像会显示在用户于应用中看到的Daily Pass(每日通行证)对话框中。在上一个屏幕截图(图6)中,图像只是一个橙色正方形。在创建512像素的图像时,出于方便起见,您可上传这个通用图像
  13. 单击保存。​

步骤3.创建订阅型(Go Premium(高级版))应用程序内商品

  1. 如果需要,登录开发者门户,进入主信息页面,然后单击您的应用。
  2. 单击应用中的应用程序内商品选项卡。
  3. 单击添加订阅按钮(适用于Go Premium(高级版)).(在“Subscriptions are not supported by Amazon Underground”(Amazon Underground不支持订阅)提示出现时,再次单击添加订阅按钮。)
  4. 为下表中定义的字段输入值:

    字段 描述
    标题 指代此商品的名称。该标题不会显示给用户。出于方便起见,可键入Go Premium(高级版)。
    SKU 您应用的唯一字符串,会成为商品的ID。例如,“com.amazon.example.iap.mygopremiumitem。” 应用使用的SKU必须与您提交到亚马逊应用商店的SKU匹配。与之前(创建应用时)相同的SKU字符要求在这里也适用。
    Content delivery(内容交付) 选择No additional file required(无需额外文件),因为要交付的内容是作为应用的一部分加入。
  5. 单击保存。​

  6. 单击订阅期限选项卡,并按照下表的定义填写字段。

    字段 描述
    订阅期限 选择您需要的订阅持续时间。订阅期限从购买日期开始。
    SKU 输入与此订阅期限对应的SKU(使用与其他SKU字段相同的指南)。例如,“com.amazon.example.calypso.monthly”。此SKU是您在商品详情页面上输入的SKU的子SKU。
    免费试用 如果需要,为订阅指定可选的免费试用期。
    您是否对此订阅收费? 选择是,我的基本价格为...。则系统将显示为商品设置基本价格和币种的字段。在设置了基本价格后,您可以手动设置其他币种的价格,或让亚马逊应用商店根据汇率和税款为您设置这些价格。有效价格可以是0.00美元,也可以在0.99美元到299美元之间。
    您希望此商品何时可用? 指定商品在应用中可供购买的日期(IAP使用PST时区)。如果您将此字段留空,则商品将在获得亚马逊应用商店批准后立即可用。
  7. 单击保存。​
  8. 单击描述选项卡。
  9. 填写显示标题描述字段。

    这些字段在用户单击Go Premium(高级版)之后显示在对话框中:

    图7. 向用户显示的“标题”和“描述”字段。
  10. 单击保存。​
  11. 单击图像选项卡。
  12. 开发者控制台需要图像图标,但与Daily Pass(每日通行证)(消费品)不同的是,用户在应用中看到的Go Premium(高级版)对话框中使用这两个图像中的任一个。出于方便起见,您可以上传这个通用的114像素图像和这个通用的512像素图像
  13. 单击保存。​

步骤4.下载并推送JSON数据文件

配置Daily Pass(每日通行证)和Go Premium(高级版)应用程序内商品后,您将下载一个JSON文件,其中包含有关应用程序内商品的详细信息。

  1. 如果需要,登录开发者门户,进入主信息页面,然后单击您的应用。
  2. 单击应用中的应用程序内商品选项卡。
  3. 单击JSON数据文件按钮下载包含您的应用程序内商品详情的JSON文件。

  4. 在您的终端中,cd到包含此文件的目录。
  5. 使用以下命令将JSON文件推送到您的Fire TV设备:

    $ adb push amazon.sdktester.json /mnt/sdcard/
    

    响应将显示以下内容:[100%] /mnt/sdcard/amazon.sdktester.json

步骤5.在您的应用中启用应用内购买组件

现在,您已经在开发者控制台中创建了应用程序内商品,您需要在应用程序中启用IAP组件。

  1. 将亚马逊应用内购买组件加载到您的应用中。有关如何将组件加载到应用中的详细信息,请参阅加载组件
  2. 在Android Studio中,展开ContentBrowser文件夹,然后转到res > values(res >值),然后打开custom.xml文件。
  3. 复制以下字符串:

    <bool name="is_iap_disabled">true</bool>
    

    (忽略override_all_contents_subscription_flag字段。)

  4. 在您的app文件夹中,打开custom.xml文件(位于res > values(res >值)中)。
  5. 粘贴之前复制的字符串并将该值更改为false。务必将此字符串粘贴到resources标签中:

    <bool name="is_iap_disabled">false</bool>
    

    应用的custom.xml中的值将覆盖组件中的任何值。

步骤6.将应用程序内商品映射到您应用中的内容

  1. 在Android Studio中,展开PurchaseInterface文件夹,然后转到assets(资产)。然后打开skuslist.json文件。

  2. 对于“Go Premium”(高级版)商品,将红色字段替换为您的Go Premium(高级版)商品的SKU值。

    {
      "skusList": [
        {
          "sku": "testSubSku",
          "productType": "SUBSCRIBE",
          "purchaseSku": "testSubSku"
        },
        {
          "sku": "RentUnPurchased",
          "productType": "RENT",
          "purchaseSku": "RentUnPurchased"
        }
      ],
      "actions": {
        "CONTENT_ACTION_DAILY_PASS": "RentUnPurchased",
        "CONTENT_ACTION_SUBSCRIPTION": "testSubSku"
      }
    }
    

    Go Premium(高级版)商品为订阅商品。

  3. 对于“Daily Pass”(每日通行证)商品,将红色字段替换为您的Daily Pass(每日通行证)商品的SKU值。

    {
      "skusList": [
        {
          "sku": "testSubSku",
          "productType": "SUBSCRIBE",
          "purchaseSku": "testSubSku"
        },
        {
          "sku": "RentUnPurchased",
          "productType": "RENT",
          "purchaseSku": "RentUnPurchased"
        }
      ],
      "actions": {
        "CONTENT_ACTION_DAILY_PASS": "RentUnPurchased",
        "CONTENT_ACTION_SUBSCRIPTION": "testSubSku"
      }
    }
    

    Daily Pass(每日通行证)商品为租赁商品。

步骤7.自定义按钮文本

您可以自定义Content Details(内容详情)屏幕按钮上显示的“Daily Pass”(每日通行证)或“Go Premium”(高级版)文本。

要自定义文本,请执行以下操作:

  1. 前往ContentBrowser > res > values(ContentBrowser > res >值),然后打开strings.xml文件。
  2. 复制以下字符串并将其粘贴到应用的custom.xml文件:

    <string name="premium_1">Go</string>
    <string name="premium_2">Premium</string>
    <string name="daily_pass_1">Daily</string>
    <string name="daily_pass_2">Pass</string>
    

    您也可以在此处复制与购买组件相关的其他字符串:

    <string name="iap_error_dialog_title">Purchase Error</string>
    <string name="subscription_expired">Your subscription expired!</string>
    <string name="ok">Ok</string>
    
  3. 根据需要自定义字符串值。

步骤8.设置App Tester

您已经设置了应用程序内商品并配置了应用,那么是时候测试一下集成了,由此看看IAP如何与您的媒体交互。

要在应用中测试应用程序内商品(无需实际购买,并且可以在将应用提交到亚马逊应用商店之前进行),您需要使用IAP App Tester。App Tester使用沙盒服务器模拟对应用内购买API的调用。App Tester会拦截对应用内购买API的传出调用,并返回有效的收据,对交易授权。有关更多详细信息,请参阅安装并配置App Tester

要设置App Tester,请执行以下操作:

  1. 使用电脑的浏览器,前往App Tester from the AppStore(来自亚马逊应用商店的App Tester),获取应用(免费),然后将其交付到您的设备。

    要将此应用交付到您的设备,您必须使用与设置Fire TV时相同的凭证登录亚马逊。使用“Deliver to”(交付到)选项将应用交付到您的设备:

    图9. Delivery(交付)选项允许您将应用发送到您的Fire TV设备。
  2. 在Fire TV上,前往Settings(设置)> My Account(我的账户)> Sync Amazon Content(同步亚马逊内容),将购买的商品与设备同步。
  3. 在Fire TV主页屏幕上,前往Apps(应用),然后选择Your Apps Library(您的应用库)。
  4. 选择 Amazon App Tester应用,然后从云下载并安装该应用。
  5. 下载完成后启动应用。
  6. 单击应用内购买API部分。

    图10. In-App Purchasing API(应用内购买API)选项。
  7. 选择5.IAP Items in JSON File(5. JSON文件中的IAP商品),并验证您的amazon.sdktester.json文件中的商品是否显示在此处。

模拟调用

配置好应用和测试工具后,您现在可以模拟对IAP服务的调用。

  1. 使用ADB启动应用。
  2. 浏览到应用中的媒体。
  3. 单击Daily Pass(每日通行证)或Subscribe(订阅)按钮。

调整应用程序内商品

您可能需要根据文本在应用中的显示方式调整“描述”选项卡上的“标题”和描述”字段。

您可以登录开发者控制台,单击应用并前往“应用程序内商品”选项卡,由此调整应用程序内商品中的文本或其他特性。只要您还没有提交应用程序,所有字段都将保持可编辑状态。

重置购买

在测试功能时,您可以通过执行以下操作来重置任何Daily Pass(每日通行证)或Go Premium(高级版)购买:

  1. 前往Settings > Applications(应用程序)> Manage Installed Applications(管理已安装应用)> Amazon App Tester
  2. 选择Clear data(清除数据)以及Clear cache(清除缓存)。

通过收据验证服务实现额外的安全性

当用户购买您媒体的Daily Pass(每日通行证)或订阅时,IAP API会向您的应用返回一张收据,说明交易是否有效。由于您的用户拥有Fire TV设备,因此黑客有可能将传出呼叫重新路由到IAP API并伪造收据。

要验证从IAP API返回的收据是否有效,您可以设置自己的服务,以调用亚马逊的收据验证服务

以下是使用Fire App Builder通过收据验证服务验证收据的一般流程:

  • 您设置自己的服务器(使用任何语言/平台),将收据和附带的密钥发送到收据验证服务,询问收据是否有效。
  • 您的应用向收据验证服务发送一个包含所需属性和共享密钥的请求,以检查收据。所需的值可通过以下路径找到:AmazonInAppPurchaseComponent > res > values > values.xml(AmazonInAppPurchaseComponent > res >值> values.xml)。
  • 验证密钥后,收据验证服务确定收据是否有效,并以答案“正确”或“错误”进行响应。

此工作流程未包含在Fire App Builder中。默认情况下,Fire App Builder只调用一个始终返回有效的虚构服务一次。具体而言,在Fire App Builder中,AReceiptVerifier类(位于AmazonInAppPurchaseComponent文件夹)是一个抽象类,您可以用自己的子类对其进行扩展以调用收据验证服务。

DefaultReceiptVerificationService是Fire App Builder中的一个示例子类,可以扩展AReceiptVerifierDefaultReceiptVerificationService中的validateReceipt方法实现收据验证服务所需的所有参数:

  • context: 应用上下文
  • requestId: 该请求的请求ID
  • sku: 收据的SKU
  • userData: 当前用户的用户数据
  • receipt: 要验证的收据
  • listener: 此请求的侦听器
  • return: 请求ID

但是,validateReceipt实际上并没有调用收据验证服务。相反,此方法只返回成功的状态。

您必须创建自己的子类才能通过实际调用收据验证服务来扩展AReceiptVerifier。(或者,您可以自定义DefaultReceiptVerificationService子类。)

创建子类时,必须通过以下操作在应用的custom.xml文件中提供子类名称:

  1. 前往AmazonInAppPurchaseComponent > res > values(AmazonInAppPurchaseComponent > res >值),然后打开strings.xml文件。
  2. 复制以下receipt_verification_service_iap字符串,然后将其粘贴到您应用的custom.xml文件(位于app(应用)> resources(资源)):

    <string name="receipt_verification_service_iap">com.amazon.inapppurchase.DefaultReceiptVerificationService</string>
    
  3. 在应用的custom.xml文件中,使用子类的完整路径更新字符串的值。默认情况下,已配置DefaultReceiptVerificationService。您可以创建一个新的子类,也可以直接覆盖DefaultReceiptVerificationService类。

有关调用收据验证服务的更多详细信息,请参阅适用于Appstore SDK IAP的收据验证服务

将应用程序内商品提交至生产环境

到目前为止,本文档已经解释了如何在测试环境中配置应用。当您准备好向亚马逊应用商店提交应用时,您还需要提交应用程序内商品。

要提交应用程序内商品,请执行以下操作:

  1. 登录开发者门户,进入主信息页面,然后单击您的应用。
  2. 单击应用中的应用程序内商品选项卡。
  3. 单击提交应用内商品按钮。

提交应用程序内商品后,您将无法再对其进行编辑。如果您需要更改已提交的应用程序内商品,则需要创建应用的新版本,或者创建新的应用并向应用添加新的应用程序内商品。


Last updated: 2024年3月15日