安卓SDK接入说明

安卓SDK单机接入

接入必读

注意事项

SDK概述

附录

0 接入必读

0.1 接入准备

接入开始前，请先做好如下准备工作：
1.创建游戏，获取渠道参数及配置文件
接入前，需要由掌趣项目负责人完成渠道申报并在掌趣后台进行配置，从而获取到该游戏的渠道参数、掌趣配置文件（见下图）。掌趣配置文件（ourpalm.cfg）按照渠道及语言机型的不同，被分别打到对应的压缩文件目录中。

MIS平台配置参数及获取配置文件的说明

2.完成计费申报，填写商品录入模板
计费测试前，还需要完成在渠道的计费点申报，填写《商品录入模板》（见下图），并由掌趣项目负责人完成在掌趣后台的配置。

MIS平台配置计费点方法

0.2 版本命名

游戏版本命名（安卓是指androidmainfest.xml 中的versionName，IOS是指info.plist中的Bundle version），必须遵循如下规则要求（详见附录3.5）

1 注意事项

1.1 游戏需要在AndroidManifest.xml中添加如下配置：

<application

        android:name="ourpalm.android.channels.Info.Ourpalm_Channels_Application"
        android:allowBackup="true"
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme">
        <activity 
          android:name="com.ourpalm.test_ourpalm_v3.MainActivity" 
          android:configchanges="orientation|keyboardHidden|navigation|screenSize"
          android:label="@string/app_name">
          <intent-filter>
            <action android:name="android.intent.action.MAIN">
              <category android:name="android.intent.category.LAUNCHER"></category>
            </action>
          </intent-filter>
        </activity>
       
       <activity
          android:name="ourpalm.android.opservice.Ourpalm_OpService_Activity"
          android:configChanges="keyboardHidden|orientation|screenSize"
          android:theme="@android:style/Theme.Translucent.NoTitleBar" >
       </activity>
        
        <meta-data 
          android:name="ourpalm_class_name" 
          android:value="com.ourpalm.test_ourpalm_v3.MainActivity" />
       
       <meta-data
          android:name="ourpalm_screenOrientation"
          android:value="landscape" />
        
       <service
          android:name="ourpalm.android.c.Ourpalm_CrashService"
          android:process=":ourpalmCrash" >
          <intent-filter>
          <action android:name="ourpalm.UpCrashLog" />
          </intent-filter>
       </service>
</application>

注意：Manifest内配置属性必须为android:installLocation="auto"

1.2 游戏需要在AndroidManifest.xml中添加如下权限：

1.3 游戏的名称需要定义到res/values/strings.xml的app_name中，例如：

1.4 游戏本身所有的Activity的配置项android:launchMode必须使用如下配置，android:configChanges最少包含以下配置：

如游戏本身未对android:launchMode进行配置，请忽略此说明。

1.5 游戏res资源文件命名注意事项：

游戏res资源文件中，png及xml文件命名最好不好过于简单，以免和第三方渠道重复。如close.png或close.xml命名的文件，可以加上游戏名前缀，game_close.png或game_close.xml

1.6 游戏内容的初始化时机：

