Android海外SDK接入说明

修订记录

日期 版本号 修改说明 作者
2017/10/11 V3.3.7 文档创建 李庆硕
2018/03/29 V3.3.9 文档创建 李庆硕

1 文档说明

1.1 功能描述

此文档主要是用于在游戏及应用开发商需要接入掌趣SDK时,各个用户和计费相关的接口参考说明。
用于在游戏及应用开发商需要接入掌趣BASE SDK时,了解BASE SDK如何接入,接入过程中需注意的事项等。

1.2 阅读对象

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

2 接入准备

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

3 特别说明

3.1 游戏版本命名

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

3.2 渠道识别

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

3.3 游戏中接入第三方SDK

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

3.4 掌趣SDK中普通闪屏说明

游戏使用掌趣sdk的闪屏功能时,如果想替换预置的掌趣logo图片,可以按照下面的闪屏制作规范,替换相应图片资源即可, 同时可以新增游戏闪屏,最多支持配置5套游戏闪屏。
闪屏图片 制作规范:
横屏:
ourpalm_gamelogo_landscape1.png
ourpalm_gamelogo_landscape2.png
ourpalm_gamelogo_landscape3.png
ourpalm_gamelogo_landscape4.png
ourpalm_gamelogo_landscape5.png
注意:每套闪屏 都需要做三个尺寸的图片,一套闪屏 需要存放到4个目录中,以第一套为例:
res\drawable 存放 尺寸:1280x720 名称:ourpalm_gamelogo_landscape1.png 图片
res\drawable-xhdpi 存放 尺寸:1280x720 名称:ourpalm_gamelogo_landscape1.png 图片
res\drawable-xxhdpi 存放 尺寸:1920x1080 名称:ourpalm_gamelogo_landscape1.png 图片
res\drawable-xxxhdpi 存放 尺寸:2560x1440 名称:ourpalm_gamelogo_landscape1.png 图片

竖屏:
ourpalm_gamelogo_portrait1.png
ourpalm_gamelogo_portrait2.png
ourpalm_gamelogo_portrait3.png
ourpalm_gamelogo_portrait4.png
ourpalm_gamelogo_portrait5.png
注意:每套闪屏 都需要做三个尺寸的图片,一套闪屏 需要存放到4个目录中,以第一套为例:
res\drawable 存放 尺寸:720x1280 名称:ourpalm_gamelogo_portrait1.png 图片
res\drawable-xhdpi 存放 尺寸:720x1280 名称:ourpalm_gamelogo_portrait1.png 图片
res\drawable-xxhdpi 存放 尺寸:1080x1920 名称:ourpalm_gamelogo_portrait1.png 图片
res\drawable-xxxhdpi 存放 尺寸:1440x2560 名称:ourpalm_gamelogo_portrait1.png 图片

4 接入BASE SDK注意事项

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

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

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

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

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

  1. Ourpalm_Entry.getInstance(this).Ourpalm_onPause()
  2. Ourpalm_Entry.getInstance(this).Ourpalm_onRestart()
  3. Ourpalm_Entry.getInstance(this).Ourpalm_onResume()
  4. Ourpalm_Entry.getInstance(this).Ourpalm_onStart()
  5. Ourpalm_Entry.getInstance(this).Ourpalm_onStop()
  6. Ourpalm_Entry.getInstance(this).Ourpalm_onDestroy()
  7. Ourpalm_Entry.getInstance(this).Ourpalm_onActivityResult()
  8. Ourpalm_Entry.getInstance(this).Ourpalm_onConfigurationChanged()
  9. Ourpalm_Entry.getInstance(this).Ourpalm_onNewIntent()

4.4调用支付接口需要注意内容

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

5 导入BASE SDK

5.1 res中资源和lib库的导入

方式一:游戏工程直接引用《OurpalmAndroid_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 权限配置

  1. <!-- OurpalmSDK需要的权限 -->
  2. <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  3. <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
  4. <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
  5. <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
  6. <uses-permission android:name="android.permission.INTERNET" />
  7. <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
  8. <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

5.2.2 其他必须配置项

  1. <manifest xmlns:android="http://schemas.android.com/apk/res/android"
  2. package="our.test.base.demo"
  3. android:installLocation="auto"
  4. android:versionCode="1"
  5. android:versionName="1.0.1" >
  6. <!-- 如游戏本身有Application类,则需要在代码中继承ourpalm.android.channels.Info.Ourpalm_Channels_Application;如游戏本身没有Application类,则需要在此添加配置,将AndroidManifest.xml中application的名字命名为"ourpalm.android.channels.Info.Ourpalm_Channels_Application" -->
  7. <application android:name="ourpalm.android.channels.Info.Ourpalm_Channels_Application"
  8. android:allowBackup="true"
  9. android:icon="@drawable/ic_launcher"
  10. android:label="@string/app_name"
  11. android:theme="@style/AppTheme" >
  12. <!-- 客服反馈功能的Activity V3.1.7新增加 -->
  13. <activity
  14. android:name="ourpalm.android.opservice.Ourpalm_OpService_Activity"
  15. android:configChanges="keyboardHidden|orientation|screenSize"
  16. android:theme="@android:style/Theme.Translucent.NoTitleBar" >
  17. </activity>
  18. <!-- 打开指定页面Activity V3.4.0版本新增加-->
  19. <activity
  20. android:name="ourpalm.android.view.Ourpalm_WebView_Activity"
  21. android:configChanges="keyboardHidden|orientation|screenSize"
  22. android:screenOrientation="sensor"
  23. android:theme="@android:style/Theme.Translucent.NoTitleBar" >
  24. </activity>
  25. <!-- BASE SDK中上传崩溃日志的服务 V3.1.9版本新增加 -->
  26. <service
  27. android:name="ourpalm.android.c.Ourpalm_CrashService"
  28. android:process=":ourpalmCrash" >
  29. <intent-filter>
  30. <action android:name="ourpalm.UpCrashLog" />
  31. </intent-filter>
  32. </service>
  33. <!-- 游戏自己的启动activity类名,需要完整路径,必须配置 -->
  34. <meta-data
  35. android:name="ourpalm_class_name"
  36. android:value="com.ourpalm.test_ourpalm_v3.MainActivity" />
  37. <!-- 游戏请配置自己游戏的展示类型,竖屏游戏请配置成 portrait,横屏游戏请配置成landscape -->
  38. <meta-data
  39. android:name="ourpalm_screenOrientation"
  40. android:value="landscape" />
  41. <meta-data
  42. android:name="ourpalm_gametype_console"
  43. android:value="false" />
  44. </application>

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

