帮助文档

1     开发前准备

1.将“网游\sdk\u3d”目录下的文件CopyAssets\Plugins\Android\中;

2.  AndroidManifest的文件:

1)在游戏AndroidManifest.xml文件的application中添加由易接提供如下代码,可参考“网游\sdk\ AndroidManifest.xml "

<service

     android:name="com.snowfish.a.a.s.ABGSvc"

     android:enabled="true"

     android:process="com.snowfish.a.a.bg">

<intent-filter>

     <action android:name="com.snowfish.a.a.s.ABGSvc"/>

     <category android:name="android.intent.category.DEFAULT"/>

</intent-filter>

</service>

<meta-data

     android:name="com.snowfish.customer"

     android:value="SNOWFISH">

</meta-data>

<meta-data

     android:name="com.snowfish.channel"

     android:value="SNOWFISH">

</meta-data>

<meta-data

     android:name="com.snowfish.sdk.version"

     android:value="2">

</meta-data>

<meta-data

     android:name="com.snowfish.appid"

     android:value="KEY">

</meta-data>

<meta-data

     android:name="com.snowfish.channelid"

     android:value="{4ff036a1-3254eafe}">//此参数不做修改,保持默认就行,打包会自动替换

</meta-data>

标红处的KEY值需要替换成在易接用户中心申请获取的APPID,格式如下:{12345678-12345678} 

2)修改 Application

1)若无自定义Applicatiion,则修改AndroidManifest.xmlApplication如下:

<application   android:name="com.snowfish.cn.ganga.helper.SFOnlineApplication"/>

2)若开发者自定义的Application。则自定义Application需要继承   

com.snowfish.cn.ganga.helper.SFOnlineApplication AndroidManifest.xml修改如下:

<application android:name="自定义Application"/>

3)在游戏的AndroidManifest.xml中添加use-permision如下,可参考“网游\sdk\ AndroidManifest.xml "

<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.MOUNT_UNMOUNT_FILESYSTEMS"/>

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>

<uses-permission android:name="android.permission.READ_PHONE_STATE"/>

<uses-permission android:name="android.permission.GET_TASKS"/>

<uses-permission android:name="android.permission.WAKE_LOCK"/>

<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE"/> 

3. 添加启动闪屏ActivitiyUnity3d游戏入口Activity

1Eclipse中建立一个与unity3d工程同包名工程,引入gangaonlineyijie.jargangaonlinehelper.jar库;

2 新建一个闪屏activity例如SplashActivity,继承com.snowfish.cn.ganga.helper.SFOnlineSplashActivity;

3)新建一个游戏入口activity例如MainActivity继承Unity3DUnityPlayerActivity类;

4)将工程propertiesandroid选项中Is Library选中,如下图

5)将工程bin目录下生成的jar拷贝至unity工程                          Assets\Plugins\Android\bin文件夹下;

6)将Assets\Plugins\Android\AndroidManifest.xml中的主入口Activity配置为SplashActivity。例如:

<activityandroid:name=".SplashActivity">

<intent-filter>

<actionandroid:name="android.intent.action.MAIN"/>

<categoryandroid:name="android.intent.category.LAUNCHER"/>

</intent-filter>

</activity>

7)在Assets\Plugins\Android\AndroidManifest.xml中声明游戏的入口MainActivity,如下:

 <activity

            android:name=".MainActivity"          

            android:configChanges="orientation|navigation|screenSize

                                      |keyboard|keyboardHidden"

            android:label="@string/app_name"

            android:screenOrientation="portrait"

            android:theme="@android:style/Theme.NoTitleBar.Fullscreen" >

            <meta-data

                android:name="unityplayer.UnityActivity"

                android:value="true" />

            <meta-data

                android:name="unityplayer.ForwardNativeEventsToDalvik"

                android:value="true" >

            </meta-data>

        </activity>

注意:闪屏的横竖屏需要cp自己在AndroidManifest.xml中的闪屏activity中,设置一下screenOrientation属性。

8)游戏的入口Activity(例如上述MainActivity)请添加到Assets\Plugins\Android\res\values\strings.xml中的zy_class_name字符串中,使得闪屏完成后即启动游戏,例如:

<string

    name="zy_class_name"> com.yijie.cn.sdk.demo.MainActivity

</string>

2     接口说明

2.1 SDK初始化及Activity生命周期接口(必选接口)

本节方法在游戏入口Activity中调用,例如上述MainActivity

1.  初始化函数,以下2个接口任选一个接入

@Override
    protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       SFOnlineHelper.onCreate(this);
    }

1

SFOnlineHelper.onCreate(Activity arg0)

该方法在游戏Activity中的onCreate中调用。

调用用例:

注意:只需调用一次

2

