iap

来自于：官方立即使用

setTransactionListener finishTransaction getProducts purchase restoreTransactions setDownloadListener startDownloads pauseDownloads resumeDownloads cancelDownloads

概述

iap模块封装了iOS系统应用内购买代码相关功能。

使用模块之前需要先了解苹果应用内购买，在App Store Connect上面创建好商品，正确填写好银行、税务等相关信息，沙箱测试时需要退出手机上面登录的正式Apple ID账号。

setTransactionListener

设置交易监听

建议在应用启动后就设置交易监听，这样可以处理之前未完成的交易，防止丢单。

注意：设置此监听后，所有的商品交易状态都将会通过此回调返回，而不再通过purchase和restoreTransactions方法的回调返回。如果多个页面都设置了监听，那么将无法保证具体哪个页面的监听有效。

setTransactionListener({params}, callback(ret, err))

params

autoFinishTransaction：

  • 类型：布尔
  • 默认值：true
  • 描述：是否自动完成交易，默认会在回调后自动完成交易。如果设置为false，那么需要在监听回调里面处理完交易后调用finishTransaction方法完成交易（如果有下载内容，需要在下载完成后完成交易）。建议设置为false，在验证完交易后调用finishTransaction完成交易。

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     state:                      //交易状态，详见交易状态常量，数字类型
  3.     productId:                  //商品id，字符串类型
  4.     applicationUsername:      //用户信息，字符串类型
  5.     transactionId:              //交易id，字符串类型
  6.     originalTransactionId:      //原始交易id，只在state为恢复购买时有效，字符串类型
  7.     receipt:                  //交易凭证，经过base64编码，用于验证交易是否合法和有效，避免因越狱破解内购后造成损失，只在state为购买成功时有效，字符串类型
  8.     errorCode:                  //交易失败时的错误码，详见错误码常量，数字类型
  9.     downloads:                  //有下载内容时的下载信息列表
  10.     [{
  11.         transactionId：          //下载内容所属交易id，字符串类型
  12.         contentId:              //下载内容id，字符串类型
  13.         downloadState:          //下载状态，详见下载状态常量，数字类型
  14.         progress：              //下载进度，取值范围0~1，数字类型
  15.         contentLength:          //文件内容大小，数字类型
  16.         timeRemaining:          //下载剩余时间，-1时表示未知，数字类型
  17.         contentVersion:          //下载内容的版本，字符串类型
  18.         contentURL:              //下载成功后文件路径，字符串类型
  19.         errorCode:              //下载失败时的错误码，数字类型
  20.         errorMsg:              //下载失败时的错误描述，字符串类型
  21.     }]
  22. }

示例代码

  1. var iap = api.require('iap');
  2. iap.setTransactionListener(function(ret, err) {
  3.     if (ret) {
  4.         alert(JSON.stringify(ret));
  5.     } else {
  6.         alert(JSON.stringify(err));
  7.     }
  8. });

可用性

iOS系统

可提供的1.0.3及更高版本

finishTransaction

完成指定交易，在完成购买并提供给用户相关功能后应该完成此次交易。

finishTransaction({params})

params

transactionId：

  • 类型：字符串
  • 默认值：无
  • 描述：交易id。

示例代码

  1. var iap = api.require('iap');
  2. iap.finishTransaction({
  3.     transactionId:'xxx'
  4. });

可用性

iOS系统

可提供的1.0.4及更高版本

getProducts

获取有效商品列表

getProducts({params}, callback(ret, err))

params

productIds：

  • 类型：字符串数组
  • 默认值：无
  • 描述：商品id列表

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     invalidProductIds:               //无效的商品id列表，字符串数组
  3.     products:                       //有效商品列表，JSON数组
  4.     [{
  5.         productId:                   //商品id，字符串类型
  6.         title:                       //商品标题，字符串类型
  7.         description:               //商品描述，字符串类型
  8.         price:                       //商品价格，数字类型
  9.         formattedPrice:               //商品格式化后的价格，如￥6.00，字符串类型
  10.         downloadable:               //是否有下载内容，布尔类型
  11.         downloadContentLengths:       //下载内容长度，数字组成的数组
  12.         downloadContentVersion:       //下载内容的版本，字符串类型
  13.     }]
  14. }