游戏本身的初始化最好在SDK的初始化结束并成功后开始，因为部分渠道的SDK有自动展示LOGO的功能，如果游戏的初始化先于SDK的初始化或2者并行可能会造成渠道的LOGO展示不出来或显示时间很短的BUG
// 初始化SDK Ourpalm_Entry.getInstance(this).Ourpalm_Init(GameInfo.GameType_Console, gameVer, gameResVer, new Ourpalm_CallBackListener() { @Override public void Ourpalm_LogoutSuccess() { // TODO Auto-generated method stub // 当前渠道带有注销功能的话由游戏实现，如返回到登录界面。 // 单机游戏不用实现 } @Override public void Ourpalm_LogoutFail(int code) { // TODO Auto-generated method stub // 当前渠道带有注销功能的话由游戏实现 // 单机游戏不用实现 } @Override public void Ourpalm_LoginSuccess(String tokenId, String data) { // TODO Auto-generated method stub // 登录成功回调，网络游戏必须实现 // 单机游戏不用实现 } @Override public void Ourpalm_LoginFail(int code) { // TODO Auto-generated method stub // 登录失败回调，网络游戏必须实现 // 单机游戏不用实现 } @Override public void Ourpalm_InitSuccess() { // TODO Auto-generated method stub // 待SDK的初始化完成后，游戏开始实现游戏本身的初始化 // 初始化游戏 initGame(); } @Override public void Ourpalm_InitFail(int code) { // TODO Auto-generated method stub // SDK初始化失败的回调，游戏可以在这里实现自己的逻辑处理，可以只提示用户后退出游戏，也可以继续游戏，但SDK的某些功能可能会受到影响 } @Override public void Ourpalm_ExitGame() { // TODO Auto-generated method stub // 游戏使用掌趣SDK退出接口时必须实现此回调，在此处实现退出游戏的功能。 MainActivity.this.finish(); // android.os.Process.killProcess(android.os.Process.myPid()); } @Override public void Ourpalm_SwitchingAccount(boolean Success, String tokenId, String userInfo) { // TODO Auto-generated method stub // 当前渠道带有切换账号功能时，游戏需要实现此接口逻辑进行游戏登录。切换账号分2种情况： //一是调用SDK的切换账号接口实现账号的切换，此类型的切换账号按钮是由游戏去实现，建议放到登录界面，切换账号成功后，登录数据会在此接口返回，游戏可执行游戏的登录流程，类似登录成功接口的回调。 //二是渠道SDK的悬浮框或者用户中心页面带有切换账号功能，如用户点击切换账号并登录成功后，登录数据会在此接口返回，但如果当前游戏场景处于游戏中，游戏正常应该先返回到登录界面，然后再通过SDK切换账号成功返回的数据执行游戏的登录流程（游戏能在游戏中直接实现账号切换，人物改变的除外，不需返回登录界面）。 // Success=true表示切换成功，Success=false表示切换失败，tokenId和userInfo同登录成功接口 // 单机游戏不用实现 } });

1.7 游戏必须接入掌趣 “用户中心”，“切换账号”，“注销”这三个接口：

但需要根据调用Ourpalm_GetEnableInterface这个接口的返回值来确认游戏是否需要启用这三个接口和相应的UI按钮展示，因为根据渠道不同会用到其中之一或者所有或者都不用。

1.8 游戏必须接入掌趣SDK与Activity生命周期相关的接口：

1.9 必须调用接口如下：

掌趣SDK初始化接口；
掌趣SDK登录接口；
掌趣SDK支付接口；
掌趣SDK退出接口；
掌趣SDK Ourpalm_GetEnableInterface接口。

1.10 调用支付接口需注意内容：

支付接口中的参数注意：
propName：商品名称（也可以理解为商品单位）。
propCount：商品数量。

注意：对该接口中的商品名称和商品数量2个参数具体说明，如游戏中所卖商品在游戏界面显示为“100元宝或100金币”，当调用支付接口时，商品名称务必传“元宝或金币”，商品数量务必传“100”，切记不可商品名称传“100元宝或100金币”，商品数量传“1”；如游戏中所卖商品在游戏界面显示为“月卡或礼包”一类，当调用支付接口时，商品名称请直接传“月卡或礼包”，商品数量传“1”。
简单一句话，如果当前商品是某种虚拟游戏货币，商品名称中不要出现数量的概念。

2 SDK概述

2.1开发环境搭建

2.1.1 资源和lib库的引入

方式一：游戏工程直接引用 <ourpalm_android_sdk_lib_渠道缩写_完整版本号> 此lib工程，工程内已包含res中的资源和lib库，如还需使用assets中资源，请自行从<资源，lib库和配置文件>中复制assets文件夹中内容到游戏工程。如何引用LIB工程这里不做详细说明，如不清楚如何导入LIB工程到游戏工程请上网搜索，或者咨询掌趣SDK技术人员。

方式二：直接从<资源，lib库和配置文件>中复制所有资源和lib库到游戏工程的相应目录，包含res,libs,assets。

注意：由MIS平台获取的ourpalm.cfg请放到APK的assets文件夹的根目录。

2.1.2 AndroidManifest.xml的配置

请游戏直接从<资源，lib库和配置文件>中AndroidManifest.xml中复制当前渠道所需配置的内容，内有详细的注释说明。如不清楚请咨询掌趣SDK技术人员。
1.掌趣SDK所需要的权限：

复制代码

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<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.INTERNET"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

2.其他权限配置，根据当前渠道要求自行增加，详情查看当前渠道SDK的DEMO。

2.1.3 备注说明