5.2.3 可选配置项

  1. <!-- 闪屏配置,如使用此配置,请将游戏原启动activity的android.intent.category.LAUNCHER修改为android.intent.category.DEFAULT -->
  2. <activity
  3. android:name="ourpalm.android.logo.Ourpalm_LogoScreen_Activity"
  4. android:configChanges="orientation|keyboardHidden|screenSize|screenLayout"
  5. android:screenOrientation="landscape"
  6. android:theme="@android:style/Theme.NoTitleBar" >
  7. <intent-filter>
  8. <action android:name="android.intent.action.MAIN" />
  9. <category android:name="android.intent.category.LAUNCHER" />
  10. </intent-filter>
  11. </activity>
  12. <!-- 闪屏默认配置 -->
  13. <meta-data
  14. android:name="ourplam_logo_flag"
  15. android:value="1" />
  16. <!-- 闪屏时间为 2S -->
  17. <meta-data
  18. android:name="ourplam_logotime"
  19. android:value="2000" />

6 登录相关接口介绍

6.1 流程介绍

SDK登录流程图
1 手机游戏客户端会调用掌趣sdk进行sdk初始化操作
2 掌趣sdk向掌趣用户中心服务器发起登录/注册的请求
3 掌趣用户中心服务器向掌趣sdk返回token、用户信息等等
4 掌趣sdk向返回游戏客户单登录结果和用户信息
5 游戏客户端上传用户信息到游戏服务器
6 服务器根据token向掌趣用户中心服务器获取用户信息
7 掌趣用户中心服务器向游戏服务器返回用户信息
8 游戏服务器向游戏客户端返回登录结果

6.2 SDK初始化接口

6.2.1 功能说明

  1. 为SDK中各个功能的使用提供必要的准备工作。
  2. 获取初始化数据。
  3. 检查版本更新。
  4. 发送激活日志。
  5. 初始化第三方SDK。

6.2.2 接口定义

  1. /**
  2. * 初始化SDK
  3. *
  4. * @param gameType
  5. * 游戏类型 1:网游;2:单机
  6. * @param gameVer
  7. * 游戏版本号
  8. * @param gameResVer
  9. * 游戏资源版本号,无资源版本号可传""
  10. * @param listener
  11. * 回调接口
  12. **/
  13. public void Ourpalm_Init(String gameType, String gameVer, String gameResVer, Ourpalm_CallBackListener listener)

6.2.3 参数说明

参数名称 是否必传 类型 说明
gameType 必须 String 游戏类型,GameInfo.GameType_Online表示网游,GameInfo.GameType_Console表示单机。
gameVer 可选 String SDK优先读取AndroidManifest.xml里面的版本号,如未获取到则使用此参数。
gameResVer 可选 String 游戏资源版本号,如游戏无此概念则可以传null。
listener 必须 Ourpalm_CallBackListener 游戏需实现此回调中的所有接口。

