华为HarmonyOS应用内支付服务 -- 2 权限发放

场景介绍

应用在收到用户购买消耗型/非消耗型商品成功的结果后，需要发放相关权益，并在权益发放后，向IAP Kit确认发货，完成购买流程，具体实现请参见接入购买。此外，还需要补充如下处理，确保权益发放：

• 若应用提供消耗型商品，需要按照确保权益发放处理消耗型商品的权益发放。
• 若应用提供非消耗型商品，且为单机应用，则需要按照单机应用权益发放（非消耗型商品）处理非消耗型商品的权益发放。其他场景需要按照确保权益发放处理非消耗型商品的权益发放。

确保权益发放

用户购买商品后，开发者需要及时发放相关权益。但实际应用场景中，若出现异常（网络错误、进程被中止等）将导致应用无法知道用户实际是否支付成功，从而无法及时发放权益，即出现掉单情况。为了确保权益发放，需要在以下场景检查用户是否存在已购未发货的商品：

1. 应用启动时。
2. 购买请求（createPurchase）返回iap.IAPErrorCode.PRODUCT_OWNED或iap.IAPErrorCode.SYSTEM_ERROR时。

如果存在已购未发货商品，则发放相关权益，然后向IAP Kit确认发货，完成购买。

业务流程

1. 应用客户端向IAP Kit发起queryPurchases请求，查询用户已购买但未确认发货的订单信息。
2. IAP Kit返回PurchaseData列表。PurchaseData为JWS格式的字符串，承载了相关的订单信息。
3. 应用客户端向应用服务器上报PurchaseData列表。
4. 应用服务器需对每个PurchaseData.jwsPurchaseOrder进行解码验签，验证成功可得到对应的PurchaseOrderPayload的JSON字符串。
5. 处理权益发放。检查当前PurchaseOrderPayload是否已发放权益，未发放则发放相关权益，并记录对应的订单信息（PurchaseOrderPayload）。
6. 应用客户端向应用服务器查询订单的发货状态。
7. 应用服务器返回对应的发货状态以及订单信息（PurchaseOrderPayload）。
8. 发货成功后应用客户端向IAP Kit发送finishPurchase请求，以此通知IAP服务器更新商品的发货状态，完成购买流程。应用成功执行finishPurchase之后，IAP服务器会将相应商品标记为已发货状态。对于消耗型商品，IAP服务器会将相应商品重新设置为可购买状态，用户即可再次购买该商品。此步骤也可放到应用服务器处理。应用服务器可通过请求服务端订单确认发货接口来确认发货，完成购买流程。

   注意

   确保在发货成功之后再执行此步骤，否则可能导致IAP服务器已经确认发货但是应用没有发货的问题。

开发步骤

1. 应用客户端向IAP Kit发起queryPurchases请求，获取用户已购买但未确认发货的订单信息。

   在请求参数QueryPurchasesParameter中指定对应的productType，同时指定queryType为iap.PurchaseQueryType.UNFINISHED。当接口请求成功时，IAP Kit将返回一个QueryPurchaseResult对象，该对象包含承载了订单信息的PurchaseData的列表。

2. 对purchaseData.jwsPurchaseOrder进行解码验签。建议应用客户端将purchaseData发送至应用服务器，在应用服务器执行此操作。
3. 验证成功可得到对应的PurchaseOrderPayload的JSON字符串，如果PurchaseOrderPayload.purchaseOrderRevocationReasonCode为空，则代表购买成功，需要进行补发货处理。

   建议先检查此笔订单权益的发放状态，未发放则发放权益，成功后记录PurchaseOrderPayload等信息，用于后续检查权益发放状态。

4. 发货成功后，应用需调用finishPurchase接口确认发货，以此通知IAP服务器更新商品的发货状态，完成购买流程。

   发起请求时，需在请求参数FinishPurchaseParameter中携带PurchaseOrderPayload中的productType、purchaseToken、purchaseOrderId。

   请求成功后，IAP服务器会将相应商品标记为已发货状态。对于消耗型商品，IAP服务器会将相应商品重新设置为可购买状态，用户即可再次购买该商品。对于非消耗型商品，用户购买后永久拥有，无法再次购买该商品。

   1. import { iap } from '@kit.IAPKit';
   2. import { common } from '@kit.AbilityKit';
   3. import { BusinessError } from '@kit.BasicServicesKit';
   4. // JWTUtil为自定义类，可参见示例代码
   5. import { JWTUtil } from '../common/JWTUtil';
   7. queryPurchases() {
   8. const param: iap.QueryPurchasesParameter = {
   9. productType: iap.ProductType.CONSUMABLE,
   10. queryType: iap.PurchaseQueryType.UNFINISHED
   11. };
   12. const context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
   13. iap.queryPurchases(context, param).then((res: iap.QueryPurchaseResult) => {
   14. console.info('Succeeded in querying purchases.');
   15. const purchaseDataList: string[] = res.purchaseDataList;
   16. if (purchaseDataList === undefined || purchaseDataList.length <= 0) {
   17. return;
   18. }
   19. for (let i = 0; i < purchaseDataList.length; i++) {
   20. const jwsPurchaseOrder: string = JSON.parse(purchaseDataList[i]).jwsPurchaseOrder;
   21. if (!jwsPurchaseOrder) {
   22. continue;
   23. }
   24. const purchaseStr = JWTUtil.decodeJwtObj(jwsPurchaseOrder);
   25. // 需自定义PurchaseOrderPayload类，包含的信息请参见PurchaseOrderPayload
   26. const purchaseOrderPayload = JSON.parse(purchaseStr) as PurchaseOrderPayload;
   27. // 处理发货
   28. // ...
   29. // 发货成功后向IAP Kit发送finishPurchase请求，确认发货，完成购买
   30. this.finishPurchase(purchaseOrderPayload);
   31. }
   32. }).catch((err: BusinessError) => {
   33. // 请求失败
   34. console.error(`Failed to query purchases. Code is ${err.code}, message is ${err.message}`);
   35. });
   36. }
   38. finishPurchase(purchaseOrder: PurchaseOrderPayload) {
   39. const finishPurchaseParam: iap.FinishPurchaseParameter = {
   40. productType: purchaseOrder.productType,
   41. purchaseToken: purchaseOrder.purchaseToken,
   42. purchaseOrderId: purchaseOrder.purchaseOrderId
   43. };
   44. const context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
   45. iap.finishPurchase(context, finishPurchaseParam).then(() => {
   46. // 请求成功
   47. console.info('Succeeded in finishing purchase.');
   48. }).catch((err: BusinessError) => {
   49. // 请求失败
   50. console.error(`Failed to query purchases. Code is ${err.code}, message is ${err.message}`);
   51. });
   52. }