1.导入过程中可能因为重复引用LIB库导致编译报错，在项目工程中移除重复的LIB库即可。
2.某些渠道关于横竖屏展示问题，需游戏自行在AndroidManifest.xml中设置。
3.AndroidManifest.xml中所需配置的渠道参数，需由产品管理人员申请后填写正确的参数，不要使用DEMO中的value。

2.1.4 Debug SO文件提取

Android平台中目标文件对应的是SO文件，Debug SO文件是指具有调试信息的SO文件。为了能快速并准确地定位用户APP发生Crash的代码位置,掌趣崩溃日志收集功能使用Debug so对APP发生 Crash的程序堆栈进行解析和还原。
注意:该说明主要针对使用了NDK的安卓项目
1.如何定位Debug SO文件

IDE: Eclipse
IDE如果使用Eclipse+NDK,默认情况下,Debug SO文件将位于:

<项目文件夹(Project Directory)>/obj/local/<架构(Architecture)>/

如下图所示:

IDE: Android Sutdio
IDE如果使用Android Sutdio+NDK,默认情况下,Debug编译的Debug SO文件将位于:

<子项目文件夹>/build/intermediates/ndk/debug/obj/local<架构(Architecture)>/

而Release编译的Debug SO文件将位于:

<子项目文件夹>/build/intermediates/ndk/release/obj/local<架构(Architecture)>/

注意：Android Sutdio中"子项目"即Module
如下图所示:

2.Debug SO 文件上传
将取得的Debug so文件按照CPU架构压缩成zip

将压缩好的文件，由产品经理上传至MIS平台游戏包管理处，每个版本对应一个符号文件

2.2SDK初始化接口

2.2.1 功能说明

1.为SDK中各个功能的使用提供必要的准备工作。
2.获取初始化数据。
3.检查版本更新。
4.发送激活日志。
注意：初始化方法必须在游戏Activity的onCreate中调用。

2.2.2 接口定义

2.2.3 参数说明

参数名称	重要性	类型	说明
gameType	必须	String	游戏类型。 public static final String GameType_Online = "1"; // 网游 public static final String GameType_Console = "2"; // 单机
gameVer	可选	String	SDK优先读取AndroidManifest.xml里面的版本号，如未获取到则使用此参数。
gameResVer	可选	String	游戏资源版本号，如游戏无此概念则可以传""。
Listener	必须	Ourpalm_CallBackListener	游戏需实现此回调中的所有接口。

2.2.4 接口示例

// 初始化SDK
	Ourpalm_Entry.getInstance(this).Ourpalm_Init(GameInfo.GameType_Online, gameVer, gameResVer, new Ourpalm_CallBackListener() 	{
			@Override
			public void Ourpalm_LogoutSuccess() {
				// TODO Auto-generated method stub
				// 单机游戏不需要实现
			}

@Override
			public void Ourpalm_LogoutFail(int code) {
				// TODO Auto-generated method stub
				// 单机游戏不需要实现
			}

@Override
			public void Ourpalm_LoginSuccess(String tokenId, String data) {
				// TODO Auto-generated method stub
				// 单机游戏不需要实现
			}

@Override
			public void Ourpalm_LoginFail(int code) {
				// TODO Auto-generated method stub
				// 单机游戏不需要实现
			}

@Override
			public void Ourpalm_InitSuccess() {
				// TODO Auto-generated method stub
				// 游戏实现
				// 初始化游戏
				initGame();
			}

@Override
			public void Ourpalm_InitFail(int code) {
				// TODO Auto-generated method stub
				// 单机游戏不需要实现
			}

@Override
			public void Ourpalm_ExitGame() {
				// TODO Auto-generated method stub
				// 游戏使用掌趣SDK退出接口时必须实现此回调
				MainActivity.this.finish();
			}

@Override
			public void Ourpalm_SwitchingAccount(boolean Success, String tokenId, String userInfo) {
				// TODO Auto-generated method stub
				// 单机游戏不需要实现
			}
		});

2.2.5 回调接口说明(Ourpalm_CallBackListener)

以上接口中的code参数为错误码。

2.3充值发货接口

2.3.1 支付接口（客户端调用，必须）

功能说明
调用自有支付功能，实现游戏中的道具购买。
注意：对该接口中的商品名称和商品数量2个参数具体说明，如游戏中所卖商品在游戏界面显示为“100元宝”，当调用支付接口时，商品名称请传“元宝”，商品数量请传“100”，切记不可商品名称传“100元宝”，商品数量传“1”。