6.2.4 接口实例

  1. // 初始化SDK
  2. Ourpalm_Entry.getInstance(this).Ourpalm_Init("1", gameVer, gameResVer, new Ourpalm_CallBackListener() {
  3. @Override
  4. public void Ourpalm_LogoutSuccess() {
  5. // TODO Auto-generated method stub
  6. // 当前渠道带有注销功能的话由游戏实现,如返回到登录界面。
  7. // 单机游戏不用实现
  8. }
  9. @Override
  10. public void Ourpalm_LogoutFail(int code) {
  11. // TODO Auto-generated method stub
  12. // 当前渠道带有注销功能的话由游戏实现
  13. // 单机游戏不用实现
  14. }
  15. @Override
  16. public void Ourpalm_LoginSuccess(String tokenId, String data) {
  17. // TODO Auto-generated method stub
  18. // 登录成功回调,网络游戏必须实现
  19. // 单机游戏不用实现
  20. }
  21. @Override
  22. public void Ourpalm_LoginFail(int code) {
  23. // TODO Auto-generated method stub
  24. // 登录失败回调,网络游戏必须实现
  25. // 单机游戏不用实现
  26. }
  27. @Override
  28. public void Ourpalm_InitSuccess() {
  29. // TODO Auto-generated method stub
  30. // 待SDK的初始化完成后,游戏开始实现游戏本身的初始化
  31. // 初始化游戏
  32. }
  33. @Override
  34. public void Ourpalm_InitFail(int code) {
  35. // TODO Auto-generated method stub
  36. // SDK初始化失败的回调,游戏可以在这里实现自己的逻辑处理,可以只提示用户后退出游戏,也可以继续游戏,但SDK的某些功能可能会受到影响
  37. }
  38. @Override
  39. public void Ourpalm_ExitGame() {
  40. // TODO Auto-generated method stub
  41. // 游戏使用掌趣SDK退出接口时必须实现此回调,在此处实现退出游戏的功能。
  42. MainActivity.this.finish();
  43. // android.os.Process.killProcess(android.os.Process.myPid());
  44. }
  45. @Override
  46. public void Ourpalm_SwitchingAccount(boolean Success, String tokenId, String userInfo) {
  47. // TODO Auto-generated method stub
  48. // 当前渠道带有切换账号功能时,游戏需要实现此接口逻辑进行游戏登录。切换账号分2种情况:
  49. // 一是调用SDK的切换账号接口实现账号的切换,此类型的切换账号按钮是由游戏去实现,建议放到登录界面,切换账号成功后,登录数据会在此接口返回,游戏可执行游戏的登录流程,类似登录成功接口的回调。
  50. // 二是渠道SDK的悬浮框或者用户中心页面带有切换账号功能,如用户点击切换账号并登录成功后,登录数据会在此接口返回,但如果当前游戏场景处于游戏中,游戏正常应该先返回到登录界面,然后再通过SDK切换账号成功返回的数据执行游戏的登录流程(游戏能在游戏中直接实现账号切换,人物改变的除外,不需返回登录界面)。
  51. // Success=true表示切换成功,Success=false表示切换失败,tokenId和userInfo同登录成功接口
  52. // 单机游戏不用实现
  53. }
  54. });

6.2.5 回调接口说明

  1. 登陆注销成功:public void Ourpalm_LogoutSuccess();
  2. 登陆注销失败:public void Ourpalm_LogoutFail(int code);
  3. 登陆成功:public void Ourpalm_LoginSuccess(String tokenId, String data);
  4. 登陆失败:public void Ourpalm_LoginFail(int code);
  5. 初始化成功:public void Ourpalm_InitSuccess();
  6. 初始化失败:public void Ourpalm_InitFail(int code);
  7. 退出游戏:public void Ourpalm_ExitGame();
  8. 切换账号回调:public void Ourpalm_SwitchingAccount(boolean Success,
  9. String tokenId, String userInfo);

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

6.3 登录接口

6.3.1 功能说明

调用第三方SDK的登陆功能。
当为官网包时会自动调用掌趣官网登陆界面。

6.3.2 接口定义

  1. /**
  2. * 登陆接口
  3. */
  4. public void Ourpalm_Login();

6.3.3 接口实例

  1. Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_Login();

6.3.4 登录成功回调说明

  1. public void Ourpalm_LoginSuccess(String tokenId, String data)

6.3.4.1 参数说明

参数名称 重要性 类型 说明
tokenId 必须 String 掌趣用户中心返回的当前登陆用户的tokenId,游戏客户需将此参数的值传给游戏服务器,游戏服务器需来掌趣用户中心进行登陆验证,验证通过才能让用户进入游戏,详看服务器登陆验证接口。
data 必须 String 当前登陆用户的用户信息数据,json格式

6.3.4.2 数据说明

  1. tokenId == 45bf7d3b-5041-451d-b660-b872ba4c831d
  2. data == {"id":"0101540000000000000000000000000623530796","userName":"oPlat000000001000047","returnJson":{"ErrorCode":"1","ErrorDesc":"有效"}}
  3. id:掌趣用户中心生成的用户ID,游戏应以此ID作为用户登陆的唯一标识。
  4. userName:掌趣用户中心生成的用户名称。
  5. returnJson:第三方用户系统返回给掌趣用户中心的数据,不同渠道返回的数据会有所不同,游戏根据情况酌情使用,不需要的话可以不取。

6.3.5 登录失败回调说明

  1. public void Ourpalm_LoginFail(int code)

6.3.5.1 参数说明

参数名称 重要性 类型 说明
code 必须 int 错误码详情 请查看错误码列表

6.4 注销

6.4.1 功能说明

注销当前登陆账号,注销成功后会调用游戏实现功能后的注销回调接口。
客户端需要根据Ourpalm_GetEnableInterface 返回值,判断是否需要展示UI和调用此接口

6.4.2 接口定义

  1. /**
  2. * 登陆注销
  3. */
  4. public void Ourpalm_Logout()

6.4.3 接口实例

  1. Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_Logout();

6.5 切换账号

6.5.1 功能说明

某些渠道SDK当登陆过一次后下次登陆会变成自动登陆,这个时候如果SDK内部没有注销或者切换账号的按钮,需要游戏调用此接口实现账号切换功能。
客户端需要根据Ourpalm_GetEnableInterface 返回值,判断是否需要展示UI和调用此接口

6.5.2 接口定义

  1. /**
  2. * 账号切换
  3. */
  4. public void Ourpalm_SwitchAccount();

