Android SDK 接入指南
目前 Ping++ 的 Android SDK 支持的渠道包含：支付宝 App 支付（alipay）、跨境支付宝 App 支付（cb_alipay）、微信 App 支付（wx）、跨境微信 App
支付（cb_wx）、银联 App 支付（upacp）、招行一网通（cmb_wallet）、QQ
钱包支付（qpay）、百度钱包（bfb_wap）、易宝支付（yeepay_wap）、京东支付（jdpay_wap）、建行 App 支付（ccb_pay）。具体可参考 API文档
。
注：
- 【Ping++ 对象】包含：
Charge、Order、Recharge。 - 当仅使用名称包含
_wap的渠道时，均需要使用webview加载，并且不需要导入第三方渠道的 SDK 库包，只需导入 Ping++ SDK 即可。 - 此 SDK 要求 Android 4.1 及以上版本，且请使用 Java 8 及以上版本。
- lib 目录包含的 Library Project，你可以直接作为依赖库，导入到你的项目。
快速体验
Android Studio
Ping++ SDK 为开发者提供了 Demo 程序，可以快速体验Android SDK接入流程。下载 Android SDK 之后将整个 pingpp-android 目录导入到你的项目中，即可运行该 Demo 。
快速集成
导入 Ping++ SDK
支持在线导入和下载 SDK 导入两种方式，后者可以在 Github 下载 Android SDK ，以下我们提供针对 Android Studio 和 Eclipse ADT 两种工具的导入方式。
一、在线导入方式
① Gradle 导入方式
- 在项目中的 build.gradle 中添加 bintray 仓库地址
allprojects { repositories { // ...其他仓库地址... jcenter() // 添加下面的 bintray 仓库地址 maven { url "https://dl.bintray.com/pingxx/maven" } }}
- 在 module 中 的 build.gradle 中设置
dependencies { implementation 'com.pingxx:pingpp-android:2.2.2' // (Ping++ 标准版 SDK) 必须添加 implementation 'com.tencent.mm.opensdk:wechat-sdk-android-without-mta:+' // 使用微信支付时添加,具体版本参考微信官方文档 implementation 'com.pingxx:pingpp-android-alipay:2.2.0' // 使用支付宝时添加 implementation 'com.pingxx:pingpp-android-upacp:2.2.0' // 使用银联支付时添加 implementation 'com.pingxx:pingpp-qpay:2.1.19' // 使用QQ钱包时添加 implementation 'com.pingxx:pingpp-cmbwallet:2.1.19' // 使用招行一网通时添加 implementation 'com.pingxx:pingpp-ccbpay:2.1.19' // 使用建行支付时添加 implementation 'com.pingxx:pingpp-android-cmpay:2.2.2' // 使用和包支付时添加}
② Maven 导入方式
<dependency> <groupId>com.pingxx</groupId> <artifactId>pingpp-core</artifactId> <!--请将 VERSION 换成 SDK 对应的版本号--> <version>VERSION</version> <type>pom</type></dependency>
二、下载 SDK 导入
在 lib 目录中包含 pingpp 资源，其中包含支付所需的 jar 包和资源包。
pingpp
- Ping++ 依赖包：
libpingpp-x.x.x、res资源文件和libpingpp.so文件(必须依赖的) - 微信依赖包：
wechat-sdk-android-without-mta.jar - 支付宝依赖包：
alipaySdkxxxxxxxx.jar - 银联支付依赖包：
UPPayAssistEx.jar、UPPayPluginExPro.jar、libentryexpro.so、libuptsmaddon.so和assets目录下data.bin文件 - QQ钱包依赖包：
mqqopenpay.jar - 招行一网通(混淆加密方式可不配置相关的参数，非混淆加密方式需配置)：
cmbkeyboard.jar和res目录下cmb_开头的资源文件
权限声明
<!-- 注：有些权限是需要动态注册的，如 READ_PHONE_STATE 权限 --><!-- 通用权限 --><uses-permission android:name="android.permission.INTERNET"/><uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/><uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/><uses-permission android:name="android.permission.READ_PHONE_STATE"/><uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/><!-- 银联需要的权限 --><uses-permission android:name="android.permission.NFC"/>
开始接入
你的 APP 内的渠道选择页面和支付完成页面（布局、样式等）由你自行实现，你仅需要将支付凭证传给 Ping++ Client SDK，由 Ping++ Client SDK 完成唤起支付页面的功能。
1、注册 activity
<!-- Ping++ SDK --><activity android:name="com.pingplusplus.android.PaymentActivity" android:configChanges="orientation|keyboardHidden|navigation|screenSize" android:launchMode="singleTop" android:theme="@android:style/Theme.Translucent.NoTitleBar" > <!-- 不使用QQ钱包,可删除此部分代码 --> <!-- scheme 填写规则建议：qwallet + QQ 钱包中的 app_id --> <intent-filter> <action android:name="android.intent.action.VIEW"/> <category android:name="android.intent.category.BROWSABLE"/> <category android:name="android.intent.category.DEFAULT"/> <data android:scheme="qwalletXXXXXXXX"/> </intent-filter> </activity> <!-- 微信支付 --><!-- 1.需要将以下"替换成自己 APK 的包名"换成在微信平台上注册填写的包名 --><!-- 2.WxPayEntryActivity 这个类在 SDK 内部实现，开发者不需要额外实现该类 --><activity-alias android:name="替换成自己APK的包名.wxapi.WXPayEntryActivity" android:exported="true" android:targetActivity="com.pingplusplus.android.PaymentActivity" /> <!-- 招行一网通（非混淆加密方式） --><service android:name="cmb.pb.cmbsafe.CmbService" android:exported="false"/><activity android:name="cmb.pb.ui.PBKeyboardActivity" android:theme="@style/CmbDialogStyleBottom" /> <!-- 招行一网通 App 即招商银行（格式：`<SCHEME>://pingppcmbwallet`，其中 `<SCHEME>` 是你自定义的 `URL Schemes`） --><intent-filter> <action android:name="android.intent.action.VIEW"/> <category android:name="android.intent.category.BROWSABLE"/> <category android:name="android.intent.category.DEFAULT"/> <data android:scheme="自定义 URL Scheme"/> <data android:host="pingppcmbwallet"/></intent-filter><!-- 将以上代码添加到 Ping++ SDK 注册的 Activity，如： --><activity android:name="com.pingplusplus.android.PaymentActivity" android:configChanges="orientation|keyboardHidden|navigation|screenSize" android:launchMode="singleTask" android:theme="@android:style/Theme.Translucent.NoTitleBar" > <intent-filter> <action android:name="android.intent.action.VIEW"/> <category android:name="android.intent.category.BROWSABLE"/> <category android:name="android.intent.category.DEFAULT"/> <data android:scheme="自定义 URL Scheme"/> <data android:host="pingppcmbwallet"/> </intent-filter> </activity> <!-- 建行支付需注册 (自定义 action-name 保持与服务端的 third_app_info 一致） --><activity android:name="com.ccb.ccbnetpay.activity.appresult.ResultActivity" android:configChanges="orientation|keyboardHidden|screenSize" android:screenOrientation="portrait"> <intent-filter> <action android:name="自定义 action-name"/> <category android:name="android.intent.category.DEFAULT"/> </intent-filter></activity> <activity android:name="com.ccb.ccbnetpay.activity.CcbUnionPayActivity" android:configChanges="orientation|keyboardHidden|screenSize" android:screenOrientation="portrait"/> <activity android:name="com.ccb.ccbnetpay.activity.CcbH5PayActivity" android:configChanges="orientation|keyboardHidden|screenSize" android:screenOrientation="portrait"/>
2、获得 Charge / Order / Recharge 对象
Charge / Order / Recharge 对象是一个包含支付信息的 JSON 对象，是 Ping++ SDK 发起支付的必要参数。该参数需要请求用户服务器获得，服务端生成 Charge / Order / Recharge 的方式参考 服务端接入简介 ，SDK 中的 Demo 里面提供了如何获取 Ping++ 对象的实例方法，供用户参考。
3、调起支付
因为 Ping++ 已经封装好了相应的调用方法，所以只需要调用支付方法即可调起支付控件： (注：该调用方法需要在主线程(UI线程)完成)
//参数一：Activity 当前调起支付的Activity//参数二：data 获取到的 Charge/Order/Recharge 的 JSON 字符串Pingpp.createPayment(YourActivity.this, data);
4、获取支付结果
从 Activity 的 onActivityResult 方法中获得支付结果。支付成功后，用户服务器也会收到 Ping++ 服务器发送的 webhooks 异步通知。 最终支付成功请根据服务端异步通知为准
protected void onActivityResult(int requestCode, int resultCode, Intent data) { //支付页面返回处理 if (requestCode == Pingpp.REQUEST_CODE_PAYMENT) { if (resultCode == Activity.RESULT_OK) { String result = data.getExtras().getString("pay_result"); /* 处理返回值 * "success" - 支付 * 成功 * "fail" - 支付失败 * "cancel" - 取消支付 * "invalid" - 支付插件未安装（一般是微信客户端未安装的情况） * "unknown" - app进程异常被杀死(一般是低内存状态下,app进程被杀死) */ String errorMsg = data.getExtras().getString("error_msg"); // 错误信息 String extraMsg = data.getExtras().getString("extra_msg"); // 错误信息 showMsg(result, errorMsg, extraMsg); } }}// 注：线下渠道无支付结果返回, 返回 unknown 字段。需要从服务端获取正确的支付结果。
混淆设置
用户进行 apk 混淆打包的时候，为了不影响 Ping++ SDK 以及渠道 SDK 的使用，请在主 module 以及该 SDK 依赖所在的 module 中添加以下混淆规则。
# Ping++ 混淆过滤-dontwarn com.pingplusplus.**-keep class com.pingplusplus.** {*;} # 支付宝混淆过滤-dontwarn com.alipay.**-keep class com.alipay.** {*;} # 微信或QQ钱包混淆过滤-dontwarn com.tencent.**-keep class com.tencent.** {*;} # 银联支付混淆过滤-dontwarn com.unionpay.**-keep class com.unionpay.** {*;} # 招行一网通混淆过滤-keepclasseswithmembers class cmb.pb.util.CMBKeyboardFunc { public <init>(android.app.Activity); public boolean HandleUrlCall(android.webkit.WebView,java.lang.String); public void callKeyBoardActivity();} # 内部WebView混淆过滤-keepclassmembers class * { @android.webkit.JavascriptInterface <methods>;}
关于定制
用户可以根据需求自行定制一个或者多个支付渠道，但是定制 SDK 的时候需要注意以下几点：
- PaymentActivity 必须在 AndroidManifest.xml 文件里面声明。
<!-- Ping++ SDK 注册 --> <activity android:name="com.pingplusplus.android.PaymentActivity" android:launchMode="singleTop" android:theme="@android:style/Theme.Translucent.NoTitleBar" />
- 权限
微信支付渠道是通过向「微信」客户端发起请求进行支付的，要求手机必须安装微信。如果没有安装微信，Ping++ SDK 会在支付结果中给予通知。支付宝、银联等渠道，需要的权限为：
<uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <uses-permission android:name="android.permission.READ_PHONE_STATE" /> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
- 用户如果选择不使用某种渠道，可以把该渠道相关的 Activity 从 AndroidManifest.xml 删除
- 若安装了银联云闪付 app，那么使用
upacp渠道时会直接调起云闪付，反之则默认使用网页版的银联支付 - 判断是否安装了招商银行客户端：
// isInstalled true: 已安装 false: 未安装boolean isInstalled = Pingpp.isCmbWalletInstalled(context);
- 使用招行一网通非混淆加密方式下，需配置
cmbkb_publickey字段，配置方法如下：
- 在自己项目中 res/values/string.xml 下配置该字段
- 在 pingpp/res/values/cmbkb_strings.xml 下替换该字段
<string name="cmbkb_publickey">填写自己的publickey</string>
- 是否允许手机 Pay（比如 Huawei Pay、Mi Pay）：
// true: 允许 (默认) false: 不允许Pingpp.isPermissionSEPay(false);
日志开关
SDK 提供了日志功能，日志默认为关闭状态。开发者可以通过以下设置打开日志开关。通过 PING++ 来对日志进行筛选。
//开启调试模式Pingpp.DEBUG = true;
注意事项
- Android 不允许在 UI 线程中进行网络请求，所以请求 Charge、Order、Recharge 对象的时候请使用 thread+handler 或者使用 AsyncTask 。example 里面的示例程序使用的就是 AsyncTask 方式请求。
- Ping++ Android SDK 可能会与友盟、百度地图等其他第三方 jar 包冲突，当同时使用这些 jar 包的时候，你需要根据情况判断保留哪一方的 jar 包。
wx渠道是通过向微信客户端发起请求进行支付的，要求： 手机必须安装微信。 应用包名和签名必须与填写在微信开放平台上的一致，微信平台上的签名需是 MD5 且不带冒号的格式。 调试的时候必须打包出来测试，否则无法调用微信支付控件。- 请勿直接使用客户端支付结果作为最终判定订单状态的依据，由于 Ping++ 没有参与你的客户端和第三方渠道的交互，无法保证客户端支付结果的安全性，建议订单状态的更新对比客户端的渠道同步回调信息和服务端的 Ping++ Webhooks 通知来确定是否修改。
下一步H5 SDK 接入指南
