MMSDK310开发文档.docx

1、MMSDK310开发文档中国移动应用商场应用内计费开发指南V 3.1.02014-11本文档主要描述了中国移动应用商场(MM)的应用内计费基本机制，以及指导开发者如何在应用中使用应用内计费功能。文档中提供了开发者需要做哪些准备、如何获取所需资源及如何使用SDK等的指引，同时也提供了相关的范例供开发者学习使用。目 录1.1 开发应用 31.1.1 准备开发环境 31.1.2 下载和导入SDK 31.2 开发者开发应用注意事项 52 应用内计费SDK使用手册 62.1 SDK组成和接口说明 62.1.1 Purchase API说明 62.1.2 OnPurchaseListener 82.1.3

2、 OnPurchaseListener中返回数据说明 92.1.4 AndroidManifest 设置（开发者必须要注意的地方） 102.2 SDK调用时序 142.2.1 构造及初始化 142.2.2 查询 152.2.3 订购 152.3 示例代码 162.3.1 SDK初始化 182.3.2 SDK订购，查询,退订接口的调用 202.3.3 获取渠道ID 212.4 应用混淆 231.1 开发应用 1.1.1 准备开发环境在使用应用内计费接口之前，请确认Eclipse、JDK、Android SDK已经安装，并正常使用。如果尚未安装，请参考以下资源，安装过程不再赘述。Eclipse:

3、http:/www.eclipse.org/downloads/JDK: Android SDK: 1.1.2 下载和导入SDK SDK以jar文件的形式提供给开发者在程序中使用，同时提供HTML格式的API文档供查阅相关类、方法、常量等说明。以下内容将说明如何在Eclipse中，将jar文件加入到应用工程中去。1. 将mmbilling.3.1.0.jar文件拷贝到应用工程的libs目录下，如没有该目录，可新建；2. 在Project Explorer中右击鼠标，从弹出的菜单中，选中“Properties”;3. 在Properties窗口的左侧菜单项中，点击“Java Build Path

4、”，并在右侧选中“Libraries”;4. 点击“Add JARs”按钮，在弹出窗口中，选中jar文件，如下图1所示。 SDK可以在创建应用页面进行下载图表 1 添加jar文件最后，检查Referenced Libraries中是否可以看到jar文件，如下图2所示。如果可以，则表示配置成功，否则，请检查上述步骤是否执行成功。图表 2 检查5. 将libidentifyApp.so,libcasdkjni.so,libcmcc_haze.so和libcmcc_rusteze.so复制到libsarmeabi目录下1.2 开发者开发应用注意事项1) 为保证自身敏感数据(APPID、APPKEY、

5、PAYCODE)的安全性，请尽量采用加密等手段保存，避免以常量字符串形式出现于源码。2) 为保护自身数据和付费点，开发完成后，建议对APK做混淆处理。3) 应用中不能同时发起两起或者以上的订购操作，比如不能同时启动两个查询订单的线程。4) 包月和单次计费的业务，可以缓存授权结果在本地，以避免过多网络的交互。但缓存的授权可能会有不同步的情况，应用可根据实际业务情况决定是否启用本地缓存授权。也可以在运行过程中，清除缓存授权(clearCache()。5) 可批量购买的计费点，在两次订购之间，目前有时间限制(目前定义30秒钟)6) 可批量购买的计费点，一次订购数量不能超过10个。7) 应用升级，开发

6、如果需要升级目前已投入商用的APP，需要重新上传后，用户通过MM商城或者其他与移动有关渠道升级。如果采用自升级，可能会因为APP数据与移动服务器中数据不一致，导致APP中无法正常发起交易业务。8) 中国移动部分省份已经开始销售147号段的SIM卡，该号段同样可以使用IAP进行计费。请应用开发者注意判断此号段的SIM卡，以免造成不必要的麻烦。9) 如果应用中同时有armeabi和armeabi-v7a等多个文件夹，请将计费需要的so库（libidentifyApp.so,libcasdkjni.so,libcmcc_haze.so和libcmcc_rusteze.so）同时添加到这两个文件夹中。

7、如果存在x86文件夹，操作方式同上。10) 升级SDK时，是否能仅升级jar？不行，sdk包括jar和so，在使用新版本时，请同事替换这4个so库。2 应用内计费SDK使用手册 2.1 SDK组成和接口说明 SDK公开的接口包括：2.1.1 Purchase API说明Purchase对象是SDK提供给开发者发起订购，查询的接口。开发者在实例化该对象后，调用其中的函数可以处理相应的业务。1) 构造实例：Purchase对象的创建使用了单例模式，不需要重复创建：purchase = Purchase.getInstance();2) 各参数设置：purchase.setAppInfo(appid

8、, appkey); / 设置计费应用ID和Key (必须)purchase.setTimeout(10000, 10000); / 设置超时时间(可选)，可不设置，缺省都是10s3) 初始化：Init()，初始化函数。此函数主要实现用户身份数字证书申请。建议开发者在APP初始化中调用，这样可减少用户在订购，查询业务中的等待时间。purchase.init(context, listener); /初始化，传入监听器调用后，请等待onInitFinish()完成后，再发起其他业务请求，否则其他业务不会处理。4) 订购：调用Purchase对象中的order函数，一共有4种，传入相应的参数： p