6.5.3 接口实例

  1. Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_SwitchAccount();

6.6 设置角色信息

6.6.1 功能说明

成功登录并进入游戏后,游戏客户端必须调用此接口设置用户的角色信息,角色信息在其他功能接口中需要用到,如未调用则无法使用支付功能。用户首次创建或注册角色并登录时,需要调用一次注册设置(type=1)和一次登录设置(type=2);用户使用老角色登录,则只需要调用一次登录设置(type=2)。
注意:
1.游戏内没有角色注册行为的,在游戏自动给用户创建角色的时候,即认为注册。
2.用户首次创建或注册角色并登录时,需先调用注册设置(type=1),再调用登录设置(type=2)

6.6.2 接口定义

  1. /**
  2. * 设置游戏角色信息
  3. * @param type
  4. * 1:角色注册,2:角色登录
  5. * @param gameServerName
  6. * 当前角色所属服务器名称
  7. * @param gameServerId
  8. * 当前角色所属服务器ID
  9. * @param roleName
  10. * 当前角色名字
  11. * @param roleId
  12. * 当前角色ID
  13. * @param rolelv
  14. * 当前角色等级,无等级可传""
  15. * @param roleViplv
  16. * 当前角色VIP等级,无VIP等级可传""
  17. *
  18. */
  19. public void Ourpalm_SetGameInfo(int type, String gameServerName,
  20. String gameServerId, String roleName, String roleId,
  21. String rolelv,String roleViplv)

6.6.3 接口实例

  1. Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_SetGameInfo(1, "服务器名称", "服务器ID", "测试角色名称", "测试角色ID", "测试角色等级", "测试角色VIP等级");

6.6.4 参数说明

参数名称 重要性 类型 说明
type 必须 int 1表示角色注册,2表示角色登录
gameServerName 必须 String 当前用户所在游戏服务器名称
gameServerId 必须 String 当前用户所在游戏服务器ID
roleName 必须 String 当前角色名称(不支持富文本)
roleId 必须 String 当前角色ID
rolelv 必须 String 当前角色等级,如无可传””
roleViplv 必须 String 当前角色VIP等级,如无可传””

6.7 设置绑定账户回调(非必须)

6.7.1 功能说明

绑定官网账户的回调,游戏如果有需要绑定结果可以设置,不需要可以不使用该接口。

6.7.2 接口定义

  1. /**
  2. * 绑定账号结果回调 韩国需求使用,可能会和登录成功 或者其他回调 同时触发
  3. *
  4. * @param listener
  5. */
  6. public void SetOurpalm_AccountBindListener(Ourpalm_AccountBindListener listener)

6.7.3 接口实例

  1. Ourpalm_Entry.getInstance(this).SetOurpalm_AccountBindListener(new Ourpalm_AccountBindListener() {
  2. @Override
  3. public void Ourpalm_AccountBindSuccess(String tokenId, String userInfo) {
  4. // TODO Auto-generated method stub
  5. Logs.i("info", "Ourpalm_AccountBindSuccess, tokenId == " + tokenId + " userInfo = " + userInfo);
  6. Toast.makeText(MainActivity.this, "通知游戏绑定成功", Toast.LENGTH_LONG).show();
  7. }
  8. @Override
  9. public void Ourpalm_AccountBindFail(int code) {
  10. // TODO Auto-generated method stub
  11. Logs.i("info", "Ourpalm_AccountBindFail,");
  12. Toast.makeText(MainActivity.this, "通知游戏绑定失败", Toast.LENGTH_LONG).show();
  13. }
  14. @Override
  15. public void Ourpalm_AccountBindCancel() {
  16. // TODO Auto-generated method stub
  17. Logs.i("info", "Ourpalm_AccountBindCancel,");
  18. Toast.makeText(MainActivity.this, "通知游戏绑定取消", Toast.LENGTH_LONG).show();
  19. }
  20. });

6.7.4 回调接口说明(Ourpalm_AccountBindListener)

6.7.4.1 绑定成功回调

  1. /**
  2. * 绑定账号成功
  3. *
  4. * @param tokenId
  5. * 用户绑定账号返回的tokenid
  6. *
  7. * @param userInfo
  8. * 绑定账号后返回的用户信息
  9. */
  10. public abstract void Ourpalm_AccountBindSuccess(String tokenId, String userInfo);

6.7.4.1 绑定失败回调

  1. /**
  2. * 绑定失败
  3. *
  4. * @param code
  5. * 错误标识
  6. */
  7. public abstract void Ourpalm_AccountBindFail(int code);

6.7.4.1 绑定取消回调

  1. /**
  2. * 绑定取消
  3. */
  4. public abstract void Ourpalm_AccountBindCancel();

6.7.5 成功回调参数说明

6.7.5.1 参数说明

参数名称 重要性 类型 说明
tokenId 必须 String 掌趣用户中心返回的当前登陆用户的tokenId,游戏客户需将此参数的值传给游戏服务器,游戏服务器需来掌趣用户中心进行登陆验证,验证通过才能让用户进入游戏,详看服务器登陆验证接口。
userInfo 必须 String 当前登陆用户的用户信息数据,json格式