err：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     msg: ''    //错误描述
  3. }

示例代码

  1. var iap = api.require('iap');
  2. iap.getProducts({
  3.     productIds: [
  4.         'com.apicloud.iap.free'
  5.     ]
  6. }, function(ret, err) {
  7.     if (ret) {
  8.         alert(JSON.stringify(ret));
  9.     } else {
  10.         alert(JSON.stringify(err));
  11.     }
  12. });

补充说明

获取有效的商品

可用性

iOS系统

可提供的1.0.0及更高版本

purchase

购买商品

purchase({params}, callback(ret, err))

params

productId：

  • 类型：字符串
  • 默认值：无
  • 描述：有效的商品id

applicationUsername：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）用户信息，回调里面将会返回该字段。

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     state:                      //交易状态，详见交易状态常量，数字类型
  3.     productId:                  //商品id，字符串类型
  4.     applicationUsername:      //用户信息，字符串类型
  5.     transactionId:              //交易id，字符串类型
  6.     originalTransactionId:      //原始交易id，只在state为恢复购买时有效，字符串类型
  7.     receipt:                  //交易凭证，经过base64编码，用于验证交易是否合法和有效，避免因越狱破解内购后造成损失，只在state为购买成功时有效，字符串类型
  8.     errorCode:                  //交易失败时的错误码，详见错误码常量，数字类型
  9.     downloads:                  //有下载内容时的下载信息列表
  10.     [{
  11.         transactionId：          //下载内容所属交易id，字符串类型
  12.         contentId:              //下载内容id，字符串类型
  13.         downloadState:          //下载状态，详见下载状态常量，数字类型
  14.         progress：              //下载进度，取值范围0~1，数字类型
  15.         contentLength:          //文件内容大小，数字类型
  16.         timeRemaining:          //下载剩余时间，-1时表示未知，数字类型
  17.         contentVersion:          //下载内容的版本，字符串类型
  18.         contentURL:              //下载成功后文件路径，字符串类型
  19.         errorCode:              //下载失败时的错误码，数字类型
  20.         errorMsg:              //下载失败时的错误描述，字符串类型
  21.     }]
  22. }

err：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     msg: ''         //其它错误，如参数错误、如当前用户不能使用应用内购买等
  3. }

示例代码

  1. var iap = api.require('iap');
  2. iap.purchase({
  3.     productId: 'com.company.app.productid'
  4. }, function(ret, err) {
  5.     if (ret) {
  6.         alert(JSON.stringify(ret));
  7.     } else {
  8.         alert(JSON.stringify(err));
  9.     }
  10. });

补充说明

无

可用性

iOS系统

可提供的1.0.0及更高版本

restoreTransactions

恢复用户以前购买过的所有商品交易

restoreTransactions({params}, callback(ret, err))

params

applicationUsername：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）用户信息，回调里面将会返回该字段。

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     finished:                    //是否所有交易恢复完成，若未完成，则会有以下当前具体交易信息，布尔类型
  3.     transaction:
  4.     {
  5.         state:                    //交易状态，详见交易状态常量，数字类型
  6.         productId:                //商品id，字符串类型
  7.         applicationUsername:    //用户信息，字符串类型
  8.         transactionId:            //交易id，字符串类型
  9.         originalTransactionId:    //原始交易id，只在state为恢复购买时有效，字符串类型
  10.         receipt:                //交易凭证，经过base64编码，用于验证交易是否合法和有效，避免因越狱破解内购后造成损失，只在state为购买成功时有效，字符串类型
  11.         downloads:                //有下载内容时的下载信息列表
  12.         [{
  13.             transactionId：        //下载内容所属交易id，字符串类型
  14.             contentId:            //下载内容id，字符串类型
  15.             downloadState:        //下载状态，详见下载状态常量，数字类型
  16.             progress：            //下载进度，取值范围0~1，数字类型
  17.             contentLength:        //文件内容大小，数字类型
  18.             timeRemaining:        //下载剩余时间，-1时表示未知，数字类型
  19.             contentVersion:        //下载内容的版本，字符串类型
  20.             contentURL:            //下载成功后文件路径，字符串类型
  21.             errorCode:            //下载失败时的错误码，数字类型
  22.             errorMsg:            //下载失败时的错误描述，字符串类型
  23.         }]
  24.     }
  25. }