SFOnlineHelper.onCreate(Activity activity,final SFOnlineInitListener initListener)

该方法用于需要在游戏主Activity中的onCreate中调用,带有初始化完成的回调函数。

调用用例:  

SFOnlineHelper.onCreate(this,new SFOnlineInitListener() {
           @Override
       public void onResponse(String tag, String value) {
           if(tag.equalsIgnoreCase("success")){
                //初始化成功的回调
           }else if(tag.equalsIgnoreCase("fail")){
               //初始化失败的回调,value:如果SDK返回了失败的原因,会给value赋值
           }
           }});

 

2. 

SFOnlineHelper.onStop(Activity arg0);

该方法在游戏Activity中的onStop中调用。

调用用例:

  @Override
    protected void onStop() {
       super.onStop();
       SFOnlineHelper.onStop(this);
   }

3. 

SFOnlineHelper.onDestroy(Activity arg0);

该方法在游戏Activity中的onDestroy中调用。

调用用例:

@Override
    protected void onDestroy() {
       super.onDestroy();
       SFOnlineHelper.onDestroy(this);
    }

4. 

SFOnlineHelper.onResume(Activity arg0);

该方法在游戏Activity中的onResume中调用,如果出现Unity3D界面刷新异常可以增加延迟调用。

调用用例:

@Override
     protected void onResume() {
       super.onResume();
       handel.postDelayed(new Runnable() {          
           public void run() {
              SFOnlineHelper.onResume(MainActivity.this);
           }
       }, 1000);
    }

5. 

SFOnlineHelper.onPause(Activity arg0);

该方法在游戏Activity中的onPause调用。

调用用例:

 @Override
     protected void onPause() {
       super.onPause();
       SFOnlineHelper.onPause(this);
    }

6.

 SFOnlineHelper.onRestart(Activity arg0);

该方法在游戏Activity中的onRestart调用。

调用用例:

@Override
      protected void onRestart() {
       super.onRestart();
       SFOnlineHelper.onRestart(this);
    }

   

2.2 用户登陆登出接口(必选接口)

以下小节所有接口,请在Unity3D脚本中使用。

1.  [DllImport("gangaOnlineUnityHelper")]

privatestatic extern void login(IntPtr context, string customParams);

该方法用于登录,调用用例:

login(curActivity.GetRawObject(),"Login");  

2.  [DllImport("gangaOnlineUnityHelper")]

private static extern void logout(IntPtr context, string customParams);

该方法用于登出,调用用例:

logout(curActivity.GetRawObject(),"LoginOut");

3.  [DllImport("gangaOnlineUnityHelper")]

private static extern void exit(IntPtr context, string gameObject,string listener);

该方法用于系统全局退出,listener为退出监听函数,调用用例:

exit(curActivity.GetRawObject(),"Main Camera"," ExitResult"); 

4.  [DllImport("gangaOnlineUnityHelper")]

private static extern void setLoginListener (IntPtr context,string gameObject, string listener);

该接口方法用于设置登陆监听;

参数描述:

参数名称

类型

注释

context

IntPtr

currentActivity

gameObject

string