6.7.5.2 数据说明

  1. tokenId == 45bf7d3b-5041-451d-b660-b872ba4c831d
  2. userInfo == {"id":"0101540000000000000000000000000623530796","userName":"oPlat000000001000047","returnJson":{"ErrorCode":"1","ErrorDesc":"有效"}}
  3. id:掌趣用户中心生成的用户ID,游戏应以此ID作为用户登陆的唯一标识。
  4. userName:掌趣用户中心生成的用户名称。
  5. returnJson:第三方用户系统返回给掌趣用户中心的数据,不同渠道返回的数据会有所不同,游戏根据情况酌情使用,不需要的话可以不取。

7 计费相关接口介绍

7.1 流程介绍

SDK计费流程
1 base sdk向掌趣计费中心发起支付请求;
2 掌趣计费中心生成订单号,并向base sdk返回支付结果;
3 掌趣计费中心通知游戏服务器发货;
4 游戏服务器发送虚拟物品至玩家手机游戏客户端;
5 游戏服务器向计费中心返回发货结果;

7.2 支付接口

7.2.1 功能说明

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

7.2.2 接口定义

  1. /**
  2. *
  3. * @param propId
  4. * 游戏自定义的商品ID
  5. * @param chargeCash
  6. * 商品价格
  7. * @param currencyType
  8. * 货币类型(1人民币2美元3日元4港币5英镑6新加坡币7越南盾8台币9韩元10泰铢)
  9. * @param propName
  10. * 商品名称
  11. * @param propCount
  12. * 商品数量
  13. * @param propDes
  14. * 商品描述
  15. * @param Gameurl
  16. * 掌趣计费中心回调游戏发货地址
  17. * @param ExtendParams
  18. * 扩展参数
  19. * @param callBack
  20. * 支付回调接口
  21. * @param rolelv
  22. * 角色等级
  23. * @param roleviplv
  24. * 角色VIP等级
  25. */
  26. public void Ourpalm_Pay(final String propId, final String chargeCash, final String currencyType,final String propName, final String propCount, final String propDes, final String Gameurl,final String ExtendParams, final Ourpalm_PaymentCallBack callBack, final String rolelv,final String roleviplv)

7.2.3 参数说明

参数名称 重要性 类型 说明
propId 必须 String 游戏自定义的道具ID 必传。
chargeCash 必须 String 道具价格,单位为分。
currencyType 必须 String 货币类型(1人民币2美元3日元4港币5英镑6新加坡币7越南盾8台币9韩元)
propName 必须 String 道具名称
propCount 必须 String 道具数量
propDes 必须 String 道具描述
Gameurl 可选 String 游戏发放道具服务器地址,用户支付成功后掌趣计费中心会回调此地址告知游戏进行道具发放。
(如果游戏客户端未传此参数,则计费中心使用在平台配置的回调地址进行发货)
ExtendParams 可选 String 游戏自定义数据,支付成功后,计费中心会将此字段数据回传给游戏服务器。
callBack 必须 Ourpalm_PaymentCallBack 客户端回调类
rolelv 必须 String 角色等级,请传数字,如游戏中无角色等级可以传null
roleviplv 必须 String 角色VIP等级,请传数字,如游戏中无角色VIP等级可以传null

7.2.4 接口实例

  1. Ourpalm_Entry.getInstance(this).Ourpalm_Pay("商品ID", "100", "1", "商品名称", "1", "商品描述", "回调地址", "我是扩展参数",
  2. new Ourpalm_PaymentCallBack() {
  3. @Override
  4. public void Ourpalm_PaymentSuccess(int code, String ssid, String pbid) {
  5. // TODO Auto-generated method stub
  6. Logs.i("info", "Ourpalm_PaymentSuccess ssid == " + ssid + " , pbid = " + pbid);
  7. Toast.makeText(mContext, "花钱成功了。。。*_*", Toast.LENGTH_SHORT).show();
  8. }
  9. @Override
  10. public void Ourpalm_PaymentFail(int code, String ssid, String pbid) {
  11. // TODO Auto-generated method stub
  12. Logs.i("info", "Ourpalm_PaymentFail code = " + code + "ssid == " + ssid + " , pbid = " + pbid);
  13. Toast.makeText(mContext, "支付失败了", Toast.LENGTH_SHORT).show();
  14. }
  15. @Override
  16. public void Ourpalm_OrderSuccess(int code, String ssid, String pbid) {
  17. // TODO Auto-generated method stub
  18. Toast.makeText(mContext, "下单成功了", Toast.LENGTH_SHORT).show();}
  19. }, RoleLv, RoleVipLv);

7.2.5 回调接口说明(Ourpalm_PaymentCallBack)

7.2.5.1 支付成功

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

7.2.5.2 支付失败

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

7.2.5.3 下单成功

  1. /* "下单成功"表示当前订单已经成功提交,但用户是否进行支付,以计费中心服务器的通知为准。 下单成功代表支付流程结束。下单成功回调触发以后不会在有支付成功和支付失败的回调,游戏需要根据服务器通知为准。*/
  2. public void Ourpalm_OrderSuccess(int code, String ssid, String pbid);

7.2.6 回调参数说明

参数名称 重要性 类型 说明
code 必须 int 结果状态说明
ssid 必须 string 掌趣计费中心生成的订单号,如支付失败或者用户取消支付时可能返回为空。
pdid 必须 string 游戏自定义id

8 客服反馈相关

8.1 客户反馈接口

8.1.1 功能说明

游戏登录成功后,调用此接口,打开客服反馈页面
游戏需要自己设计UI展示以及展示位置,当用户点击此按钮时,调用接口,打开客服反馈页面。

