游众SDK-JAVA(Android)接入文档
1、引言
1.1 术语及缩略词
appId: 游戏的唯一标识,用于区分不同游戏的唯一标准。 在游众开发者
中心游戏管理模块中创建新游戏获取。
appKey:游戏的唯一标识,用于区分不同游戏的唯一标准。 在游众开发者
中心游戏管理模块中创建新游戏获取。
sdkId:渠道sdk标识。
opId: 游戏渠道标识,此 id 可区分渠道,在游众后台有相应的渠
道对照表,打包的时候自动生成。
channelId:分发渠道标识。
2、基本流程
2.1 登录流程图
2.2支付流程图
3、接入SDK
3.1 SDK使用准备
SDK 开发包包括以下几个文件与目录:
SDK 开发资源包:SDK 目录中包含SDK的资源文件,请复制SDK目录中的所有目录与文件,并拷贝至各自的游戏工程中,如下:
拷贝资源
将\sdk\java\libs目录下的文件拷贝到游戏对应目录下
3.2添加SDK提供的lib引用
将\sdk\java \libs 目录下的文件拷贝到游戏对应目录下.并做如下图关联。
3.3 配置appId和appKey
可参考“ 网游\sdk\ AndroidManifest.xml "。
<meta-data
android:name="YZGAME_APPID"
android:value="你的appId">
</meta-data>
<meta-data
android:name="YZGAME_APPKEY"
android:value="你的appKey">
</meta-data>
3.4 修改Application
1) 若无自定义Applicatiion,则修改AndroidManifest.xml的Application如下:
<application android:name="com.iyouzhong.yzonlinesdk.YZGameApplication">
2) 若开发者自定义的Application。 则自定义Application需要继承
com.iyouzhong.yzonlinesdk.YZGameApplication,
AndroidManifest.xml修改如下:
<application android:name="自定义Application"/>
3.5 增加闪屏Activity
继承com.iyouzhong.yzonlinesdk.YZSplashActivity并将该 Activity设置为程序启动时的 Activity。
public class MySplashActivity extends YZSplashActivity{
@Override
protected void onCreate(Bundle savedInstanceState){
super.onCreate(savedInstanceState);
}
// 闪屏结束后的操作
@Override
public void endOfSplash() {
// 闪屏结束结束,进入游戏
Intent intent = new Intent(this, Zhensg.class);
startActivity(intent);
this.finish();
}
// 返回闪屏的背景颜色public int getBackgroundColor() {
return Color.BLACK;
}
}
AndroidManifest.xml中关于该Activity的声明,要声明为启动Activity。
<activity
android:name="com.iyouzhong.zhensg.MySplashActivity"
android:label="@string/app_name"
android:screenOrientation="landscape"
android:theme="@android:style/Theme.NoTitleBar.Fullscreen" >
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
3.6 添加SDK需要的use-permision
在游戏的 AndroidManifest.xml 中添加 use-permision 如下,
可参考“ 网游\sdk\ AndroidManifest.xml ”
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.SEND_SMS" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_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.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.READ_SMS" />
<uses-permission android:name="android.permission.WRITE_SMS" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.READ_LOGS" />
<uses-permission android:name="android.permission.MANAGE_ACCOUNTS" />
3.7 SDK 避免模糊,防止计费时发生异常。
两种方式建议使用第二种方式:
1. proguard-project.txt 文件中增加如下代码:
-keep class com.iyouzhong.**(*;)
2. android\sdk\tools\proguard\proguard-android.txt 文件中增加:
-keep class com.iyouzhong.**(*;)
4、基本接口
4.1 SDK初始化接口(必选接口)
如下方法在游戏主 Activity 中调用。
1. public static void onCreate(Activity context)
该方法用于需要在游戏主 Activity 中的 onCreate 中调用,
注意: 只需调用一次
调用用例: YZOnlineSdk.onCreate(this);
2. public static void onStart(Activity context)
该方法用于需要在游戏主 Activity 中的 onStart 中调用,
调用用例: YZOnlineSdk.onStart(this);
3. public static void onRestart(Activity context)
该方法用于需要在游戏主 Activity 中的 onRestart 中调用,
调用用例: YZOnlineSdk.onRestart(this);
4. public static void onResume(Activity context)
该方法用于需要在游戏主 Activity 中的 onResume 中调用,
调用用例: YZOnlineSdk.onResume(this);
5. public static void onPause(Activity context)
该方法用于需要在游戏主 Activity 中的 onPause 中调用,
调用用例: YZOnlineSdk.onPause(this);
6. public static void onStop(Activity context)
该方法用于需要在游戏主 Activity 中的 onStop 中调用,
调用用例: YZOnlineSdk.onStop(this);
7. public static void onDestroy(Activity context)
该方法用于需要在游戏主 Activity 中的 onDestroy 中调用,
调用用例: YZOnlineSdk.onDestroy(this);
8. public static void onNewIntent(Intent intent)
该方法用于需要在游戏主 Activity 中的 onNewIntent 中调用,
调用用例: YZOnlineSdk.onNewIntent(intent);
9. public void onActivityResult(int requestCode, int resultCode, Intent data)
该方法用于需要在游戏主 Activity 中的 onNewIntent 中调用,
调用用例: YZOnlineSdk.onNewIntent(intent);
10. public void onWindowFocusChanged(boolean hasFocus)
该方法用于需要在游戏主 Activity 中的 onWindowFocusChanged中调用,
调用用例: YZOnlineSdk.onWindowFocusChanged(hasFocus);
4.2 用户登录登出接口(必选接口)
1. public static void login(final Context context, final YZOnlineLoginListener listen)
该方法用于登录,调用示例:
/**
* SDK登录回调
*/
private YZOnlineLoginListener loginListener = new YZOnlineLoginListener(){
@Override
public void onFailed(String info) {
// 登录失败回调 }
@Override
public void onSuccess(YZOnlineUser user) {
// 登录成功回调
}
};
YZOnlineSdk.login(this, loginListener);
onSuccess登陆成功回调回来的YZOnlineUser参数描述如下,
用于服务器登录校验:
参数 | 获取方式 | 类型 | 注释 |
appid | user.getAppId() | String | 游众平台创建的游戏id |
sdkid | user.getSdkId() | String | 游众平台的渠道SDK标识 |
uin | user.getUid() | String | 渠道SDK返回的用户id |
session | user.getToken() | String | 渠道SDK登录完成后返回的sessoin id。 特别提醒: 部分渠道此参数会包含特殊值如‘ +’,空格之类的,如直接使用 URL 参数传输到游戏服务器请求校验,会出现问题。 |
sdkversion | user.getVersion() | String | 渠道SDK版本标识 |
ext | user.getExtParams() | String | 扩展字段 |
user.getUid()该方法有部分渠道是无法在前端获取到uid的,uid以从服务端登录验证后返回的uid为准,具体参见游众SDK服务端登录验证接口。比如支付接口那个uid就要用从服务端登录验证后返回的uid
2.public static void logout(Context context)
该方法用于登出,调用示例:
YZOnlineSdk.logout(this)
3. public static void setLogoutListener(LogoutListener logoutListener)
该方法为登出的监听函数需要在调用 login 函数之前调用,调用示例:
// 注销监听
YZOnlineSdk.setLogoutListener(new LogoutListener() { @Override public void onLogout(String info) { // 登出回调 } });
4. public static void switchAccount(final Context context, final YZOnlineLoginListener listen)
该方法用于切换账号,调用示例:
YZOnlineSdk.switchAccount(this, loginListener);
4.3 登录校验接口(必选接口)
由于有些 SDK 要求必须做登录验证,为接入规范,必须接入登录验证,只有登录验证成功才算真正的登录成功。由CP自行向CP服务端发送appid,sdkid,uid,token,version等参数,cp服务端用这些参数再向游众SDK发送登录验证,具体参考游众SDK服务端接入说明。
调用用例:参考demo中的
public void loginCheck(final YZOnlineUser user)
4.4 设置角色基本数据(必选接口)
public static void setRoleData(Context context, String roleId, String roleName, String roleLevel, String zoneId, String zoneName,String roleCTime)
部分渠道如 UC 渠道,要对游戏人物数据进行统计,而且为接入规范,
所以为必选接口
调用时间:在游戏登录验证成功后和角色等级变化时
参数描述:
参数名称 | 类型 | 注释 |
context | Context | 上下文Activity |
roleId | String | 角色唯一标识 |
roleName | String | 角色名 |
roleLevel | String | 角色的等级 |
zoneId | String | 角色所在区服的唯一标识 |
zoneName | String | 角色所在区服名称 |
roleCTime | String | 角色创建时间 |
4.5 退出接口(必选接口)
public static void onExit(Activity act, final YZOnlineExitListener el)
当游戏退出前必须调用该方法,进行清理工作。如果游戏直接退出,而不调用该方法,可能会出现未知错误,导致程序崩溃, 一般游戏在按返回键退出时调用此接口。
调用示例:
public void exitGame(){
finish();
android.os.Process.killProcess(android.os.Process.myPid());
}
/**
* 按下返回鍵时调用onExit方法
*/
public void onBackPressed() {
YZOnlineSdk.onExit(this,new YZOnlineExitListener(){
/* onSDKExit
* @description 当SDK有退出方法及界面,回调该函数
* @param bool SDK是否退出标志位
*/
@Override
public void onExit(boolean result) {
if(result){
//SDK已经退出,此处可以调用游戏的退出函数
exitGame();
}
}
/* onNoExiterProvide
* @description SDK没有退出方法及界面,回调该函数,可在此使用游戏退出界面
*/
@Override
public void onNoExiterProvide(boolean result) {
AlertDialog.Builder builder = new Builder(MainActivity.this);
builder.setTitle("是否退出游戏?");
builder.setPositiveButton("退出",new DialogInterface.OnClickListener() {
@Override
public void onClick(DialogInterface dialog,
int which) {
exitGame();
}
})
.setNegativeButton("取消", null)
.show();
}
});
}
4.6 支付接口(必选接口)
public static void pay(YZPayParams params)
该接口用于调起支付。YZPayParams是支付参数的封装类。
参数描述:
参数名称 | 类型 | 注释 |
Order_Id | String | cp订单号 |
Money | String | 游戏道具价格,必须为整数(单位:元) |
Player_Id | String | 玩家角色id |
Server_Id | String | 区服id |
Product_Name | String | 商品名称 |
Product_Desc | String | 商品描述 |
Pay_CallbackUrl | String | 支付回调地址 |
Custome_Params | String | 自定义参数(必填,不能为空,不能超过64个字符长度) |
UID | String | uid要用从服务端登录验证返回的uid |
EXTRA | String | 酷派渠道扩展参数,登录校验返回,具体可参数Demo |
调用示例:
YZPayParams params = new YZPayParams();
// 价格,整数,单位:元
params.setParam(YZPayParams.Money, "1");
// 玩家角色id
params.setParam(YZPayParams.Player_Id, "123");
// cp订单id
params.setParam(YZPayParams.Order_Id, ""+System.currentTimeMillis());
// 商品名称
params.setParam(YZPayParams.Product_Name, "100元宝");
// 商品描述
params.setParam(YZPayParams.Product_Desc, "100元宝");
// 区服id
params.setParam(YZPayParams.Server_Id, "10000");
// 支付回调地址
params.setParam(YZPayParams.Pay_CallbackUrl, payCallbackUrl);
// 传登录校验返回的uid
params.setParam(YZPayParams.UID, uid);
// 酷派的扩展参数
params.setParam(YZPayParams.EXTRA, extra);
// 自定义参数
params.setParam(YZPayParams.Custome_Params, "test");
YZOnlineSdk.pay(params);
说明:网游的支付结果请以服务器端的同步结果为准,因为某些SDK客户端没有支付结果的回调。
4.7 游戏声音开关接口
public static boolean isMusicEnabled(Activity activity)
判断SDK是否需要打开游戏声音,目前只有移动基地需要此接口,游戏开发者需要根据该返回值,设定游戏背景音乐是否开启。
4.8 打开用户中心和论坛
/**
* 打开用户中心
*
* @return 如果渠道有提供该接口则返回true,默认返回false
*/
public static boolean openUserCenter()
/**
* 打开论坛
*
* @return 如果渠道有提供该接口则返回true,默认返回false
*/
public static boolean openBBS()
5、扩展接口
5.1 获取游戏资源更新信息
/**
* 请求游戏资源更新信息,注意该方法并不是异步的。(选接)
*
* @param appVersion 游戏版本
* @param resVersion 资源版本
* @return 如果请求失败,返回空字符串,请求成功返回json字符串
*/
public static String requestUpdateInfo(String appVersion, String resVersion)
返回参数:
参数名称 | 参数类型 | 说明 | 是否必填 |
errorCode | String | 错误代码 0:成功 1:参数错误 2:签名错误 3:opid不存在 9:其他错误 | 是 |
errorMsg | String | 错误提示 | 是 |
updateUrl | String | 资源更新地址 | 否 |
Status | int | 0:无更新,1:热更,2:强更 | 否 |
返回JSONObject示例:
{"errorCode":0,"updateUrl":"http:\/\/sdev.uzone8.com","errorMsg":"游戏需要更新",”Status”:1}
游戏更新信息配置
游戏的更新信息在游众后台配置
说明:当调用接口时传递的resVersion小于后台配置的资源版本号时才会返回资源更新地址。
5.2 上报区服id接口
/**
* 上报玩家进入游戏服务器ID接口,注意该方法并不是异步的。(选接)
*
* @param zoneId 区服id
* @param uid 用户id
* @return 如果请求失败,返回空字符串,请求成功返回json字符串
*/
public static String uploadEnterZone(String zoneId, String uid)
该接口一般在玩家进入游戏时调用。
返回参数:
参数名称 | 参数类型 | 说明 | 是否必填 |
errorCode | String | 错误代码 0:成功 1:参数错误, 2:没有创建这个appId,9:其他错误 | 是 |
5.3 获取区服列表接口
/**
* 获取区服列表,注意该方法并不是异步的。(选接)
*
* @param uid 用户id
* @param resVersion 资源版本号,大于正式资源版本号,返回测试服,否则正式服,(注:白名单可看到正式服、测试服)
* @return 如果请求失败,返回空字符串,请求成功返回json字符串
*/
public static String requestZoneList(String uid, String resVersion)
返回格式:json
示例:{
"errorCode": 0,
"defaultSid": [
2
],
"data": [
{
"server_id": "2",
"server_name": "测试2服",
"ip": "121.201.1.84",
"game_port": "8080",
"isopen": "0"
},
{
"server_id": "1",
"server_name": "测试1服",
"ip": "120.132.90.230",
"game_port": "8080",
"isopen": "1"
}
]
}
返回参数:
参数名称 | 参数类型 | 说明 | 是否必填 |
errorCode | String | 错误代码 0:成功 1:参数错误, 2:没有创建这个appId,9:其他错误 | 是 |
defaultSid | Json | 默认区服server_id | 是 |
data | Json | 注:该数据中status释义如下 isopen: 1:服务器开启,0:服务器关闭 | 否 |
5.4 公告管理接口
/**
* 公告管理接口,用于判断公告是否更新,注意该方法并不是异步的。(选接)
*
* @param noticeMD5 公告内容
* @return 如果请求失败,返回空字符串,请求成功返回json字符串
*
*/
public static String noticeUpdate(String noticeMD5)
返回参数:
参数名称 | 参数类型 | 说明 |
errorCode | String | 错误代码 0:成功 1:参数错误, 2:没有创建这个appId,3:不需要更新,4:需要更新,9:其他错误 |
errorMsg | String | 返回提示信息 |
url | String | 公告存放的地址,errorCode=4时返回 |
Md5Sign | String | Md5(公告txt),errorCode=4时返回 |
6、其他
6.1 关于混淆
游众SDK 已经经过了混淆,如果要混淆java代码,请不要混淆联编的jar包中的类。可以添加以下类到proguard配置,排除在混淆之外:
-keep class com.iyouzhong.** { *; }