掌趣安卓SDK接入说明

1.文档说明

1.1 功能描述

此文档主要是用于在游戏及应用开发商需要接入掌趣BASE SDK时，了解BASE SDK如何接入，接入过程中需注意的事项等。

1.2 阅读对象

接入掌趣BASE SDK的游戏及应用的android客户端开发者。

2.接入准备

服务端配置：请参考 通用接入文档—> 《SDK服务端接入说明文档》

3.特别说明

3.1 游戏版本命名

安卓包是指androidmainfest.xml中的versionName。

3.2 渠道识别

在掌趣自动打包系统里，serviceId是区分渠道信息的标识，研发如果要识别当前游戏包属于哪个渠道，请调用获取serviceId的接口（11.2），并和技术经理匹配各serviceId对应的渠道。

3.3 游戏中接入第三方SDK

如果产品接入了第三方SDK，有需要根据包名、签名分配参数的情况，一定要提前通知技术经理。各个渠道包的包名、签名、证书等都不一样。自动打包将替换客户端包名、签名和证书。但不会自动替换第三方的参数。如地图、语音、推送能功能的第三方SDK。具体如何实现，需要根据具体情况操作。

4.接入BASE SDK注意事项

4.1 游戏res文件夹中资源文件命名注意事项

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

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

Ourpalm_Entry.getInstance(this).Ourpalm_onPause()
Ourpalm_Entry.getInstance(this).Ourpalm_onRestart()
Ourpalm_Entry.getInstance(this).Ourpalm_onResume()
Ourpalm_Entry.getInstance(this).Ourpalm_onStart()
Ourpalm_Entry.getInstance(this).Ourpalm_onStop()
Ourpalm_Entry.getInstance(this).Ourpalm_onDestroy()
Ourpalm_Entry.getInstance(this).Ourpalm_onActivityResult()
Ourpalm_Entry.getInstance(this).Ourpalm_onConfigurationChanged()
Ourpalm_Entry.getInstance(this).Ourpalm_onNewIntent()

5.导入BASE SDK

5.1 res中资源和lib库的导入

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

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

5.2 AndroidManifest.xml的配置

5.2.1 权限配置

<!-- OurpalmSDK需要的权限 -->
    <uses-permission android:name="android.permission.INTERNET" >
    </uses-permission>
    <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" >
    </uses-permission>
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" >
    </uses-permission>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" >
    </uses-permission>
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" >
    </uses-permission>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" >
    </uses-permission>
    <uses-permission android:name="android.permission.READ_PHONE_STATE" >
    </uses-permission>
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" >
    </uses-permission>
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" >
    </uses-permission>

5.2.2 其他必须配置项

<!-- 客服反馈功能Activity -->
        <activity
            android:name="ourpalm.android.opservice.Ourpalm_OpService_Activity"
            android:configChanges="keyboardHidden|orientation|screenSize"
            android:theme="@android:style/Theme.Translucent.NoTitleBar" >
        </activity>
        <!-- 游戏自己的启动activity类名，需要完整路径，必须配置 -->
        <meta-data
            android:name="ourpalm_class_name"
            android:value="com.ourpalm.test_ourpalm_v3.Ourpalm_Demo_MainActivity" />
        <!-- 游戏请配置自己游戏的展示类型，竖屏游戏请配置成 portrait，横屏游戏请配置成landscape -->
        <meta-data
            android:name="ourpalm_screenOrientation"
            android:value="landscape" />
    <!-- BASE SDK中上传崩溃日志的服务 V3.2.1版本新增加 -->
        <service
            android:name="ourpalm.android.c.Ourpalm_CrashService"
            android:process=":ourpalmCrash" >
            <intent-filter>
                <action android:name="ourpalm.UpCrashLog" />
            </intent-filter>
        </service>

5.2.4 其他注意事项

<!-- 建议targetSdkVersion不要超过22 -->
<uses-sdk
        android:minSdkVersion="7"
        android:targetSdkVersion="22" />
<!-- 如游戏本身有Application类，则需要在代码中继承  
ourpalm.android.channels.Info.Ourpalm_Channels_Application；如游戏本身没有  
Application类，则需要在此添加配置，将AndroidManifest.xml中application的名字  
命名为"ourpalm.android.channels.Info.Ourpalm_Channels_Application" --> 
<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/NoTitle_FullScreen" >
</application>

