一、API文档说明
本API文档面向与绝峰SDK进行合作的游戏商。详情如下：
-
1、数据通过HTTP协议传输。
-
2、请求方式：HttpPost。
-
3、数据格式：参数格式（示例：a=XXX&b=XXXX）。
-
4、加密方式：MD5。
-
5、请求参数与返回值编码格式为UTF-8。
-
6、签名方式：MD5(全部变量串按照字母顺序+server_key) 。
-
7、server_key：在线获取或QQ群内向对接人员索取。
-
8、支持通过Quick出包，渠道名：绝峰游戏。
二、接口详情介绍
1、订单支付回调
说明：此接口用于确认游戏中与sdk交易的成功与否,由游戏厂商编写,并告知绝峰sdk,添加回调地址,当有交易需要确认时, 绝峰sdk会调用相关接口确认交易信息。
回调地址 在对接时候 线下发给SDK 开发人员即可。（回调地址请不要携带参数避免出错）
（1）接口请求参数说明：
| 请求参数 | 说明 | 示例 |
|---|---|---|
| orderId | 调用sdk支付接口,返回的订单号[String] | orderId=1212121 |
| gameRole | 游戏内对应角色唯一id [String] | gameRole=2323 |
| gameArea | 游戏内区服id[String] | gameArea=234 |
| productName | 游戏内购买物品定义名称[String] | productName=光明礼包2 |
| productDesc | 游戏内购买物品定义描述[String] | productDesc=光明礼包12元 |
| remark | 游戏自定义信息[String] | 游戏方订单编号，方便数据查询，建议长度<=64，‘透传字段’ |
| payTime | 玩家在sdk中支付的时间[String] | 格式：yyyy-MM-dd HH:mm:ss
例子：2017-06-13 12:15:30 |
| amount | 支付金额[String] （单位：元） | amount=10.22 |
| payWay | 支付方式[String] | payWay=支付宝 |
| sign | 请求签名[String] |
md5(amount=10.22&gameArea=12&gameRole=2323& orderId=1212121&payTime=2017-06-13 12:15:30& payWay=支付宝&productDesc=光明礼包12元& productName=光明礼包2&remark=111server_key)，字符串拼接 参数直接拼接，然后加密。不做转码或其他处理 |
（2）接口返回值说明：
| 返回值内容 | 表达意义 |
|---|---|
| success | 成功收到sdk服务器的交易确认,并确认完成无异议，【小写】 |
| failed | 成功收到sdk服务器交易确认,但交易细节有问题,参数确认失败 |
| 如果重复收到此消息，且订单已结完成。请直接回复 success |
2、订单查询接口 （非必须）
说明：此接口用于游戏服务器主动请求绝峰sdk服务器确认订单信息接口
按照游戏方本身的业务选择性接入即可
| 请求地址 | http://api.yiigames.com/search/order |
| 请求方式 | HttpPost |
| 说明 | 根据订单号获取相应的订单信息, server_key由服务端调取 |
（1）接口请求参数说明：
| 请求参数 | 说明 | 示例 |
|---|---|---|
| orderId | 调用sdk支付接口,返回的订单号[String] | orderId=1212121 |
| sign | 请求签名[String] | md5(orderId=1212121server_key)，字符串拼接 |
（2）接口返回值说明：
| 返回值 | 说明 | 示例 |
|---|---|---|
| code | 成功或失败的标识[String] | 1 |
| msg | 结果说明[String] | 获取成功 |
| data | 成功后返回的数据信息 | |
| gameRole | 游戏内对应角色唯一id[String] | 12 |
| gameArea | 游戏内区服id [String] | 234 |
| productName | 游戏内购买物品定义名称[String] | 大礼包 |
| productDesc | 游戏内购买物品定义描述[String] | 大礼包20元 |
| remark | 游戏自定义信息[String] | |
| payTime | 玩家在sdk中支付的时间[String] | 格式：yyyy-MM-dd HH:mm:ss
例子：2017-06-13 12:15:30 |
| amount | 支付金额[String]（单位：元） | 12.00 |
| payWay | 支付方式[String] | 支付宝 |
成功返回值示例：
{
"code":"1",
"msg":"获取成功",
"data":
{
"gameRole":"###",
"gameArea":"###",
"productName":"###",
"productDesc":"###",
"remark":"###",
"payTime":"###",
"amount":"###",
"payWay":"###"
}
}
失败返回值示例：
{
"code":"400",
"msg":"参数缺失orderId为空"
}
（3）code返回值说明：
| code | msg |
|---|---|
| 0 | 1、获取订单信息失败 2、订单不存在 |
| 1 | 获取成功 |
| 400 | 参数缺失orderId |
| 401 | 签名不正确 |
3、登录token验证接口 （建议接入）
说明：此接口用于玩家在登录后，游戏服务器主动请求sdk服务器验证登录信息接口，按照游戏方本身的业务选择性接入即可
| 请求地址 | http://api.yiigames.com/api/cp/user/check |
| 请求方式 | HttpPost |
| 说明 |
注意：本接口跟其余两个接口的加密参数有点区别 本接口：其他参数 &app_key=server_key |
（1）接口请求参数说明：
| 请求参数 | 说明 | 示例 |
|---|---|---|
| app_id | 游戏id[String] | app_id=60079 |
| mem_id | 玩家id[String] | mem_id=12 |
| user_token | 玩家token[String] | user_token=49356f14-6dff-43e0-b55a-321de1d87b8a |
| sign | 请求签名[String] |
md5(app_id=1212121&mem_id=12&user_token=sasa&app_key=server_key) 字符串拼接（注意最后有链接符号 &） |
（2）接口返回值说明：
| 返回值 | 说明 | 示例 |
|---|---|---|
| status | 成功或失败的标识[String] | 1 |
| msg | 结果说明[String] | 获取成功 |
成功返回值示例：
{
"status":"1",
"msg":"验证成功"
}
失败返回值示例：
{
"status":"11",
"msg":"app_id错误"
}
（3）status返回值说明：
| status | msg |
|---|---|
| 1 | 验证成功 |
| 11 | app_id错误 |
| 12 | 签名错误 |
| 14 | Token不存在或已失效 |
一、接入说明
1.1、谁来阅读此文档
接入厂商的产品，技术人员，平台技术人员。
1.2、注意事项
接口参数大小写敏感
request和response的编码格式为UTF-8。
备注：
-
1、【闪屏】SDK已经自带，不需要额外添加。
-
2、不需要【角标】。
-
3、【包名后缀】，期望：.jfandriod
-
4、【SDK名称】：绝峰游戏
-
5、素材需求：（期望）
| logo（必须） | 请提供最大尺寸 |
| icon（必须） | 尺寸：512*512，格式：png |
| 宣传截图（必须） | 尺寸：不低于600*900，数量：5张 |
| Banner/宣传图（必须） | |
| 首页banner位 图片 | 尺寸：不低于1920*960 |
| 首页新游推荐位 | 尺寸：不低于468*234 |
| 精品游戏推荐图 | 尺寸：不低于630*420 |
| 主要游戏人物的原画、素材 | 原画、素材尽量多给，有什么给什么 |
1.3、名词定义
| 名词 | 说明 |
|---|---|
| CP | 游戏合作商 |
| APP | 接入平台的游戏 |
| JF_APPID | 接入时由平台分配的游戏ID |
| JF_APPKEY | 接入时由平台分配的游戏/应用密钥 |
二、拷贝部分
2.1、jar文件的拷贝
将libs文件夹下的jar包拷贝到自己项目的libs文件夹下并添加依赖
2.2、资源文件的拷贝
-
1.将res文件夹下的资源文件复制到自己相对应的资源文件夹下或者将内容拷贝到自己相对应的文件内（必须拷贝，文件夹内资源文件名称和内容不可修改）如图所示。
-
2. 如已存在assets目录将assets文件夹内部文件考入，不存在的话将assets文件夹拷贝到main文件夹下。
2.3、AndroidManifest.xml 文件的配制
2.3.1、在工程AndroidManifest.xml格式如下，确保工程AndroidManifest.xml具有以下权限
(如有误差，请以DEMO 为准)
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>
<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.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.MOUNT_UNMOUNT_FILESYSTEMS"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permissionandroid:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS"/>
2.3.2、在工程AndroidManifest.xml的<application>段内配置以下内容
说明：activity的配置与支付模块有关，以demo中配置为准，为第三方支付（支付宝）接入平台SDK的activity，还有一类就是非支付类的：比如用户个人中心之类的，这些要填写，以DEMO为准，还有service需配置，以demo为准
(可将内容拷贝粘贴到自己的Manifest里面，需要更换JF_APPID和JF_APPKEY为绝锋游戏平台所提供的JF_APPID和JF_APPKEY)
<!—PayActivity所有游戏强制竖屏-->
<activity android:name="com.juefeng.sdk.jfsdk.ui.activity.PayActivity" android:screenOrientation="portrait"/>
<!-- WebViewActivity所有游戏强制竖屏-->
<activity android:name="com.juefeng.sdk.jfsdk.ui.activity.WebViewActivity" android:screenOrientation="portrait"/>
<!-- InitdataActivity 横竖屏参数可根据游戏需要自行配置-->
<activity android:name="com.juefeng.sdk.jfsdk.ui.activity.InitdataActivity" android:screenOrientation="portrait"/>
<service android:name="com.juefeng.sdk.juefengsdk.JFSDKService">
<intent-filter android:priority="1000">
<action android:name="com.juefeng.sdk.juefengsdk.JFSDKService"></action>
</intent-filter>
</service>
<!-- 支付宝相关配置,此处按第三方支付添加配置 -->
<activity
android:name="com.alipay.sdk.app.H5PayActivity"
android:configChanges="orientation|keyboardHidden|navigation"
android:exported="false"
android:screenOrientation="behind"
android:windowSoftInputMode="adjustResize|stateHidden"/>
<activity
android:name="com.alipay.sdk.auth.AuthActivity"
android:configChanges="orientation|keyboardHidden|navigation"
android:exported="false"
android:screenOrientation="behind"/>
<!--此处用于配置JF_APPID和JF_APPKEY到时候参照demo-->
<meta-data android:name="JF_APPID" android:value="1"/>
<meta-data android:name="JF_APPKEY" android:value="7D00D570B14806C235BCA79CC8BBEB1D"/>
三、sdk业务接口代码说明
3.1、sdk初始化，登录，注册，支付，退出等事件监听接口的实现及参数说明
3.1.1、api说明
SDK的大部分API调用，使用了事件通知的方式回调给游戏,游戏通过创建一个SDKEventListener对象，实现对SDK的每个事件结果的监听以下是代码部分（包含对每个回调接口的解释，及参数说明）。
3.1.2、代码部分
SDKEventListener mSDKEventListener = new SDKEventListener(){
@Override
public void onLoginSuccess(LogincallBacklogincallBack) {//登录成功
JFSDK.getInstance().showFloatView();
}
@Override
public void onLoginFailed(LoginErrorMsgloginErrorMsg) {//登录失败
ToastUtils.show(loginErrorMsg.getErrorMsg());
}
@Override
public void onInitSuccess(String desc,booleanisAutoLogin) {
ToastUtils.show("初始化成功");
}
@Override
public void onInitFaild(String desc) {
ToastUtils.show("初始化失败);
}
@Override
public void onPaySuccessCallback(PaySuccessInfopaySuccessInfo) {
ToastUtils.show("支付成功");
}
@Override
public void onPayFaildCallback(PayFaildInfopayFaildInfo) {
ToastUtils.show("支付失败");
}
@Override
public void onExit(String desc) {//退出成功
MainActivity.this.finish();
}
@Override
public void onCancleExit(String desc) {
ToastUtils.show("取消退出");
}
@Override
public void onCreatedOrder(CreatOrderInfo infoBean) {
//订单创建成功
}
@Override
public void onLogoutLogin(){//此处需回到游戏登录界面游戏方执行
}
};
3.1.3、接口及参数说明
| 方法 | 说明 |
|---|---|
| onInitSuccess(String desc,boolean isAutoLogin) |
初始化成功； 参数说明：desc(字符串“初始化成功”) IsAutoLogin(是否可调取自动登录) |
| onInitFaild(String desc) |
初始化失败； 参数说明：desc(字符串“初始化失败原因”) |
| onLoginSuccess(LogincallBack logincallBack,booleanisAutoLogin) |
登录成功 1、客户端未曾有过登录账号isAutoLogin为false 2、自动登录触发过程中点击取消登录并且后续未执行登录操作直接退出游戏，下次初始化为false 3、可以根据isAutoLogin在游戏加载成功后去触发自动登录效果 |
| onLoginFailed(LoginErrorMsgerrorMsg) |
登录失败 参数说明：errorMsg (登录失败后返回的错误码，及失败原因) |
| onPaySuccessCallback (PaySuccessInfopaySuccessInfo) |
支付成功 参数说明：paySuccessInfo(支付成功后返回的订单信息，含有订单号，此处还需要去跟游戏服务器确认支付信息，才可确定支付成功) |
| onPayFaildCallback(PayFaildInfopayFaildInfo) |
支付失败 参数说明：payFaildInfo(支付失败返回的信息) |
| onExit(String desc) |
退出成功 参数说明：desc(字符串“成功退出”) |
| onCancleExit(String desc) |
取消退出，选择继续游戏 参数说明：desc(字符串“取消退出”) |
| onCreatedOrder(CreateOrderInfocreatOrderInfo) |
SDK服务器已经成功创建此订单 creatOrderInfo订单信息 |
| onLogoutLogin() | 注销账号登录（需在此回调中退出游戏，返回登录页面） |
3.2、sdk的初始化
3.2.1、代码部分
JFSDK.getInstance().init(this, mSDKEventListener, false);
3.2.2、参数说明
1、初始化sdk资源，注册sdk事件监听器。
2、false代表sdk不会自动触发自动登录事件。
3、将false改为true，sdk会自主触发自动登录。
4、mSDKEventListener为3.1实现的事件监听器。
3.2.3、回调说明
初始化的成功失败会回调 3.1 中的 onInitSuccess 和 onInitFaild cp可根据回调结果做出相应处理
3.3、登录
3.3.1、登录拉起说明
方法需要在UI线程中调用，详细调用可以参考DEMO 以下为示例。
代码调用：JFSDK.getInstance().doLogin(MainActivity.this);
调用效果如下图所示
3.3.2、登录回调说明
回调说明：登录和注册的失败会回调到 3.1 中的 onLoginSuccess 和 onLoginFailed cp可根据回调结果做出相应处理
3.3.3、返回参数说明
登录或注册成功回调方法：onLoginSuccess
回调参数说明：
| 参数名 | 类型 | 参数说明 |
|---|---|---|
| userId | string | 登录成功后，用户的userId（唯一） |
| token | string | 用户此次登录平台分配的唯一token（唯一） |
| userName | string | 用户名 |
登录失败回调方法：onLoginFaild
该方法在产生业务逻辑错误时调用
| 参数名 | 类型 | 参数说明 |
|---|---|---|
| code | string | 登录失败错误码 |
| errorMsg | string | 登录失败的消息提示 |
3.4、支付
3.4.1、支付的拉起
JFSDK.getInstance().showPay(this,"商品名称","商品描述","0.1","区服信息","角色Id","用户自定义参数","订单号");
3.4.2、拉起参数说明（以下参数传递顺序不可改变）
| 参数 | 说明 |
|---|---|
| this | 游戏的Activity对象，不可为null。 |
| 商品名称(String) | 所购买商品的名称，不可为null 不可为空串 |
| 商品描述(String) | 所购买商品的说明不可为null 不可为空串 |
| 0.1(String) | 钱数(数字类型字符串，精确到小数点后一位)不可为null 不可为空串(单位元) |
| 区服信息(String) | 有则传没有可传任意字符串(不可为null不可为空串) |
| 角色Id (String) | 角色游戏内唯一标示(含所有区服)(不可为null不可为空串) |
| 用户自定义参数 | 用户自定义参数（不可为空，没有传cp订单号） |
| 订单号 | Cp生成的订单号（必传） |
3.4.3、支付的回调
支付涉及三个回调，创建订单成功，支付成功，支付失败。分别会回调到 3.1 中的onCreatedOrder，onPaySuccessCallback，onPayFaildCallback
3.4.4、回调返回对象字段解释
onPaySuccessCallback，onCreatedOrder，onPayFaildCallback
PaySuccessInfo｛
public String orderId; //服务端生成的唯一订单号
public String gameRole; // 游戏端传入的角色Id
public String gameArea; //游戏端传入的区服信息
public String productName; //游戏端传入的商品名称
public String productDesc; //游戏端传入的商品描述
public String remark; //游戏端传入的自定义参数
public String cpOrderId; //cp传入的订单号
｝
CreateOrderInfo｛
public String orderId; //sdk服务端生成的唯一订单号
public String gameRole; //游戏端传入的角色Id
public String gameArea; //游戏端传入的区服信息
public String productName; //游戏端传入的商品名称
public String productDesc; //游戏端传入的商品描述
public String cpOrderId; //cp传入的订单号
public String remark; //游戏端传入的自定义参数
｝
PayFaildInfo｛
private String code; //错误码
private String msg; //失败说明
｝
3.5、平台浮点，用户中心（必须调用）
3.5.1、功能说明
登录完成后，可以通过悬浮按钮进入个人中心，
查看平台帐号信息
设置帐号密码保护
帐号绑定手机
修改帐号密码
管理支付密码，查看充值和消费记录
3.5.2、API调用
-
1、浮点的显示
代码：JFSDK.getInstance().showFloatView(MainActivity.this);
-
2、浮点的隐藏
public void removeFloatView() //隐藏悬浮窗口
3.5.3、API调用位置
-
1、浮点的显示
需再游戏界面 获取焦点和（3.1）登录成功的回调中调用浮点显示代码如下所示
@Override
Protected void onResume() {// 显示浮点
JFSDK.getInstance().showFloatView(this);
super.onResume();
}
SDKEventListener mSDKEventListener = new SDKEventListener()
{
@Override
public void onLoginSuccess(LogincallBack logincallBack)
{
ToastUtils.show("登录成功");
JFSDK.getInstance().showFloatView(MainActivity.this);
}
}
-
2、浮点的隐藏
需要在游戏界面失去焦点的时候调用
@Override
Protected void onStop() { // 从窗体移除浮点
JFSDK.getInstance().removeFloatView();
super.onStop();
}
3.6、自动登录
3.6.1、API的使用
JFSDK.getInstance().AutoLogin(MainActivity.this)
3.6.2、回调
登录成功会回调onLoginSuccess(LogincallBacklogincallBack) （参见3.1）
登录失败会回调onLoginFaild(LoginErrorMsgloginErrorMsg) （参见3.1）
3.6.3、说明
此接口调用后可以自动拉起上次所登录的账号执行自动登录，一般用于游戏资源加载成功后，此接口是否可调用可通过onInitSuccess(String desc,boolean isAutoLogin)中的isAutoLogin 来判断：
isAutoLogin说明：
-
1、客户端未曾有过登录账号isAutoLogin为false
-
2、自动登录触发过程中点击取消登录并且后续未执行登录操作直接退出游戏，下次初始化为false
-
3、可以根据isAutoLogin在游戏加载成功后去触发自动登录效果
3.7、游戏数据同步（必须调用）
3.7.1、说明
首次登入游戏或角色信息发生变化时sdk需要同步角色信息
3.7.2、调用
Map<String,String> map = new HashMap<String, String>();
map.put(SDKParamKey.LEVEL,"2");//用户等级
map.put(SDKParamKey.ROLENAME,"特朗普");//角色名称
map.put(SDKParamKey.ROLEID,"123465");//角色Id
map.put(SDKParamKey.EXPERIENCE,"213");//用户当前经验值(可为"" 不可为null)
map.put(SDKParamKey.ATTACH,"213");//额外信息(可为"" 不可为null)
map.put(SDKParamKey.SERVERNAME,"天下第一");//服务器名称
map.put(SDKParamKey.SERVERID,"213");//用户所在服务器Id
JFSDK.getInstance().syncInfo(map);
3.8、游戏退出
3.8.1、API的使用
调用JFSDK.getInstance().exitLogin(MainActivity.this);
3.8.2、调用位置
需要重写 dispatchKeyEvent 方法 代码如下（可直接拷贝）
@Override
public boolean dispatchKeyEvent(KeyEvent event) {
if(event.getKeyCode() == KeyEvent.KEYCODE_BACK) {
if(event.getAction() == KeyEvent.ACTION_DOWN&&event.getRepeatCount() == 0) {
JFSDK.getInstance().exitLogin(MainActivity.this);
return true;
}
}
return super.dispatchKeyEvent(event);
}
3.8.3、回调说明
点击返回键调用 JFSDK.getInstance().exitLogin();
选择退出是 会回调 （3.1）SdkEventListener 内的 onExit()方法 在此方法里面执行游戏界面的关闭
/*这两个回调在init方法注册的SdkEventListener的事件监听器中*/
//需要在onExit方法中执行游戏界面关闭的操作(此处MainActivity代表游戏界面)
@Override
public void onExit(String desc)
{
ToastUtils.show("退出成功");
MainActivity.this.finish();
}
//onCancleExit为取消退出的回调方法
@Override
public void onCancleExit(String desc)
{
ToastUtils.show("取消退出");
}
3.9、注销登录（必须实现）
点击个人中心的退出当前账户按钮，会回调（3.1）中的 onLogoutLogin 接口 此接口内需实现返回游戏登录界面的代码 游戏方执行
四、注意
4.1、运行环境
-
目前该sdk只支持Android 4.0或以上版本的手机系统
-
手机必须处于网络环境中，2.5G/3G/4G/WIFI等等
4.2、混淆
JFSDK包是以jar提供给用户的，已经半混淆状态，您在混淆自己APK包的时候请不要将jar包一起混淆，因为里面有自定义UI控件，若被混淆后会因为无法找到相关类而抛异常。