果盘SDK接入文档 for Android

### 一、文档说明

#### 1.1 功能描述
果盘 SDK 是一家专业的手游联运发行解决方案服务商，通过 SDK 账号系统、支付功能、福利系统、用户社区、聚合工具（包含智能客服系统、游戏加速功能等），为第三方应用程序提供便捷、安全以及可靠的服务。本文主要描述 SDK 支付接口的使用方法，供合作伙伴的开发者接入使用。

#### 1.2 阅读对象
本文档面向具有一定 Android 客户端开发能力，了解 Android 客户端的开发和管理人员。

#### 1.3 注意事项
- targetSdkVersion：支持 targetSdkVersion = 30。接入方需要把 targetSdkVersion 设置为 30。
- targetSdkVersion 设置为 30 后，apk 包签名需要支持 v2，否则在 Android 11 及以上的设备会安装失败。
- 如果已经接入 msa 库，请确保版本最高不超过 1.0.25，否则打包后，可能出现无法正常获取 oaid 的情况。

### 二、Android 客户端接入

#### 2.0 SDK基础信息

**果盘游戏SDK**

**开发者：**火烈鸟网络（广州）股份有限公司

**主要功能：**提供游戏联合运营的登录、⽀付、运营（社区）⽀持服务

**个人信息处理规则：** [《个人信息采集详情》](https://gpdoc.guopan.cn/project-3/doc-52/ "《个人信息采集详情》")[《果盘游戏SDK隐私政策》](https://gpdoc.guopan.cn/project-3/doc-50/ "《果盘游戏SDK隐私政策》")

**合规使用说明：**[《果盘游戏SDK合规使用说明》](https://gpdoc.guopan.cn/project-3/doc-51/ "《果盘游戏SDK合规使用说明》")

#### 2.1 SDK 资源下载

[果盘Android-SDK-v5.5.2.2.zip](/media/attachment/2025/06/果盘Android-SDK-v5.5.2.2.zip)

[安卓接入参考demo](/media/attachment/2025/06/GPDemo.zip)(仅作为参考，非正式运行程序)

#### 2.2 接入前工程配置
1、接入工程的包名的后缀应为`.guopan`（BT版应该是.bt.guopan），例如:`com.xx.game`应变为`com.xx.game.guopan`;

2、游戏安装包 icon 需加入果盘角标，角标源文件请在 SDK 文件夹的一级目录查收，角标样式如下：
![](http://pmrdoc01.rmz.flamingo-inc.com/media/202110//1634811634.5751693.png)

#### 2.3 开发环境配置

1、把`SDKFrameWork-release.aar`拷贝到项目的 libs 文件夹中；

2、在对应项目的 `build.gradle` （非根目录的 build.gradle）文件中添加依赖，如下：

```
dependencies {
    implementation files('libs/SDKFrameWork-release.aar')
}
```

#### 2.4 SDK 接口说明

概述：所有的接口都是异步调用，可以不需要新开线程。
特别注意，initSDK 初始化方法是其他所有接口的基础，如果 initSDK 没有成功，则后面的支付和用户接口都无法正常使用。
**必接接口**有初始化、登录、支付、退出、上报角色信息以及实名认证相关接口。

### 三、详细接口接入代码

#### 必接接口

- **获取sdk实例**（必须先调用此方法，获取到接口实例后，再调用初始化、登录、支付等接口）

```java
GPApiFactory.getGPApiForMarshmellow(this, new Callback() {
    @Override
    public void onCallBack(IGPApi igpApi) {
        // 回调之后才可调用初始化、登陆等接口
        // 获取实例
        mIGPApi = igpApi;
        ……
    }
});
```

- **初始化接口**

```java
/**
 * Context context
 * String appid  cp 申请的 appid
 * String appkey cp 申请的 appkey
 * IGPSDKInitObsv obsv 初始化接口回调（错误码，具体见下表）
 */
mIGPApi.initSdk(context, appid, appkey, obsv);
```

| 错误码 | 含义 |
| --- | --- |
|GPSDKInitResult.GPInitErrorCodeNone|初始化成功|
|GPSDKInitResult.GPInitErrorCodeNet|网络异常|
|GPSDKInitResult.GPInitErrorCodeConfig |appId,secret配置错误|
|GPSDKInitResult.GPInitErrorCodeNeedUpdate|游戏需更新（cp 方收到这个回调，无须做任何事情，不要当成初始化失败退出游戏，回调后sdk会自行引导更新）|

- **登录接口**

```java
/**
 * Context context
 * IGPUserObsv obsv 登录回调（错误码，具体见下表）
 */
mIGPApi.login(context, obsv);
```

| 错误码 | 含义 |
| --- | --- |
|GPUserResult.USER_RESULT_LOGIN_SUCC|登录成功|
|GPUserResult.USER_RESULT_LOGIN_FAIL|登录失败|

- **支付接口**

```java
/**
 * GPSDKGamePayment payParam
 * IGPPayObsv obsv 支付回调（错误码，具体见下表）
 */
/**
 * GPSDKGamePayment 相关参数定义
 * 
 * String mItemName 商品名称 （必填）
 * String mPaymentDes 订单描述信息 （必填字符数在2~到1000之间）
 * float mItemPrice 单个商品实际价格，保留两位小数（必填）
 * float mItemOrigPrice 单个商品原来价格，保留两位小数，默认为0，单位：元（必填）
 * String mItemId 商品编号id （必填）
 * int mItemCount 购买个数，不填写默认为1
 * String mSerialNumber 订单号，最大64位的字符串（必填）
 * Activity mCurrentActivity 当前的activity（必填）
 * String mReserved 非必须填,SDK不处理该字段,保留原字段传递到 游戏服务器
 * String mPlayerId 角色id（必填）
 * String mPlayerNickName 用户角色名（必填）
 * String mServerId 服务器id（多少服）（必填）
 * String mServerName 服务器名（什么服）（必填）
 * float mRate 游戏道具和人民币的比率（比如10个钻石只需要1元，那么就是10）（必填）
 */
mIGPApi.buy(payParam, obsv);
```

| 错误码 | 含义 |
| --- | --- |
|GPPayResult.GPSDKPayResultCodeSucceed|购买成功|
|GPPayResult.GPSDKPayResultCodeCancel|用户取消购买|
|GPPayResult.GPSDKPayResultCodeOtherError|其他问题购买失败|

- **角色上报接口**（请在登录成功后、创建角色、角色等级提升时调用）

```java
/**
 * GPSDKPlayerInfo playerInfo
 * IGPUploadPlayerInfoObsv obsv 上报角色信息回调（GPUploadPlayerInfoResult错误码，具体见下表）
 */
/**
 * GPSDKPlayerInfo 相关参数定义
 * 
 * String mGameLevel 角色等级 （必填）
 * String mPlayerId 角色id （必填）
 * String mPlayerNickName 角色名（必填）
 * String mServerId 服务器id （必填）
 * String mServerName 服务器 （必填）
 * int mType 上报时机（必填）——对应取值：GPSDKPlayerInfo.TYPE_CREATE_ROLE（创建角色）、GPSDKPlayerInfo.TYPE_ENTER_GAME（进入游戏）、GPSDKPlayerInfo.TYPE_LEVEL_UP（等级提升）、GPSDKPlayerInfo.TYPE_EXIT_GAME（退出游戏）
 * String mPartyName 帮派/公会名（选填）
 * String mGameVipLevel vip等级（选填）
 * float mBalance 用户游戏币余额（选填）
 * String mExt 扩展字段，json 格式（选填）。当前扩展了战斗力字段「fighting_power」，如 mExt = "{\"fighting_power\":\"99\"}";
 */
mIGPApi.uploadPlayerInfo(playerInfo, obsv);
```

| 错误码 | 含义 |
| --- | --- |
|GPUploadPlayerInfoResult.GPSDKUploadSuccess|上报成功|
|GPUploadPlayerInfoResult.GPSDKUploadFail|上报失败|

- 设置 sdk 账号切换监听

```java
// sdk内部事件回调接口
mIGPApi.setSDKInnerEventObserver(new IGPSDKInnerEventObserver() {
    @Override
    public void onSdkLogout() {
        // sdk账号登出了，游戏应该回到登录界面，然后重新调用登陆
    }

@Override
    public void onSdkSwitchAccount() {
        // 已废弃，无需实现
    }
});
```

- **退出接口**

```java
/**
 * 调起退出游戏的弹窗
 * IGPExitObsv obsv 退出回调（GPExitResult错误码，具体见下表）
 */
mIGPApi.exit(obsv);
```

| 错误码 | 含义 |
| --- | --- |
|GPExitResult.GPSDKExitResultCodeError|打开退出界面错误|
|GPExitResult.GPSDKExitResultCodeCloseWindow|点击关闭（不进行任何操作）|
|GPExitResult.GPSDKExitResultCodeExitGame|点击退出游戏|

#### 选接接口

- **查询实名认证接口**

```java
/**
 * IGPQueryCertInfoObsv obsv 查询实名信息回调（GPQueryCertResult错误码，具体见下表）
 */
// 回调实名信息——GPQueryCertInfo，其中字段含义：
// mHasCertified，true为已实名，false为未实名
// mAge，返回年龄
mIGPApi.queryCertInfo(obsv);
```

| 错误码 | 含义 |
| --- | --- |
|GPQueryCertResult.GPSDKQueryCertResultSuccess|查询成功|
|GPQueryCertResult.GPSDKQueryCertResultFailed|查询失败|

- **打开实名认证接口**

```java
/**
 * IGPOpenCertWindowObsv obsv 查询实名信息回调（GPOpenCertWindowResult错误码，具体见下表）
 * 
 * 建议游戏先调用queryCertInfo查询玩家是否已实名，根据实际返回结果再进行下面接口调用
 */
mIGPApi.openCertWindow(obsv);
```

| 错误码 | 含义 |
| --- | --- |
|GPOpenCertWindowResult.GPSDKQueryCertResultSuccess|实名认证成功|
|GPOpenCertWindowResult.GPSDKOpenCertWindowResultCancel|用户取消实名|
|GPOpenCertWindowResult.GPSDKOpenCertWindowResultOtherError|实名认证失败|

#### 可用接口

- 获取 SDK 版本号

```java
/**
 * 返回 SDK 版本号，String 类型
 */
mIGPApi.getVersion();
```

- 是否登录

```java
/**
 * 返回是否登录，boolean 类型
 */
mIGPApi.isLogin();
```

- 获取登录token

```java
/**
 * 返回登录token，String 类型
 */
mIGPApi.getLoginToken();
```

- 获取用户的唯一uin

```java
/**
 * 返回用户的唯一uin，String 类型
 */
mIGPApi.getLoginUin();
```

- 注销登录

```java
/**
 * 注销登录
 */
mIGPApi.logout();
```

- 获取用户名称

```java
/**
 * 获取用户名称，String 类型
 */
mIGPApi.getAccountName();
```

- 重新登录

```java
/**
 * 重新登录
 */
mIGPApi.reLogin(Context, IGPUserObsv);
```

- 支持游戏工具相关接口
游戏工具可选择接入，接入后将为用户提供游戏加速功能。游戏工具是默认接入，若需关闭，可以通过以下代码关闭接口， 若接入后再关闭，可直接联系我们商务及时关掉。

```java
/**
 * 关闭游戏工具
 */
mIGPApi.closeGameTool();
```

- 个人信息采集相关接口
个人信息采集可选择接入，根据GPDeviceInfo定义的个人信息类型选择是否采集。

```java
/**
 * 个人信息采集
 *type 参考GPDeviceInfo
 *isEnable: true-允许采集，false-不允许采集
 */
mIGPApi.enableCollectInfo(int type, boolean isEnable);
```

### 四、SDK 功能介绍

- SDK 账号系统： 帮助游戏方快速低成本地构建一个安全可靠的用户登录系统，用户 SDK 支持唤起登录页面，包括账号注册、登录、登出、忘记密码、修改昵称、注销账号等功能。
- SDK 支付功能： 支持微信、支付宝2种支付方式，同时支持代金券/平台币叠加支付，能给用户提供沉浸式的支付体验，支付便捷安全。
- SDK 福利系统：用户福利系统包括游戏礼包、代金券等， 是果盘面向游戏方开放的功能，合作伙伴可自行在后台创建代金券、礼包活动，活动通过审核后即可在该游戏生效，当玩家满足代金券、礼包发放条件时（例如：连续登录几天可领、充值满多少元可领），即可领取设置的代金券或礼包（例如：满 6 减 5 券，满 648 减 200 券等），从而实现拉新、促活、创收的目的。
- SDK 用户社区：用户社区是果盘提供的内嵌动态功能，用户可以在游戏内进入果盘的游戏社区，查看攻略资讯，分享自己的游戏精彩时刻，也可以和其他玩家、官方和大神进行互动（回复评论、发帖、发图等），满足用户社交需求。
- SDK 智能客服： 为用户提供客服接待服务，支持文字、表情、图片等多种消息形式，帮助用户解决在游戏场景中遇到的问题。
- SDK 游戏加速功能：游戏加速器是针对个人用户快速、安全连接游戏服务器的一种辅助服务，合作方可以选择接入，接入后可改善玩家的游戏体验。