err：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     errorCode:        //错误码，详见错误码常量
  3. }

示例代码

  1. var iap = api.require('iap');
  2. iap.restoreTransactions(function(ret, err) {
  3.     if (ret) {
  4.         alert(JSON.stringify(ret));
  5.     } else {
  6.         alert(JSON.stringify(err));
  7.     }
  8. });

补充说明

无

可用性

iOS系统

可提供的1.0.0及更高版本

setDownloadListener

设置下载监听，所有的下载进度通过此回调返回

setDownloadListener(callback(ret, err))

callBack(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     downloads:            //下载状态和进度变化的下载列表，JSON数组
  3.     [{
  4.         transactionId：    //下载内容所属交易id，字符串类型
  5.         contentId:        //下载内容id，字符串类型
  6.         downloadState:    //下载状态，详见下载状态常量，数字类型
  7.         progress：        //下载进度，取值范围0~1，数字类型
  8.         contentLength:    //文件内容大小，数字类型
  9.         timeRemaining:    //下载剩余时间，-1时表示未知，数字类型
  10.         contentVersion:    //下载内容的版本，字符串类型
  11.         contentURL:        //下载成功后文件路径，字符串类型
  12.         errorCode:        //下载失败时的错误码，数字类型
  13.         errorMsg:        //下载失败时的错误描述，字符串类型
  14.     }]
  15. }

示例代码

  1. var iap = api.require('iap');
  2. iap.setDownloadListener(function(ret, err) {
  3.     if (ret) {
  4.         alert(JSON.stringify(ret));
  5.     } else {
  6.         alert(JSON.stringify(err));
  7.     }
  8. });

补充说明

无

可用性

iOS系统

可提供的1.0.0及更高版本

startDownloads

开始下载

startDownloads({params})

params

contentIds：

  • 类型：字符串数组
  • 默认值：无
  • 描述：下载内容id组成的数组

示例代码

  1. var iap = api.require('iap');
  2. iap.startDownloads({
  3.     contentIds: [
  4.         '123'
  5.     ]
  6. });

补充说明

无

可用性

iOS系统

可提供的1.0.0及更高版本

pauseDownloads

暂停下载

pauseDownloads({params})

params

contentIds：

  • 类型：字符串数组
  • 默认值：无
  • 描述：下载内容id组成的数组

示例代码

  1. var iap = api.require('iap');
  2. iap.pauseDownloads({
  3.     contentIds: [
  4.         '123'
  5.     ]
  6. });

补充说明

无

可用性

iOS系统

可提供的1.0.0及更高版本

resumeDownloads

恢复下载

resumeDownloads({params})

params

contentIds：

  • 类型：字符串数组
  • 默认值：无
  • 描述：下载内容id组成的数组

示例代码

  1. var iap = api.require('iap');
  2. iap.resumeDownloads({
  3.     contentIds: [
  4.         '123'
  5.     ]
  6. });

补充说明

无

可用性

iOS系统

可提供的1.0.0及更高版本

cancelDownloads

取消下载

cancelDownloads({params})

params

contentIds：

  • 类型：字符串数组
  • 默认值：无
  • 描述：下载内容id组成的数组

示例代码

  1. var iap = api.require('iap');
  2. iap.cancelDownloads({
  3.     contentIds: [
  4.         '123'
  5.     ]
  6. });

补充说明

无

可用性

iOS系统

可提供的1.0.0及更高版本

错误码 下载状态 交易状态

错误码

应用内购买过程中的错误码。数字类型

取值范围：

  • 0 //未知错误
  • 1 //无效请求
  • 2 //用户取消购买
  • 3 //交易无效
  • 4 //设备不允许进行交易
  • 5 //不是有效商品

下载状态

下载状态。数字类型

取值范围：

  • 0 //等待下载
  • 1 //正在下载
  • 2 //暂停下载
  • 3 //下载完成
  • 4 //下载失败
  • 5 //取消下载

交易状态

交易状态。数字类型

取值范围：

  • 0 //已加入交易队列
  • 1 //交易完成
  • 2 //交易失败
  • 3 //恢复购买
  • 4 //交易等待被确认， iOS 8.0及以后有效