游戏场景中的对象,SDK内部完成登陆逻辑后,并把登陆结果通过Unity内部                  API(com.unity3d.player.UnityPlayer.UnitySendMessage(String gameObject,StringruntimeScriptMethod,Stringargs)通知到Unity,故游戏开发者需要指定一个游戏对象和该对象的运行脚本,用于侦听SDK的登陆结果

listener

string

登陆监听函数,隶属于gameObject对象的运行时脚本的方法名称,该方法会在收到通知后触发

调用用例

setLoginListener (curActivity.GetRawObject(),"Main Camera", "LoginResult");

2.3 定额计费接口(必选接口)

1.  [DllImport("gangaOnlineUnityHelper")]

private static extern void pay(IntPtr context, string gameObject,intunitPrice, string unitName, int count, string callBackInfo, string callBackUrl, string payResultListener);

该接口用于定额支付的接口函数。合作伙伴在需要使用定额支付的时候使用该接口。

参数描述:

参数名称

类型

注释

context

IntPtr

上下文Activity

unitName

string

虚拟货币名称(道具名称)

注意:虚拟币名称在游戏内一定要确保唯一性!!!!不能出现多个商品名称相同。

unitPrice

int

当前1个虚拟货币需要支付金额,单位为人民币分

count

int

用户选择购买道具界面的默认道具数量。(总价 count*unitPrice

callBackInfo

string

由游戏开发者定义传入的字符串,会与支付结果一同发送给游戏服务器,游戏服务器可通过该字段判断交易的详细内容(金额角色等)

callBackUrl

string

将支付结果通知给游戏服务器时的通知地址url,交易结束后,系统会向该url发送http请求,通知交易的结果金额callbackInfo等信息

注意:这里的回调地址可以填也可以为空字串,如果填了则以这里的回调地址为主,如果为空则以易接开发者中心设置的回调地址为准。

gameObject

string

游戏场景中的对象,SDK内部完成计费逻辑后,并把计费结果通过Unity内部API(com.unity3d.player.UnityPlayer.UnitySendMessage(String gameObject,StringruntimeScriptMethod,Stringargs)通知到Unity,故游戏开发者需要指定一个游戏对象和该对象的运行脚本,用于侦听SDK的计费结果。

payResultListener

string

支付监听函数,隶属于gameObject对象的运行时脚本的方法名称,该方法会在收到通知后触发

调用用例:

pay(curActivity.GetRawObject(), "Main Camera", 100,  "100金币", 1, "购买金币","http://192.168.0.224:8980/omsdk-cp/user/paylog/sync", "PayResult");  

2.4 非定额计费接口(可选接口)

1.  [DllImport("gangaOnlineUnityHelper")]

private static extern void charge(IntPtr context, string gameObject, string itemName,intunitPrice, int count, string callBackInfo, string callBackUrl, string payResultListener);

该接口用于用户触发计费进行付费行为的入口函数。合作伙伴可以在需要计费的地方调用此接口进行计费。该接口用于非定额计费。

参数描述:

参数名称

类型

注释

context

IntPtr

上下文Activity

itemName

string

虚拟货币名称(道具名称

注意:虚拟币名称在游戏内一定要确保唯一性!!!!不能出现多个商品名称相同。

unitPrice

int

游戏道具单位价格,单位为人民币分

count

int

用户选择购买道具界面的默认道具数量.(count*unitPrice)

callBackInfo

string

由游戏开发者定义传入的字符串,会与支付结果一同发送给游戏服务器,游戏服务器可通过该字段判断交易的详细内容(金额角色等)

callBackUrl

string

将支付结果通知给游戏服务器时的通知地址url,交易结束后,系统会向该url发送http请求,通知交易的结果金额callbackInfo等信息

注意:这里的回调地址可以填也可以为空字串,如果填了则以这里的回调地址为主,如果为空则以易接开发者中心设置的回调地址为准。

gameObject

string

游戏场景中的对象,SDK内部完成计费逻辑后,并把计费结果通过Unity内部API(com.unity3d.player.UnityPlayer.UnitySendMessage(String gameObject,StringruntimeScriptMethod,Stringargs)通知到Unity,故游戏开发者需要指定一个游戏对象和该对象的运行脚本,用于侦听SDK的计费结果。

payResultListener

string

支付监听函数,隶属于gameObject对象的运行时脚本的方法名称,该方法会在收到通知后触发

调用用例:

charge(curActivity.GetRawObject(), "Main Camera", "200金币", 200, 1, "购买金币","http://192.168.0.224:8980/omsdk-cp/user/paylog/sync", "PayResult");

2.5 设置角色基本数据(必选接口)

1.  [DllImport("gangaOnlineUnityHelper")]

private static extern void setRoleData(IntPtr context, string roleId, stringroleName, string roleLevel, string zoneId, string zoneName);

部分渠道如UC渠道,要对游戏人物数据进行统计,而且为接入规范,

调用时间:在游戏登录验证成功后

参数描述:

参数名称

类型

注释

context

IntPtr

上下文Activity

roleId

string

角色唯一标识

roleName

string

角色名

roleLevel

string

角色等级

zoneId

string

区域唯一标识

 

zoneName

string

区域名称

2.6 扩展接口1(必选接口)

1.[DllImport("gangaOnlineUnityHelper")]

private static extern void setData (IntPtr context, string key, string value);

扩展接口,部分渠道要求在创建新角色,或者升级角色时、选择服务器时要上报角色信息,为接入规范,所以为必选接口。

参数描述: 

@value 请按要求传入json格式的字符串,JSONObject 键值定义如下

SFJSONObject  roleInfo = new SFJSONObject ();

roleInfo.put("roleId", "1");         //当前登录的玩家角色ID,必须为数字

roleInfo.put("roleName", "猎人");  //当前登录的玩家角色名,不能为空,不能为null

roleInfo.put("roleLevel", "100");   //当前登录的玩家角色等级,必须为数字,且不能为0,若无,传入1

roleInfo.put("zoneId", "1");       //当前登录的游戏区服ID,必须为数字,且不能为0,若无,传入1

roleInfo.put("zoneName", "阿狸一区");//当前登录的游戏区服名称,不能为空,不能为null

roleInfo.put("balance", "0");   //用户游戏币余额,必须为数字,若无,传入0

roleInfo.put("vip", "1");            //当前用户VIP等级,必须为数字,若无,传入1

roleInfo.put("partyName", "无帮派");//当前角色所属帮派,不能为空,不能为null,若无,传入“无帮派”

roleInfo.put("roleCTime", "21322222");    //单位为秒,创建角色的时间

roleInfo.put("roleLevelMTime", "54456556");  //单位为秒,角色等级变化时间

 

@key键值定义如下:   

key

接口描述

调用示例

createrole

创建新角色时调用

setData(curActivity.GetRawObject(),"createrole",roleInfo.toString());

levelup

玩家升级角色时调用

setData(curActivity.GetRawObject (),"levelup",roleInfo.toString());

enterServer

选择服务器进入时调用

setData(curActivity.GetRawObject(),"enterServer",roleInfo.toString());

注意:还有一些渠道需要接入一些特殊的接口,具体可参考易接工具上各个渠道的“参数填写帮助”

2.7 扩展接口2(可选接口)

1. [DllImport("gangaOnlineUnityHelper")]

private static extern void extend (IntPtr context, string data,string gameObject, string listener);

扩展接口,有些SDK, 要求必须接入统计接口或者其它特殊的接口,并且有返回值或者回调的函数,用户可以使用此接口调用,具体可以参考易接工具上的SDK的参数填写帮助。调用用例:

SFJSONObject temp =new SFJSONObject();
// callbackCount:扩展接口回调函数的数量,没有可以传“0”
temp.put("callbackcount","1");
temp.put("callback1","callback1");
string ss = temp.toInlineString();
SFJSONObject temp1 =new SFJSONObject();
temp1.put("callbackmap",ss);
// extendcallback:扩展接口返回信息,如果不需要返回值可以不加。
temp1.put("extendcallback","extendCallback");
string ll = temp1.toString();
extend (curActivity.GetRawObject(),data, "Main Camera", ll);

详细代码请参考Unity3DDemo

2.8 回调消息定义

回调采用Json方式传递参数,定义如下:

1.  登陆回调

回调返回的Json键值定义对应表:

Key

值类型

注释

"result"

string

登出

"customParams"

string

自定义参数

"userinfo"

SFJSONObject

登陆账户信息

键值"result"Value值定义如下表:

名称

注释

LoginResult.LOGOUT

"0"

登出

LoginResult.LOGIN_SUCCESS

"1"

登入成功

LoginResult.LOGIN_FAILED

"2"

登入失败

键值" userinfo "Value值定义如下表:

参数

键值

类型

注释

id

"id"

long

易接内部userid,该值可能为0,请不要以此参数作为判定

channelId

"channelid"

String

易接平台标示的渠道SDK ID

ChannelUserId

"channeluserid"

String

渠道SDK标示的用户ID

UserName

"username"

 

渠道SDK的用户名称。

Token

"token"

String

渠道SDK登录完成后的Session ID。特别提醒:部分渠道此参数会包含特殊值如‘+’,空格之类的,如直接使用URL参数传输到游戏服务器请求校验,请使用URLEncoder编码。

ProductCode

"productcode"

String

易接平台创建的游戏IDappId

2.9 登陆验证接口(必选接口)

由于有些SDK要求SDK登录成功以后必须做登录验证,为接入规范,必须接入登录验证,只有登录验证成功才算真正的登录成功。

渠道sdk登录成功以后,客户端做登录验证请求的时候只需要把以下四个参数拼接进去就行了。

参数

键值

类型

注释

channelId

"channelid"

String

易接平台标示的渠道SDK ID

ChannelUserId

"channeluserid"

String

渠道SDK标示的用户ID

Token

"token"

String

渠道SDK登录完成后的Session ID。特别提醒:部分渠道此参数会包含特殊值如‘+’,空格之类的,如直接使用URL参数传输到游戏服务器请求校验,请使用URLEncoder编码。

ProductCode

"productcode"

String

易接平台创建的游戏IDappId

调用用例:

详细代码请参考Unity3DDemo

2.  支付回调:

名称

注释

PayResult. PAY_SUCCESS

"0"

支付成功

PayResult. PAY_FAILURE

"1"

支付失败

PayResult. PAY_ORDER_NO

"2"

返回支付订单号

使用方法参见unity3DDemo

3.  exit回调

名称

注释

ExitResult.SDKEXIT

"0"

Exit

ExitResult.SDKEXIT_NO_PROVIDE

"1"

SDKEXIT_NO_PROVIDE

使用方法参见unity3DDemo

4.  extend回调

回调返回的Json键值定义对应表:

Key

值类型

注释

"tag"

string

success”成功,”fail” 失败

“value”

string

失败带回的信息。

"customParams"

string

自定义参数

使用方法参见unity3DDemo