接口定义
参数说明

参数名称	重要性	类型	说明
propId	必须	String	游戏自定义的商品ID，必传。
chargeCash	必须	String	商品价格，单位为分。
currencyType	必须	String	货币类型(1人民币2美元3日元4港币5英镑6新加坡币7越南盾8台币9韩元10泰铢)
propName	必须	String	商品名称（不可带数量）
propCount	必须	String	商品数量
propDes	必须	String	商品描述
ExtendParams	可选	String	游戏自定义数据，支付成功后，计费中心会将此字段数据回传给游戏服务器。
callback	必须	Ourpalm_PaymentCallBack	客户端回调接口

接口示例

Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_Pay_Console("0001", "200", "1", "测试-商品名称", "10","测试-商品描述","测试-游戏自定义扩展参数", new Ourpalm_PaymentCallBack(){
    @Override
    public void Ourpalm_PaymentSuccess(int code, String ssid, String pbid) {
        // TODO Auto-generated method stub
        Logs.i("info", "Ourpalm_PaymentSuccess, code = " + code + " ,ssid = " + ssid + " ,pbid = " + pbid);
        Toast.makeText(MainActivity.this, "花钱成功了", Toast.LENGTH_SHORT).show();
    }
    @Override
    public void Ourpalm_PaymentFail(int code, String ssid, String pbid) {
        // TODO Auto-generated method stub
        Logs.i("info", "Ourpalm_PaymentFail, code = " + code + " ,ssid = " + ssid + " ,pbid = " + pbid);
        Toast.makeText(MainActivity.this, "支付失败了", Toast.LENGTH_SHORT).show();
    }

@Override
    public void Ourpalm_OrderSuccess(int code, String ssid, String pbid) {
        // TODO Auto-generated method stub
        Logs.i("info", "Ourpalm_OrderSuccess, code = " + code + " ,ssid = " + ssid + " ,pbid = " + pbid);
        Toast.makeText(MainActivity.this, "下单成功了", Toast.LENGTH_SHORT).show();
    }
});

回调接口说明(Ourpalm_PaymentCallBack)
支付成功：支付失败：下单成功：
注：“下单成功”表示当前订单已经成功提交，但用户是否进行支付或者支付结果未知，以计费中心服务器的通知为准。单机游戏的支付结果一般不会从此接口返回。

参数名称	重要性	类型	说明
code	必须	Int	结果状态码
ssid	必须	String	掌趣计费中心生成的订单号，如支付失败或者用户取消支付时可能返回为空，运营商短信支付返回空
pbid	必须	String	游戏自定义商品ID

2.4其他功能接口

2.4.1 Activity生命周期方法的调用（客户端调用，必须）

功能说明
因为某些第三方SDK需要用到生命周期中的某些方法，所以游戏客户端Activity中必须调用掌趣SDK中定义的生命周期方法，否则可能会出现不可预估的问题。
接口定义1接口示例1接口定义2接口示例2接口定义3接口示例3接口定义4接口示例4接口定义5接口示例5接口定义6接口示例6接口定义7接口示例7接口定义8接口示例8

2.4.2 退出游戏接口（客户端调用，必须）

功能说明
调用第三方SDK的退出提示接口，如第三方SDK无退出提示接口则调用掌趣的退出提示界面或者直接退出游戏。
接口定义参数说明

参数名称	重要性	类型	说明
Usetip	必须	Boolean	决定是否使用掌趣SDK自带的退出提示界面，如果第三方SDK带有退出提示界面，此参数无效

接口示例

2.4.3 开启SDK日志输出（客户端调用，可选）

功能说明
打开后能在logcat看到SDK的日志输出，TAG为“info”和”msg”, 用于游戏接入SDK的调试阶段，出正式游戏包时请务必关闭日志输出。
接口定义参数说明

参数名称	重要性	类型	说明
log	必须	Boolean	是否打开日志输出

接口示例

2.4.4 礼包码兑换接口

功能说明
兑换礼包码
CP接入礼包码功能时，由SDK来直接提示错误提示语

接口定义参数说明

参数名称	重要性	类型	说明
GiftCode	必须	String	礼包码
url	可选	String	发货地址
extendParams	可选	String	透传参数，成功回调内，将会返回此参数
mListener	必选	GiftExchangeCallBack	结果回调，成功回调内参数说明packageId

接口示例回调接口说明(GiftExchangeCallBack )
兑换成功：兑换失败：