注意：APK安装位置属性必须配置为android:installLocation=”auto”

6.充值/发货流程

6.2 接口介绍

6.2.1 支付接口

6.2.1.1 功能说明

调用自有支付功能或者第三方SDK的支付功能，实现游戏中的道具购买。

6.2.1.2 接口定义

/**
     * 支付接口(单机)，先去获取计费协议
     * 
     * @param propId
     *            游戏自定义的商品ID
     * @param chargeCash
     *            价格（以分为单位）
     * @param currencyType
     *            货币类型(1人民币2美元3日元4港币5英镑6新加坡币7越南盾8台币9韩元)
     * @param propName
     *            商品名称
     * @param propCount
     *            商品数量
     * @param propDes
     *            商品描述
     * @param ExtendParams
     *            扩展参数
     * @param callBack
     *            支付回调接口
     */
    public void Ourpalm_Pay_Console(final String propId,
            final String chargeCash, final String currencyType,
            final String propName, final String propCount,
            final String propDes, final String ExtendParams,
            final Ourpalm_PaymentCallBack callBack)

6.2.1.3 参数说明

6.2.1.4 接口示例

Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_Pay_Console(
        propId, price, "1", propName, propCount, "测试-商品描述",
        "测试-我是扩展参数", 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, "DEMO,花钱成功了。。。*_*",
                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, "DEMO,支付失败了",
                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, "DEMO,下单成功了",
                Toast.LENGTH_SHORT).show();
          }
        });

6.2.1.5 回调接口说明

支付成功：

public void Ourpalm_PaymentSuccess(int code, String ssid, String pbid);

支付失败：

public void Ourpalm_PaymentFail(int code, String ssid, String pbid);

下单成功：

public void Ourpalm_OrderSuccess(int code, String ssid, String pbid)

注：”下单成功”表示当前订单已经成功提交，但用户是否进行支付，当前未知，所以单机游戏
不要处理此回调。

6.2.1.6 回调接口参数说明

7.客服反馈相关

7.1 功能说明

游戏需要自己设计UI按钮，当用户点击此按钮时，调用接口，打开客服反馈界面。

7.2 接口介绍

7.2.1 打开客服反馈接口

7.2.1.1 接口定义

/**
* 进入客服反馈页面
*/
public void EnterServiceQuestion()

7.2.1.2 接口示例

Ourpalm_OpService_Entry.getInstance().EnterServiceQuestion();

8.礼包码兑换

8.1 功能说明

通过礼包码来兑换游戏中对应的礼包。

8.2 接口介绍

8.2.1 礼包码兑换接口

8.2.1.1 接口定义

/**
     * 礼包码兑换接口
     * 
     * @param GiftCode
     *            礼包码
     * @param url
     *            发货地址
     * @param extendParams
     *            扩展参数
     * @param mListener
     *            回调
     */
    public void Ourpalm_GiftExchange(String GiftCode, String url,
            final String extendParams,
            final Ourpalm_GiftExchangeCallBack mListener)

8.2.1.2 参数说明

8.2.1.3 接口示例

Ourpalm_Entry.getInstance(Ourpalm_Entry_Model.mActivity).Ourpalm_GiftExchange("礼包码",
"http://xxxxxxxxx/xxxxxxxx","透传参数",
new Ourpalm_GiftExchangeCallBack() {
  @Override
  public void Ourpalm_Success(String packageId, String extendParams) {
    // TODO Auto-generated
    // method stub
    Toast.makeText(Ourpalm_Demo_MainActivity.mMainActivity, "兑换成功", Toast.LENGTH_SHORT).show();
  }
  @Override
  public void Ourpalm_Fail(int code) {
    // TODO Auto-generated
    // method stub
    Logs.i("info", " 礼包码 兑换失败 code =  " + code);
  }
});

8.2.1.4 回调接口说明

兑换成功：

@Override
public void Ourpalm_Success(String packageId, String extendParams)

packageId：礼包码归属的礼包ID。
extendParams：透传参数。

兑换失败：

@Override
public void Ourpalm_Fail(int code)

code：错误码。

9. Activity生命周期相关接口的调用

