亚马逊应用内购买组件
亚马逊应用内购买组件使用亚马逊的应用内购买 (IAP) API将购买选项集成到您的应用中。
- 可用的购买选项
- 亚马逊应用内购买组件的用户体验
- 应用内购买的注意事项和限制
- 亚马逊应用内购买组件工作流程
- 配置概述
- 步骤1.在开发者门户中创建应用
- 步骤2.创建Daily Pass(每日通行证)消费品型应用程序内商品
- 步骤3.创建订阅型(Go Premium(高级版))应用程序内商品
- 步骤4.下载并推送JSON数据文件
- 步骤5.在您的应用中启用应用内购买组件
- 步骤6.将应用程序内商品映射到您应用中的内容
- 步骤7.自定义按钮文本
- 步骤8.设置App Tester
- 通过收据验证服务实现额外的安全性
- 将应用程序内商品提交至生产环境
可用的购买选项
应用内购买组件在您的应用中提供两种不同的购买选项:
- Daily Pass(每日通行证): 允许用户观看应用中的任何媒体一天(从购买之时起24小时)。这类似于24小时无限制电影租赁。
- Go Premium(高级版): 允许用户支付订阅费,从而可以在订阅期限间观看应用中的任何媒体。在亚马逊开发者控制台中设置应用程序内商品时,您可以定义订阅时间段。
借助应用内购买组件,您不必再为处理与用户的交易而烦恼。用户通过在配置Fire TV时设置的亚马逊账户进行购买。您应用中的所有交易细节都由应用内购买API负责处理。
亚马逊应用内购买组件的用户体验
在应用中实现亚马逊应用内购买组件后,用户会在Content Details(内容详情)屏幕上看到“Daily Pass”(每日通行证)和“Go Premium”(高级版)(而非Watch Now(立即观看)按钮)。
当用户单击“Daily Pass”(每日通行证)或“Go Premium”(高级版)按钮时,系统会提示用户使用其Fire TV账户进行购买。例如,如果用户单击“Go Premium”(高级版),则会出现以下屏幕:
如果用户单击“Daily Pass”(每日通行证),则会出现以下屏幕:
用户使用自己的亚马逊账户通过Fire TV对话框完成交易,该账户是用户在设置Fire TV时输入的账户。当交易完成时,用户会看到以下屏幕:
用户现在可以开始观看内容。
应用内购买的注意事项和限制
请注意有关亚马逊应用内购买组件的以下详细信息:
- 您必须同时为您的媒体提供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(高级版)按钮。但是,如果用户尝试第二次订阅,应用将识别出用户已经是订户,并将对其提供媒体的访问权限。
亚马逊应用内购买组件工作流程
以下步骤描述了亚马逊应用内购买组件的付款工作流程:
- 当应用启动时,应用使用应用内购买API来获取当前登录用户的现有购买情况,并使用最新的收据更新产品。
- 在Content Details(内容详情)屏幕上,用户单击Daily Pass(每日通行证)或Go Premium(高级版)按钮(假设用户尚未购买媒体)。
- 应用调用应用内购买API,与用户进行商品交易。用户通过自己设置好的Fire TV账户选项来完成购买。
- 如果交易成功,应用内购买API会将交易的收据ID返回给应用。
- (可选)为确保收据有效,您可以设置自己的服务,向收据验证服务发送请求并检查收据ID是否有效。
- 如果收据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.在开发者门户中创建应用
- 步骤2.创建Daily Pass(每日通行证)消费品型应用程序内商品
- 步骤3.创建订阅型(Go Premium(高级版))应用程序内商品
- 步骤4.下载并推送JSON数据文件
- 步骤5.在您的应用中启用应用内购买组件
- 步骤6.将应用程序内商品映射到您应用中的内容
- 步骤7.自定义按钮文本
- 步骤8.设置App Tester
步骤1.在开发者门户中创建应用
如果您已经创建了应用,则可以跳过本部分,前往下一个部分。
- 登录开发者门户。
- 单击添加新应用程序,然后在“Choose a Platform”(选择平台)对话框中选择Android。然后单击下一步。
-
填写应用的基本字段:
- 应用标题: 您的应用的名称。
- 应用SKU: 您应用的唯一标识符(例如,
mycalypsomediapp1234
)。SKU的最大长度为150个字符,可包含a-z、A-Z、0-9、下划线、句点和短划线。SKU区分大小写。 - 类别: 选择适合您的应用和媒体的类别。
- 对于客服联系信息,可以选择使用我的默认客服信息或自定义字段。然后单击保存。
步骤2.创建Daily Pass(每日通行证)消费品型应用程序内商品
- 登录开发者门户,进入主信息页面,然后单击您的应用。
- 单击应用中的应用程序内商品选项卡。
-
单击添加消费品按钮(适用于Daily Pass(每日通行证))。
-
为下表中定义的字段输入值:
字段 描述 标题 指代此商品的名称。该标题不会显示给用户。出于方便起见,可键入Daily Pass(每日通行证)。 SKU 您应用的唯一字符串,会成为商品的ID。例如“com.amazon.example.iap.mydailypassitem”。应用使用的SKU必须与您提交到亚马逊应用商店的SKU匹配。与之前(创建应用时)相同的SKU字符要求在这里也适用。 Content delivery(内容交付) 选择No additional file required(无需额外文件),因为要交付的内容是作为应用的一部分加入。 -
单击保存。
注意: 移至下一个选项卡之前,您必须先保存输入前一个选项卡的信息。 -
单击销售国家 (地区) 和标价选项卡并填写下表所述的详细信息。
字段 描述 Are you charging for this consumable/entitlement?(您是否对此消费品/权利收费?) 选择是,我的基本价格为...,则系统将显示为商品设置基本价格和币种的字段。在设置了基本价格后,您可以手动设置其他币种的价格,或让亚马逊应用商店根据汇率和税款为您设置这些价格。有效价格可以是0.00美元,也可以在0.99美元到400美元之间。 您希望此商品何时可用? 指定商品在应用中可供购买的日期(IAP使用PST时区)。如果您将此字段留空,则商品将在获得亚马逊应用商店批准后立即可用。 - 单击保存。
- 单击描述选项卡。
-
填写显示标题和描述字段。
这些字段在用户单击Daily Pass(每日通行证)之后显示在对话框中:
- 单击保存。
- 单击图像选项卡。
- 根据尺寸要求上传两张图像。只有114像素的图像会显示在用户于应用中看到的Daily Pass(每日通行证)对话框中。在上一个屏幕截图(图6)中,图像只是一个橙色正方形。在创建512像素的图像时,出于方便起见,您可上传这个通用图像。
-
单击保存。
警告: 请暂时不要单击提交应用内商品按钮。在提交应用程序内商品之后,将无法编辑或删除它。只有在您完全测试了功能和内容并准备好提交应用后,才能单击此按钮。
步骤3.创建订阅型(Go Premium(高级版))应用程序内商品
- 如果需要,登录开发者门户,进入主信息页面,然后单击您的应用。
- 单击应用中的应用程序内商品选项卡。
- 单击添加订阅按钮(适用于Go Premium(高级版)).(在“Subscriptions are not supported by Amazon Underground”(Amazon Underground不支持订阅)提示出现时,再次单击添加订阅按钮。)
-
为下表中定义的字段输入值:
字段 描述 标题 指代此商品的名称。该标题不会显示给用户。出于方便起见,可键入Go Premium(高级版)。 SKU 您应用的唯一字符串,会成为商品的ID。例如,“com.amazon.example.iap.mygopremiumitem。” 应用使用的SKU必须与您提交到亚马逊应用商店的SKU匹配。与之前(创建应用时)相同的SKU字符要求在这里也适用。 Content delivery(内容交付) 选择No additional file required(无需额外文件),因为要交付的内容是作为应用的一部分加入。 -
单击保存。
注意: 移至下一个选项卡之前,您必须先保存输入前一个选项卡的信息。 -
单击订阅期限选项卡,并按照下表的定义填写字段。
字段 描述 订阅期限 选择您需要的订阅持续时间。订阅期限从购买日期开始。 SKU 输入与此订阅期限对应的SKU(使用与其他SKU字段相同的指南)。例如,“com.amazon.example.calypso.monthly”。此SKU是您在商品详情页面上输入的SKU的子SKU。 免费试用 如果需要,为订阅指定可选的免费试用期。 您是否对此订阅收费? 选择是,我的基本价格为...。则系统将显示为商品设置基本价格和币种的字段。在设置了基本价格后,您可以手动设置其他币种的价格,或让亚马逊应用商店根据汇率和税款为您设置这些价格。有效价格可以是0.00美元,也可以在0.99美元到299美元之间。 您希望此商品何时可用? 指定商品在应用中可供购买的日期(IAP使用PST时区)。如果您将此字段留空,则商品将在获得亚马逊应用商店批准后立即可用。 注意: 忽略“保存并添加订阅期限”按钮。购买组件仅支持一个订阅期限。 - 单击保存。
- 单击描述选项卡。
-
填写显示标题和描述字段。
这些字段在用户单击Go Premium(高级版)之后显示在对话框中:
- 单击保存。
- 单击图像选项卡。
- 开发者控制台需要图像图标,但与Daily Pass(每日通行证)(消费品)不同的是,用户在应用中看到的Go Premium(高级版)对话框中不使用这两个图像中的任一个。出于方便起见,您可以上传这个通用的114像素图像和这个通用的512像素图像。
-
单击保存。
警告: 请暂时不要单击提交应用内商品按钮。在提交应用程序内商品之后,将无法编辑或删除它。只有在您完全测试了功能和内容并准备好提交应用后,才能单击此按钮。
步骤4.下载并推送JSON数据文件
配置Daily Pass(每日通行证)和Go Premium(高级版)应用程序内商品后,您将下载一个JSON文件,其中包含有关应用程序内商品的详细信息。
- 如果需要,登录开发者门户,进入主信息页面,然后单击您的应用。
- 单击应用中的应用程序内商品选项卡。
-
单击JSON数据文件按钮下载包含您的应用程序内商品详情的JSON文件。
- 在您的终端中,
cd
到包含此文件的目录。 -
使用以下命令将JSON文件推送到您的Fire TV设备:
$ adb push amazon.sdktester.json /mnt/sdcard/
响应将显示以下内容:
[100%] /mnt/sdcard/amazon.sdktester.json
步骤5.在您的应用中启用应用内购买组件
现在,您已经在开发者控制台中创建了应用程序内商品,您需要在应用程序中启用IAP组件。
- 将亚马逊应用内购买组件加载到您的应用中。有关如何将组件加载到应用中的详细信息,请参阅加载组件。
- 在Android Studio中,展开ContentBrowser文件夹,然后转到res > values(res >值),然后打开custom.xml文件。
-
复制以下字符串:
<bool name="is_iap_disabled">true</bool>
(忽略
override_all_contents_subscription_flag
字段。) - 在您的app文件夹中,打开custom.xml文件(位于res > values(res >值)中)。
-
粘贴之前复制的字符串并将该值更改为
false
。务必将此字符串粘贴到resources
标签中:<bool name="is_iap_disabled">false</bool>
提示: 请注意,这是一个双重否定,因此在本例中,false
实际上是在您的应用中启用IAP。应用的custom.xml中的值将覆盖组件中的任何值。
步骤6.将应用程序内商品映射到您应用中的内容
-
在Android Studio中,展开PurchaseInterface文件夹,然后转到assets(资产)。然后打开skuslist.json文件。
-
对于“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(高级版)商品为订阅商品。
-
对于“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”(高级版)文本。
要自定义文本,请执行以下操作:
- 前往ContentBrowser > res > values(ContentBrowser > res >值),然后打开strings.xml文件。
-
复制以下字符串并将其粘贴到应用的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>
- 根据需要自定义字符串值。
步骤8.设置App Tester
您已经设置了应用程序内商品并配置了应用,那么是时候测试一下集成了,由此看看IAP如何与您的媒体交互。
要在应用中测试应用程序内商品(无需实际购买,并且可以在将应用提交到亚马逊应用商店之前进行),您需要使用IAP App Tester。App Tester使用沙盒服务器模拟对应用内购买API的调用。App Tester会拦截对应用内购买API的传出调用,并返回有效的收据,对交易授权。有关更多详细信息,请参阅安装并配置App Tester。
要设置App Tester,请执行以下操作:
-
使用电脑的浏览器,前往App Tester from the AppStore(来自亚马逊应用商店的App Tester),获取应用(免费),然后将其交付到您的设备。
要将此应用交付到您的设备,您必须使用与设置Fire TV时相同的凭证登录亚马逊。使用“Deliver to”(交付到)选项将应用交付到您的设备:
- 在Fire TV上,前往Settings(设置)> My Account(我的账户)> Sync Amazon Content(同步亚马逊内容),将购买的商品与设备同步。
- 在Fire TV主页屏幕上,前往Apps(应用),然后选择Your Apps Library(您的应用库)。
- 选择 Amazon App Tester应用,然后从云下载并安装该应用。
- 下载完成后启动应用。
-
单击应用内购买API部分。
- 选择5.IAP Items in JSON File(5. JSON文件中的IAP商品),并验证您的amazon.sdktester.json文件中的商品是否显示在此处。
模拟调用
配置好应用和测试工具后,您现在可以模拟对IAP服务的调用。
- 使用ADB启动应用。
- 浏览到应用中的媒体。
- 单击Daily Pass(每日通行证)或Subscribe(订阅)按钮。
调整应用程序内商品
您可能需要根据文本在应用中的显示方式调整“描述”选项卡上的“标题”和描述”字段。
您可以登录开发者控制台,单击应用并前往“应用程序内商品”选项卡,由此调整应用程序内商品中的文本或其他特性。只要您还没有提交应用程序,所有字段都将保持可编辑状态。
重置购买
在测试功能时,您可以通过执行以下操作来重置任何Daily Pass(每日通行证)或Go Premium(高级版)购买:
- 前往Settings > Applications(应用程序)> Manage Installed Applications(管理已安装应用)> Amazon App Tester。
- 选择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中的一个示例子类,可以扩展AReceiptVerifier
。DefaultReceiptVerificationService
中的validateReceipt
方法实现收据验证服务所需的所有参数:
context
: 应用上下文requestId
: 该请求的请求IDsku
: 收据的SKUuserData
: 当前用户的用户数据receipt
: 要验证的收据listener
: 此请求的侦听器return
: 请求ID
但是,validateReceipt
实际上并没有调用收据验证服务。相反,此方法只返回成功的状态。
您必须创建自己的子类才能通过实际调用收据验证服务来扩展AReceiptVerifier
。(或者,您可以自定义DefaultReceiptVerificationService
子类。)
创建子类时,必须通过以下操作在应用的custom.xml文件中提供子类名称:
- 前往AmazonInAppPurchaseComponent > res > values(AmazonInAppPurchaseComponent > res >值),然后打开strings.xml文件。
-
复制以下
receipt_verification_service_iap
字符串,然后将其粘贴到您应用的custom.xml文件(位于app(应用)> resources(资源)):<string name="receipt_verification_service_iap">com.amazon.inapppurchase.DefaultReceiptVerificationService</string>
- 在应用的custom.xml文件中,使用子类的完整路径更新字符串的值。默认情况下,已配置
DefaultReceiptVerificationService
。您可以创建一个新的子类,也可以直接覆盖DefaultReceiptVerificationService
类。
有关调用收据验证服务的更多详细信息,请参阅适用于Appstore SDK IAP的收据验证服务。
将应用程序内商品提交至生产环境
到目前为止,本文档已经解释了如何在测试环境中配置应用。当您准备好向亚马逊应用商店提交应用时,您还需要提交应用程序内商品。
要提交应用程序内商品,请执行以下操作:
- 登录开发者门户,进入主信息页面,然后单击您的应用。
- 单击应用中的应用程序内商品选项卡。
- 单击提交应用内商品按钮。
提交应用程序内商品后,您将无法再对其进行编辑。如果您需要更改已提交的应用程序内商品,则需要创建应用的新版本,或者创建新的应用并向应用添加新的应用程序内商品。
Last updated: 2024年3月15日