8.1.2 接口定义

  1. /**
  2. * 进入客服反馈页面
  3. */
  4. public void EnterServiceQuestion();

8.1.3 接口实例

  1. Ourpalm_OpService_Entry.getInstance().EnterServiceQuestion();

8.2 查询客服是否有新的回复(客户端调用 可选)

8.2.1 功能说明

登录成功后调用,查询用户在客服反馈提交的问题是否有新的回复。

8.2.2 接口定义

  1. /**
  2. * 查看是否有新的问题回复
  3. * @param listener 回调接口
  4. */
  5. public void GetNewReplyInfo(final OurpalmOpServiceCallBack opServiceListener);

8.2.3 接口实例

  1. Ourpalm_OpService_Entry.getInstance().GetNewReplyInfo(new OurpalmOpServiceCallBack() {
  2. @Override
  3. public void Ourpalm_OpServiceResult(int resultcode) {
  4. // TODO Auto-generated method stub
  5. if (resultcode == 0) {
  6. //获取到客服回复
  7. } else if (resultcode == 1) {
  8. //没有获取到回复
  9. } else {
  10. // 其他未知错误
  11. }
  12. }
  13. });

8.2.4 回调接口参数说明

Ourpalm_OpServiceResult 返回值说明

参数名称 类型 说明
resultcode int 0: 有新的问题回复
1:没有新的问题回复
2:网络请求异常

9 礼包兑换相关

9.1 礼包码兑换接口

9.1.1 功能说明

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

9.1.2 接口定义

  1. /**
  2. * 礼包码兑换接口
  3. * @param GiftCode 礼包码
  4. * @param url 发货地址
  5. * @param extendParams 扩展参数
  6. * @param mListener 回调
  7. */
  8. public void Ourpalm_GiftExchange(String GiftCode, String url,final String extendParams,final Ourpalm_GiftExchangeCallBack mListener);

9.1.3 参数说明

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

9.1.4 接口实例

  1. Ourpalm_Entry.getInstance(this).Ourpalm_GiftExchange("用户输入的礼包码", "游戏发货服务器地址", "透传参数",new Ourpalm_GiftExchangeCallBack());

9.1.5 回调接口说明

9.1.5.1 兑换成功回调

  1. /**
  2. * 操作成功
  3. * packageId 礼包码ID
  4. * extendParams 游戏透传参数(游戏传进来的透传参数)
  5. */
  6. public void Ourpalm_Success(String packageId, String extendParams);

9.1.5.2 兑换失败回调

  1. /*
  2. * 操作失败
  3. * @param code
  4. * 错误码
  5. */
  6. public abstract void Ourpalm_Fail(int code);

10 推送相关

10.1 获取推送token

10.1.1 功能说明

获取服务器推送token

10.1.2 接口定义

  1. /**
  2. * 获取推送token
  3. *
  4. * @param callbasck
  5. * 回调游戏推送token
  6. */
  7. public void Ourpalm_GetPushToken(Ourpalm_PushCallBack callbasck);

10.1.3 接口实例

  1. // 获取推送touken
  2. Ourpalm_Entry.getInstance(mMainActivity).Ourpalm_GetPushToken(new Ourpalm_PushCallBack() {
  3. @Override
  4. public void Success(String value) {
  5. // TODO Auto-generated method stub
  6. JSONObject pushJson;
  7. String PushToken = null;
  8. try {
  9. pushJson = new JSONObject(value);
  10. PushToken = pushJson.getString("pushtoken");
  11. } catch (JSONException e) {
  12. // TODO Auto-generated catch block
  13. e.printStackTrace();
  14. }
  15. //获取成功 推送token为 PushToken
  16. }
  17. @Override
  18. public void Fail(String msg) {
  19. // TODO Auto-generated method stub
  20. //获取失败
  21. }
  22. });

10.1.4 回调接口说明(Ourpalm_PushCallBack )

10.1.4.1 获取成功回调

  1. /**
  2. * 回调游戏推送token
  3. * @param value
  4. * json 格式 {"pushtoken":"xxxxxxxxxxx"}
  5. *
  6. */
  7. public abstract void Success(String value);

pushJson = new JSONObject(value);
PushToken = pushJson.getString(“pushtoken”);

10.1.4.2 获取失败回调

  1. /**
  2. * 获取失败
  3. * @param msg
  4. * 失败描述
  5. */
  6. public abstract void Fail(String msg);

msg:错误原因。

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

11.1 功能说明

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

11.2 接口介绍

11.2.1 onStart 接口示例

  1. @Override
  2. protected void onStart() {
  3. // TODO Auto-generated method stub
  4. super.onStart();
  5. Ourpalm_Entry.getInstance(this).Ourpalm_onStart();
  6. }

11.2.2 onResume 接口示例

  1. @Override
  2. protected void onResume() {
  3. // TODO Auto-generated method stub
  4. super.onResume();
  5. Ourpalm_Entry.getInstance(this).Ourpalm_onResume();
  6. }

11.2.3 onPause 接口示例

  1. @Override
  2. protected void onPause() {
  3. // TODO Auto-generated method stub
  4. super.onPause();
  5. Ourpalm_Entry.getInstance(this).Ourpalm_onPause();
  6. }