9.1 功能说明

因为某些第三方SDK需要用到生命周期中的某些方法，所以游戏客户端Activity中必须调用掌趣SDK中定义的生命周期方法，否则可能会出现不可预估的问题。

9.2 接口介绍

9.2.1 onStart调用示例

@Override
protected void onStart() {
  // TODO Auto-generated method stub
  super.onStart();
  Logs.i("info", "onStart");
  Ourpalm_Entry.getInstance(this).Ourpalm_onStart();
}

9.2.2 onRestart调用示例

@Override
protected void onRestart() {
  // TODO Auto-generated method stub
  super.onRestart();
  Logs.i("info", "onRestart");
  Ourpalm_Entry.getInstance(this).Ourpalm_onRestart();
}

9.2.3 onResume调用示例

@Override
protected void onResume() {
  // TODO Auto-generated method stub
  super.onResume();
  Logs.i("info", "onResume");
  Ourpalm_Entry.getInstance(this).Ourpalm_onResume();
}

9.2.4 onPause调用示例

@Override
protected void onPause() {
  // TODO Auto-generated method stub
  super.onPause();
  Logs.i("info", "onPause");
  Ourpalm_Entry.getInstance(this).Ourpalm_onPause();
}

9.2.5 onStop调用示例

@Override
protected void onStop() {
  // TODO Auto-generated method stub
  super.onStop();
  Logs.i("info", "onStop");
  Ourpalm_Entry.getInstance(this).Ourpalm_onStop();
}

9.2.6 onDestroy调用示例

@Override
protected void onDestroy() {
  // TODO Auto-generated method stub
  super.onDestroy();
  Logs.i("info", "onDestroy");
  Ourpalm_Entry.getInstance(this).Ourpalm_onDestroy();
}

9.2.7 onActivityResult调用示例

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  // TODO Auto-generated method stub
  super.onActivityResult(requestCode, resultCode, data);
  Logs.i("info", "onActivityResult");
  Ourpalm_Entry.getInstance(this).Ourpalm_onActivityResult(requestCode, resultCode, data);
}

9.2.8 onConfigurationChanged调用示例

@Override
public void onConfigurationChanged(Configuration newConfig) {
  // TODO Auto-generated method stub
  super.onConfigurationChanged(newConfig);
  Logs.i("info", "onConfigurationChanged");
  Ourpalm_Entry.getInstance(this).Ourpalm_onConfigurationChanged(newConfig);
}

9.2.9 onNewIntent调用示例

@Override
protected void onNewIntent(Intent intent) {
  super.onNewIntent(intent);
  Logs.i("info","onNewIntent");
  Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_onNewIntent(intent);
}

9.2.10 onSaveInstanceState调用示例

@Override
protected void onSaveInstanceState(Bundle outState) {
  // TODO Auto-generated method stub
  super.onSaveInstanceState(outState);
  Logs.i("info", "onSaveInstanceState");
  // 必须调用
  Ourpalm_Entry.getInstance(this).onSaveInstanceState(outState);
}

10.退出游戏

10.1 功能说明

调用第三方SDK的退出提示接口，如第三方SDK无退出提示接口则调用掌趣的退出提示界面或者直接退出游戏。

10.2 接口定义

/**
     * 调用第三方SDK退出提示页面，如果第三方SDK无退出提示页面则调用掌趣提示页面
     * 
     * @param usetip
     *            是否使用掌趣SDK的退出提示界面
     */
 public void Ourpalm_ExitGame(boolean usetip)

10.3接口示例

@Override
public boolean onKeyDown(int keyCode, KeyEvent event) {
  // TODO Auto-generated method stub
  if (keyCode == KeyEvent.KEYCODE_BACK) {
  Ourpalm_Entry.getInstance(this).Ourpalm_ExitGame(true);
  return true;
  }
  return super.onKeyDown(keyCode, event);
}

11.其他接口

11.1 开启SDK日志输出

11.1.1 功能说明

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

11.1.2 接口示例

// 设置打开日志输出
Ourpalm_Entry.getInstance(this).SetLogs(true);

true为打开，false为关闭。

11.2 获取ServiceId

11.2.1 功能说明

获取当前游戏包中的ServiceId。

11.2.2 接口示例