9、ayCode，计费点 orderCount,订购数量。（包月、约定租期和不可重复订购计费点只能传入1，可重复订购计费点可以传入10以下数值） nextCycle, 对于租赁类业务，可以预订下一期租赁周期。 Listener，本参数是开发实现OnPurchaseListener对象的实例，主要用于监听各个业务的结果。 data，本参数是可透传到开发者服务器的自定义数据，长度：弱联网计费点16位以内，强联网计费点64位以内。必须数字和字母。/ 订购一个商品String tradeid = purchase.order(context, paycode, listener); / 订购5个商品Str

10、ing tradeid = purchase.order(context, paycode, 5, listener); / 租赁当前周期String tradeid = purchase.order(context, MONTH_PAYCODE, 1, falsetrue, listener); / 调用购买接口并传入自定义数据String tradeid = purchase.order(context, paycode, 1, data, true, listener);订购返回的tradeid代表当次交易ID，可以在查询接口中传入该交易ID查询交易有无成功订购具体的结果在OnPurch

11、aseListener中的onBillingFinish()中获得。如果未能初始化成功，或者之前未调用init()，那么第一次订购，会申请用户身份数字证书，导致第一次订购时间略长。 5) 查询:调用Purchase对象中的query函数，传入相应参数： payCode，计费点 TradeID, 调用order()接口返回的交易ID，用于查询交易是否成功 Listener，本参数是开发实现OnPurchaseListener对象的实例，主要用于监听各个业务的结果。/ 查询单次或者租赁类商品是否订购成功purchase.query(context, paycode, listener);/ 带交易

12、ID查询重复类商品是否交易成功purchase.query(context, paycode, tradeid, listener);6) 退订：调用Purchase对象中的unsubscribe函数，传入相应参数： payCode，计费点 Listener，本参数是开发实现OnPurchaseListener对象的实例，主要用于监听各个业务的结果。/ 退订包月业务purchase.unsubscribe(context, Paycode, Listener);注意：目前只有包月业务允许退订。其他类型业务均不允许退订。2.1.2 OnPurchaseListener应用内计费各种操作(查询，订

13、购)监听器。开发者通过实现该接口中各个接口来监听各种业务操作的状态:/ 初始化返回接口void onInitFinish(final int returnCode)/ 查询返回接口void onQueryFinish(final int returnCode, final HashMap returnObject)/ 订购返回接口:void onBillingFinish(final int returnCode, final HashMap returnObject)/退订返回接口：public void onUnsubscribeFinish(final int returnCode) R

14、eturncode的定义在PurchaseCode类中，具体含义可以通过getDescription()获取。2.1.3 OnPurchaseListener中返回数据说明 正如前面所描述的一样，初始化，查询，订购接口的返回值在OnPurchaseListenr中得到。 returnObject中定义的数据主要有几种：/ 订单号public final static String ORDERID = OrderId;/ 计费点代码public final static String PAYCODE = Paycode;/ 租赁剩余时间public final static String LEF

15、TDAY = LeftDay;/ 交易IDpublic final static String TRADEID = TradeID;/订购类型public final static String ORDERTYPE = OrderType; 上面这些值包含在onXXFinish中参数Hashmap中。各个接口返回的数据不一样。 上面这些值所代表的意义如下： OrderId，表示此次订单，mm平台形成的订单流水号 Paycode，表示此次交易的商品id LeftDay，表示此次交易商品的有效期。TradeID，表示此次交易的交易ID，供查询用。OrderType，表示此次交易的类型。如果返回0，

16、则表示是生成测试订单；如果返回1，则表示生成正式订单。1）初始化接口 初始化接口不返回任何数据。2）订购接口 订购接口在订购成功后，会返回上面5个值。如果订购失败，则不返回上面任何值。3）查询接口 查询接口在查询成功后，返回上面的OrderId，Paycode ,LeftDay这三个值。失败则不返回任何值。2.1.4 AndroidManifest 设置（开发者必须要注意的地方）此版本需要开发者在AndroidManifest.xml中增加iap声明。1) 打开应用的AndroidManifest.xml文件，增加权限和内部Service 与 Activity声明 - 2) Action声明（

17、重点）在上述声明中，需要注意声明BillingLayoutActivity中的Action 请将action声明为您程序的包名.com.mmiap.activity在上述声明中，需要注意声明PurchaseService中的Action 其中一个intent-filter是： 请将action声明为您程序的包名.purchaseservice.BIND3) 增加权限声明 以确保可以正常读取手机的IMSI/IMEI，读取和网络访问。2.2 SDK调用时序2.2.1 构造及初始化注意：1 构造函数中的needCache参数，是用于指定是否缓存授权文件。如果授权文件缓存在本地，那么之后的鉴权将会首先在本地进行，减少不必要的网络交互。建议对于无时间限制的一次性计费点，如关卡，缓存授权文件。而对于租赁类的计费点，建议不缓存，这样可以在后台获取精确的状态。