11.2.4 onStop 接口示例

  1. @Override
  2. protected void onStop() {
  3. // TODO Auto-generated method stub
  4. super.onStop();
  5. Ourpalm_Entry.getInstance(this).Ourpalm_onStop();
  6. }

11.2.5 onRestart 接口示例

  1. @Override
  2. protected void onRestart() {
  3. // TODO Auto-generated method stub
  4. super.onRestart();
  5. Ourpalm_Entry.getInstance(this).Ourpalm_onRestart();
  6. }

11.2.6 onDestroy 接口示例

  1. @Override
  2. protected void onDestroy() {
  3. // TODO Auto-generated method stub
  4. super.onDestroy();
  5. Ourpalm_Entry.getInstance(this).Ourpalm_onDestroy();
  6. }

11.2.7 onDestroy 接口示例

  1. @Override
  2. protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  3. // TODO Auto-generated method stub
  4. super.onActivityResult(requestCode, resultCode, data);
  5. Ourpalm_Entry.getInstance(this).Ourpalm_onActivityResult(requestCode, resultCode, data);
  6. }

11.2.8 onConfigurationChanged 接口示例

  1. @Override
  2. public void onConfigurationChanged(Configuration newConfig) {
  3. // TODO Auto-generated method stub
  4. super.onConfigurationChanged(newConfig);
  5. Ourpalm_Entry.getInstance(this).Ourpalm_onConfigurationChanged(newConfig);
  6. }

11.2.9 onNewIntent调用示例

  1. @Override
  2. protected void onNewIntent(Intent intent) {
  3. // TODO Auto-generated method stub
  4. super.onNewIntent(intent); Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_onNewIntent(intent);
  5. }

12 其他功能接口

12.1 获取可选接口中的可用接口

12.1.1 功能说明

“用户中心”,“切换账号”,“登录注销”等接口必须接入。
提供此接口用来引导游戏合理使用以上三个接口。根据SDK返回的值,判断是否在相应渠道客户端中显示或隐藏UI展示,以及和是否调用以上三个接口。
比如当前渠道需要调用用户中心接口,则需要将用户中心按钮显示出来并实现其接口调用的功能,如不需要,则需要隐藏用户中心的按钮。其他功能同理。
此三个功能SDK只提供功能接口,无UI显示,所以需要游戏实现展示或者隐藏“用户中心”,“切换账号”,“登录注销”的UI按钮。根据返回值给予显示或者隐藏。

12.1.2 接口定义

  1. /**
  2. * 获取当前渠道游戏包是否要调用“用户中心”,“切换账号”,“登陆注销”等接口
  3. */
  4. public String Ourpalm_GetEnableInterface()

12.1.3 接口示例

  1. String enable = Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_GetEnableInterface();

12.1.4 返回数据解析

  1. {"Logout":"Disabled","SwitchAccount":"Disabled","UserCenter":"Enabled"}
  2. Enabled: 表示需要调用
  3. Disabled: 表示不需要调用
  4. 例如以上返回数据说明:登陆注销接口不需要调用;切换账号接口不需要调用,进入用户中心接口需要调用。

12.2 进入用户中心或论坛接口

12.2.1 功能说明

进入第三方渠道SDK的用户中心或者论坛界面,或者进入官网SDK的用户中心界面。
客户端调用,根据第三方渠道SDK要求来决定是否调用

12.2.2 接口定义

  1. /**
  2. * 进入用户中心接口,如果是用官网登陆的则进入官网的用户中心
  3. */
  4. public void Ourpalm_GoCenter()

12.2.3 接口示例

  1. Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_GoCenter();

12.3 退出游戏接口

12.3.1 功能说明

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

12.3.2 接口定义

  1. /**
  2. * 调用第三方SDK退出提示页面,如果第三方SDK无退出提示页面则调用掌趣提示页面
  3. * @param usetip
  4. * 是否使用掌趣SDK的退出提示界面
  5. */
  6. public void Ourpalm_ExitGame(boolean usetip)

12.3.3 参数说明

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

12.3.4 接口示例

  1. @Override
  2. public boolean onKeyDown(int keyCode, KeyEvent event) {
  3. // TODO Auto-generated method stub
  4. if (keyCode == KeyEvent.KEYCODE_BACK) {
  5. Ourpalm_Entry.getInstance(this).Ourpalm_ExitGame(true);
  6. return true;
  7. }
  8. return super.onKeyDown(keyCode, event);
  9. }

12.4 开启SDK日志输出

12.4.1 功能说明

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

12.4.2 接口定义

  1. /**
  2. * 是否打开日志
  3. * @param log 是否打开日志输出
  4. */
  5. public void SetLogs(boolean log)

12.4.3 参数说明

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

12.4.4 接口示例

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

12.5 获取ServiceId

12.5.1 功能说明

获取当前游戏包中的ServiceId。

12.5.2 接口定义

  1. /**
  2. * @return 业务ID
  3. *
  4. public String getServiceId();

12.5.3 接口示例

  1. Ourpalm_Entry.getInstance(this).getServiceId();

12.6 获取渠道ID

12.6.1 功能说明

获取当前游戏包内打入的渠道ID。

12.6.2 接口定义

  1. /**
  2. * @return 渠道ID
  3. *
  4. public String getChannelId();

12.6.3 接口示例

  1. Ourpalm_Entry.getInstance(this).getChannelId();

12.7 获取机型组ID

12.7.1 功能说明

获取当前游戏包内打入的机型组ID。

12.7.2 接口定义

  1. /**
  2. * @return 机型组ID
  3. */
  4. public String getDeviceGroupId();