Ourpalm_Entry.getInstance(this).getServiceId();

11.3 获取ChannelId

11.3.1 功能说明

获取当前游戏包中的ChannelId。

11.3.2 接口示例

Ourpalm_Entry.getInstance(this).getChannelId();

11.4 获取DeviceGroupId

11.4.1 功能说明

获取当前游戏包中的DeviceGroupId。

11.4.2 接口示例

Ourpalm_Entry.getInstance(this).getDeviceGroupId();

11.5 获取LocaleId

11.5.1 功能说明

获取当前游戏包中的LocaleId。

11.5.2 接口示例

Ourpalm_Entry.getInstance(this).getLocaleId();

11.6 获取OpId

11.6.1 功能说明

获取当前游戏包中的OpId。

11.6.2 接口示例

Ourpalm_Entry.getInstance(this).getOpId();

11.7 展示公告栏

11.7.1 功能说明

给玩家展示公告内容。

11.7.2 接口示例

Ourpalm_Entry.getInstance(this).Ourpalm_ShowNotice();

11.8 获取在MIS平台配置的游戏自定义参数

11.8.1 功能说明

游戏可以在MIS平台配置一些自定义参数用于控制游戏中的功能，可以通过此接口实时获取自定义参数。

11.8.2 接口示例

Ourpalm_Entry.getInstance(this).Ourpalm_CustomGameMethod(
                    new CustomGameMethodCallback() {
                        @Override
                        public void complete(boolean isok, JSONObject jsondata) {
                            // TODO Auto-generated method stub
                            if (isok) {
                                Toast.makeText(MainActivity.this,
                                        jsondata.toString(), Toast.LENGTH_LONG)
                                        .show();
                            } else {
                                Toast.makeText(MainActivity.this, "暂无游戏自定义数据",
                                        Toast.LENGTH_LONG).show();
                            }
                        }
                    });

11.8.3 自定义参数返回示例

例如jsondata中的内容是{“key_bank_switch”:”0”}，游戏解析后用于控制游戏中的相关功能。

11.9 第三方支付补单功能

11.9.1 功能说明

目前发现，单机游戏使用第三方支付功能购买相关道具后，由于各种原因，玩家不能获得相应的道具，导致人工补单工作增加，所以增加此接口供游戏使用。进入游戏后，可以在能获取相关道具的前提下，自动调用此补单接口进行掉单查询，如SDK返回相应的订单号和商品ID，请根据商品ID给玩家自动放发相应的道具，如无需补单，数据返回为空。

11.9.2 接口示例

11.9.2.1 设置数据回调接口

请在SDK初始化后进行一次设置，并只设置一次即可。

// 注册自定义接口回调(请在SDK初始化后设置一次即可，不要重复设置，根据回调接口的id来区分功能)
        Ourpalm_Entry.getInstance(this).Ourpalm_SetSpreadsCallBack(
                new Ourpalm_SpreadsCallBack() {
                    @Override
                    public void Ourpalm_Spreads(int id, String... arg) {
                        // TODO Auto-generated method stub
                        switch (id) {
                        case 10000:// 补单功能回调
                            Log.i("info", "arg[0] == " + arg[0]);
                            break;
                        }
                    }
                });

游戏调用的补单接口回调返回数据如下：
01-10 16:57:24.159: I/info(11722): 查询补单结果：arg[0] == [{“orderId”:”0012018011016563087700”,”propId”:”01”}]

11.9.2.2 补单查询接口

Ourpalm_Entry.getInstance(this).Ourpalm_Channel_Spreads("ReissueOrder");

调用此接口后，如存在需补订单，会在补单回调接口中返回相应数据，包含订单号和商品ID。

11.10 TapTap更新唤起功能

11.10.1 功能说明

目前只有饥饿鲨世界TapTap渠道需要接入该功能，该接口只有游戏强更时才需要调用，
调用该接口后，会直接拉起taptap应用详细页面，玩家可以更新游戏。
该功能需要二次打包测试。

11.10.2 接口示例

Ourpalm_Entry.getInstance(this).
      Ourpalm_Channel_Spreads("TapTap_updateGame");

12.状态码表

12.1 SDK客户端状态码表

12.3 服务器计费中心状态码表

12.4 用户中心状态码表