文档中心  >  游众SDK  >  客户端接入说明  >  JAVA接口(Android)

游众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 配置appIdappKey

可参考“ 网游\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.xmlApplication如下:


<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,uidtoken,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.** { *; } 

Copyright © 2012-2018 www.uzone8.com All right reserved.

广州游众网络有限公司版权所有

Return Top