单机应用权益发放（非消耗型商品）

用户在购买非消耗型商品后，将永久拥有该商品的权益。应用需要在用户购买非消耗型商品后，始终为其发放相关权益。

请在以下场景获取用户已购非消耗型商品的信息，并发放相关权益。

1. 应用启动时。
2. 购买请求（createPurchase）返回iap.IAPErrorCode.PRODUCT_OWNED或iap.IAPErrorCode.SYSTEM_ERROR时。

开发步骤

1. 应用客户端向IAP Kit发起queryPurchases请求，获取用户已购非消耗型商品的订单状态信息。

   在请求参数QueryPurchasesParameter中指定productType为iap.ProductType.NONCONSUMABLE，同时指定queryType为iap.PurchaseQueryType.CURRENT_ENTITLEMENT。当接口请求成功时，IAP Kit将返回一个QueryPurchaseResult对象，该对象包含承载了订单信息的PurchaseData的列表。

2. 对每个PurchaseData.jwsPurchaseOrder进行解码验签。
3. 验证成功可得到对应的PurchaseOrderPayload的JSON字符串，需要发放相关权益。
4. 发放权益后，应用需调用finishPurchase接口确认发货，以此通知IAP服务器更新商品的发货状态，完成购买流程。

   发起请求时，需在请求参数FinishPurchaseParameter中携带PurchaseOrderPayload中的productType、purchaseToken、purchaseOrderId。

   请求成功后，IAP服务器会将相应商品标记为已发货。对于非消耗型商品，用户购买后永久拥有，无法再次购买该商品。

1. import { iap } from '@kit.IAPKit';
2. import { common } from '@kit.AbilityKit';
3. import { BusinessError } from '@kit.BasicServicesKit';
4. // JWTUtil为自定义类，可参见示例代码
5. import { JWTUtil } from '../common/JWTUtil';
7. queryPurchases() {
8. const param: iap.QueryPurchasesParameter = {
9. productType: iap.ProductType.NONCONSUMABLE,
10. queryType: iap.PurchaseQueryType.CURRENT_ENTITLEMENT
11. };
12. const context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
13. iap.queryPurchases(context, param).then((res: iap.QueryPurchaseResult) => {
14. console.info('Succeeded in querying purchases.');
15. const purchaseDataList: string[] = res.purchaseDataList;
16. if (purchaseDataList === undefined || purchaseDataList.length <= 0) {
17. return;
18. }
19. for (let i = 0; i < purchaseDataList.length; i++) {
20. const jwsPurchaseOrder: string = JSON.parse(purchaseDataList[i]).jwsPurchaseOrder;
21. if (!jwsPurchaseOrder) {
22. continue;
23. }
24. // 对jwsPurchaseOrder进行解码验签
25. const purchaseStr = JWTUtil.decodeJwtObj(jwsPurchaseOrder);
26. // 需自定义PurchaseOrderPayload类，包含的信息请参见PurchaseOrderPayload
27. const purchaseOrderPayload = JSON.parse(purchaseStr) as PurchaseOrderPayload;
28. // 处理权益发放
29. // ...
30. // 发放权益后向IAP Kit发送finishPurchase请求，确认发货，完成购买
31. if (purchaseOrderPayload && purchaseOrderPayload.finishStatus !== '1') {
32. this.finishPurchase(purchaseOrderPayload);
33. }
34. }
35. }).catch((err: BusinessError) => {
36. // 请求失败
37. console.error(`Failed to query purchases. Code is ${err.code}, message is ${err.message}`);
38. });
39. }
41. finishPurchase(purchaseOrder: PurchaseOrderPayload) {
42. const finishPurchaseParam: iap.FinishPurchaseParameter = {
43. productType: purchaseOrder.productType,
44. purchaseToken: purchaseOrder.purchaseToken,
45. purchaseOrderId: purchaseOrder.purchaseOrderId
46. };
47. const context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
48. iap.finishPurchase(context, finishPurchaseParam).then(() => {
49. // 请求成功
50. console.info('Succeeded in finishing purchase.');
51. }).catch((err: BusinessError) => {
52. // 请求失败
53. console.error(`Failed to query purchases. Code is ${err.code}, message is ${err.message}`);
54. });
55. }