12.7.3 接口示例

  1. Ourpalm_Entry.getInstance(this).getDeviceGroupId();

12.8 获取语言ID

12.8.1 功能说明

获取当前游戏包内打入的语言ID。

12.8.2 接口定义

  1. /**
  2. * @return 语言ID
  3. */
  4. public String getLocaleId();

12.8.3 接口示例

  1. Ourpalm_Entry.getInstance(this).getLocaleId();

12.9 获取OPID

12.9.1 功能说明

获取当前游戏包内打入的OPID。

12.9.2 接口定义

  1. /**
  2. * @return OPID
  3. */
  4. public String getOpId();

12.9.3 接口示例

  1. Ourpalm_Entry.getInstance(this).getOpId();

12.10 获取ServiceCode

12.10.1 功能说明

1.需要先调用初始化接口Ourpalm_Init后 再调用 本接口获取 ServiceCode;
2.游戏研发人员 获取ServiceCode后,联系掌趣服务器端同学联调服务端日志,获取ServiceCode接入工作正式完成。

12.10.2 接口定义

  1. /**
  2. * 获取ServiceCode
  3. * @param gameResVer
  4. * 游戏资源版本号,无资源版本号可传""
  5. *
  6. * @return 返回ServiceCode
  7. */
  8. public String Ourpalm_getServiceCode(final String gameResVer);

12.10.3 接口实例

  1. // 获取掌趣serviceCode接口,游戏需要调用(SDK接口)
  2. Ourpalm_ServiceCode_Entry.getInstance(this).Ourpalm_getServiceCode("资源版本号");

12.11 开启ServiceCode Debug日志输出

12.11.1 功能说明

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

12.11.2 接口定义

  1. /**
  2. * 是否打开日志
  3. *
  4. * @param log
  5. */
  6. public void SetLogs(boolean log)

12.11.3 接口实例

  1. // 设置打开日志输出,出正式包时务必注释掉,或者传false
  2. Ourpalm_ServiceCode_Entry.getInstance(this).SetLogs(true);

12.12 打开指定页面(可用于论坛、社区、活动)

12.12.1 功能说明

打开指定url的web页面接口(可用于论坛、社区、活动)。

12.12.2 接口定义

  1. /**
  2. * 加载指定URL的Web页面
  3. *
  4. * @param webUrl
  5. * 页面URL
  6. *
  7. * @author lgc 2018年04月11日 上午11:17:52
  8. */
  9. public void Ourpalm_OpenSpecificWebView(String webUrl)

12.12.3 参数说明

参数名称 重要性 类型 说明
webUrl 必须 String web页面url

12.12.4 接口示例

  1. Ourpalm_Entry.getInstance(MainActivity.mMainActivity).
  2. Ourpalm_OpenSpecificWebView(
  3. "http://www.baidu.com");

13 附录 错误码列表

13.1 附1:客户端错误码

状态码 说明
-1 未知错误
-2 SDK联网URL错误
-3 第三方登陆验证返回失败
-4 支付失败,未知错误
-5 无网络
0 初始化失败
10 登陆错误,未知错误
11 登陆取消
12 登陆数据错误,账号或密码为空
13 登陆验证失败
14 登陆验证参数错误
15 获取系统用户名错误
16 单机隐式登录失败
20 注册失败,未知错误
21 注册失败,验证错误
22 注册数据错误,账号或密码为空
30 修改密码错误
31 修改密码错误,用户id或者密码为null或者格式错误
32 修改密码错误,参数错误
33 找回密码错误,参数错误
40 绑定用户信息错误
41 绑定用户信息错误,验证错误
42 绑定用户信息错误,参数错误
43 接口所需参数传递为空或者格式不正确
100 支付相关参数错误
101 支付成功
102 支付失败
103 支付取消
104 下单成功
105 下单失败
106 解析支付协议失败
107 当前支付方式不可用
205 账号封停
300 官网支付webview页面报错

13.2 附2:用户中心错误码

等待用户中心统计完

13.3 附3:计费中心错误码

等待用户中心统计完

13.4 附4:激活码领取错误码

状态码 说明
21185 激活码不得为空
21186 发货失败
21187 激活码不存在或不可用
21188 激活码已过期
21189 激活码未领取
21190 激活码已使用
21191 该用户已兑换过激活码
21192 该设备已兑换过激活码
21193 活动暂停中
21194 激活码已经用完
21195 网络异常
21196 服务内部错误
21197 传入的激活码有错误
21198 传入的礼包ID有错误
21199 用户未登录
21200 兑换超过用户最大限制
21201 游戏产品有误
21202 策略关系不存在
21203 联运渠道或推广渠道有误
21204 推广渠道有误
21205 机型组有误
21206 语言有误
21207 逻辑服策略不存在
21208 逻辑服有误
23157 礼包码未到生效时间

13.5 附5:货币类型及对应ID

在MIS中的货币有总共十种,货币ID是没有限定位数的纯自增值

货币ID 货币名 币单位
1 人民币
2 美元 美分
3 日元
4 港币
5 英镑 便士
6 新加坡币
7 越南盾
8 台币
9 韩元
10 泰铢 萨当