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及以后有效