果盘SDK接入文档 for iOS

## 1 文档说明
1.1 功能描述
    果盘SDK主要用来向第三方应用程序提供便捷、安全以及可靠的账号体系和支付服务。本文主要描述客户端SDK支付接口的使用方法，供合作伙伴的开发者接入使用。
1.2 阅读对象
    本文档面向具有一定iOS客户端开发能力,了解iOS客户端的开发和管理人员。
1.3 SDK资源下载

[【附件】果盘SDK_iOS_V5.2.8_B1343.zip](/media/attachment/2025/10/果盘SDK_iOS_V5.2.8_B1343.zip)

## 2 规范要求
### 2.1 bundle identifier
    bundle identifier使用.guopan作为后缀。
    例如：原本 bundle identifier 为com.xx.game，接入果盘SDK更改为com.xx.game.guopan。
### 2.2 游戏安装包 ICON 
    游戏安装包 ICON 需加入果盘角标，角标需要放到ICON右下角。角标源文件请在SDK文件夹的一级目录查收，角标样式如下：

![](/media/202111/2021-11-17_181022_354457.png)

## 3 iOS客户端接入
### 3.1 工程配置
1)获取appID，client secret key（APP KEY，长度16位），配置支付回调；
打开 https://open.guopan.cn/gpop/ 登录你们的账号（我们商务同学给你们的）即可获appID 、 client secret key，及进行支付回调的配置。

2)添加果盘SDK目录下的所有文件，包括资源文件、头文件和静态库；

![](/media/202111/85DA7913-57BE-4A20-9658-A5871A852AAF_1637140729.png)
图1:果盘SDK目录下的文件

3)添加SDK所依赖的系统库，如下图2所示：

![](/media/202412/2024-12-23_134104_872205.png)
图2：果盘SDK依赖的系统库
4)修改工程Deployment Target（目前SDK支持8.x以上）；
方法：程序 Target->General->Deployment Info->Deployment Target 下。
5)工程Other Linker Flags设置；
方法：程序 Target->Build Settings->Linking->Other Linker Flags 添加-force_load。 $(SRCROOT)/../SDK/libGPGameSDK.a（修改为导入sdk到工程的路径），注意：$(SRCROOT)表示工程文件(如GPGameSDK_SDKDemo.xcodeproj)路径。如下图所示：

![](/media/202111/2021-11-17_172026_366468.png)

图3：配置Other Linker Flags

6)app跳转设置(URL Schemes中不能含有下划线)；
a. 如无特殊需求，不需要设置[GPGameSDK_Pay defaultGPGamePay].appScheme的值。
b.添加处理跳转的方法：
  b-1. iOS原生项目开发，在AppDelegate中 ，加上该代理方法.如图所示：

![](/media/202111/2021-11-17_172131_718885.png)
图 4:添加处理app跳转的方法

b-2. Unity项目开发，在UnityAppController中，加上图 4中的代理方法. 
  b-3. cocos2dx项目开发，在AppController中，加上图 4中的代理方法.
    c. 新增URL types，添加URL Schemes。
    方法1：修改appname-Info.plist，URL types，添加URL Schemes，确保URL Schemes唯一。
    方法2：点击项目工程文件，点击对应Target，进入Info，添加URL Types。
    注：URL Schemes的值必须设置成[GPGameSDK_Pay defaultGPGamePay].appScheme的值。

![](/media/202111/2021-11-17_172148_137553.png)
图5：设置URL Scheme的值

7)若项目本身代码没有建立c++链接，请将AppDelegate.m文件设置为 AppDelegate.mm，因为游戏一般都会使用c++，一般不需要此操作；
8)打开appname-Info.plist文件，在文件中添加Localized resources can be mixed，设置为YES，如图所示：

![](/media/202111/2021-11-17_172556_461319.png)
图6：设置Localized resources can be mixed的值

9)打开appname-Info.plist文件，在文件中添加两个变量NSLocationAlwaysUsageDescription，NSLocationWhenInUseUsageDescription，设置自定义提示用户授权使用地理定位功能时的提示语，如下图所示：

![](/media/202111/2021-11-17_172527_600598.png)
 图7：设置提示用户授权使用地理定位功能时的自定义提示语

### 3.2 iOS9-Xcode7适配注意事项
1)iOS Deployment Target 支持的最低版本为iOS8.0。
2)openurl打开其他应用，需要在info.plist添加。

![](/media/202111/2021-11-17_172634_856823.png)
图9：添加openurl打开的其他应用白名单

3)默认只支持https请求，http请求需要在info.plist中添加配置，方法如下：

![](/media/202111/2021-11-17_172646_122632.png)
图10：配置允许iOS9支持http请求

### 3.3 iOS11适配注意事项
1)在info.plist中添加相册，麦克风访问权限

![](/media/202111/2021-11-17_172726_046737.png)
图 10：配置相册，麦克风访问权限

### 3.4 iOS14适配注意事项
1)在info.plist中添加IDFA访问权限

![](/media/202201/2022-01-22_173615_497167.png)
图 11：配置IDFA访问权限

### 3.5 SDK 接口说明

1)应用初始化以及登录相关接口说明：
表3-1 GPGameSDK接口方法列表

| 方法名 | 方法描述 | 备注 |
| --- | --- | --- |
| +(GPGameSDK*)defaultGPGame | 获取服务实例 |  |
| - (void)GPInit:(NSString *)aAppID secretKey:(NSString *)aSKey completion:(GPInitErrorCodeBlock)completion |支付SDK应用初始化函数  | 初始化函数验证超时时间为7s，即遇到网络异常情况，7s后才返回，故此处验证时，游戏可以做加载状态提示，或将登录页面调出操作，从block中移出到init函数后，即直接显示登陆。 |
| - (void)GPUploadGamePlayerInfoWithPlayerID:(NSString*)playerID playerNickName:(NSString*)playerNickName severName:(NSString*)severName severID:(NSString*)serverID gameLevel:(NSString*)gameLevel |  上报游戏角色相关数据|  调用时机：1、登录成功，2、角色升级，3、支付成功|
| - (int)GPLoginInView:(UIView *)view | 调用登录并返回结果 | 显示登录页面 |
| - (void)GPLogout | 注销登录 |  |
| - (BOOL)isLogined |  |  |
| - (NSString *)loginToken | 获取登录Token |  客户端在接收到登录成功通知时，可以调用接口获取，直接进行游戏登入操作|
| - (NSString *)loginUin | 获取登录用户uin | 客户端在接收到登录成功通知时，可以调用接口获取，直接进行游戏登入操作（与服务端请求参数game_uin的值一样），用户唯一标识 |
| - (NSString *)sdkVersion | 获取SDK版本 |  |
| - (NSString *)appID | 获取appID |  |
| - (NSString *)secretKey | 获取secretKey |  |
| - (NSString *)accountName | 获取登录帐号名称 | 登录后才能获取 |
| - (void)GPQueryRealNameStatus:(GPQueryRealNameBlock) completion | 查询实名认证状态 |  登录后才能查询否则返回查询错误|
| - (void)GPOpenRealNameWindowInView:(UIView *)view completion:(GPOpenRealNameWindowBlock)completion | 打开实名认证弹窗 |  登录后才能打开实名认证弹窗|
| - (NSString *)sdkVersion | 获取SDK版本 |  |

表格 3-2 init初始化方法描述

| 方法原型 | - (void)GPInit:(NSString *)aAppID secretKey:(NSString *)aSKey completion:(GPInitErrorCodeBlock)completion |
| --- | --- |
| 方法功能 | 提供支付SDK应用初始化功能 |
| 方法参数 | 方法参数	NSString *aAppID：应用appID NSString *aSKey：应用secretKey appID 和 secretKey：通过果盘注册获取void (^)(GPInitErrorCode result) completion：初始化完成后调用的block。 |

表格 3-3 调用登录方法描述

| 方法原型 | - (int)GPLoginInView:(UIView *)view |
| --- | --- |
| 方法功能 | 提供调用登录的功能 |
| 方法参数 | UIView *view: 指定的view,可以填nil |
| 方法返回 | 返回0正常进入SDK登录界面， -1表示SDK登录环境异常.如果设置初始化配置成功，调用后立即出现登录UI，用户成功获取登录状态后，UI自动消失，并广播通知kGPGameNotification_Login_Succeed |

表格 3-4上报游戏角色信息方法描述

| 方法原型 | - (void)GPUploadGamePlayerInfoWithPlayerID:(NSString*)playerID playerNickName:(NSString*)playerNickName severName:(NSString*)severName severID:(NSString*)serverID gameLevel:(NSString*)gameLevel |
| --- | --- |
| 方法功能 | 提供上传游戏角色相关信息的功能 |
| 方法参数 | playerID：游戏角色ID 若无 可填nil playerNickName:游戏角色名称 若无 可填nil severName：游戏角色所在服务器名称 若无 可填nil severID：游戏角色所在服务器ID 若无 可填nil gameLevel：游戏角色级别 若无 可填nil|

表格 3-5查询实名认证状态方法描述

| 方法原型 | - (void)GPQueryRealNameStatus:(GPQueryRealNameBlock) completion |
| --- | --- |
| 方法功能 | 提供查询实名认证状态的功能 |
| 方法参数 | void (^)(GPQueryRealNameErrorCode result,BOOL hasRealName,int age) completion：查询结果返回的block |

表格 3-6打开实名认证弹窗方法描述

| 方法原型 | - (void)GPOpenRealNameWindowInView:(UIView *)view completion:(GPOpenRealNameWindowBlock)completion |
| --- | --- |
| 方法功能 | 提供打开实名认证弹窗的功能 |
| 方法参数 | UIView *view: 指定的view,可以填nil void (^)(GPOpenRealNameWindowErrorCode result) completion：打开实名认证弹窗完成后调用的block |

表3-7 GPGameSDK_Pay接口方法列表

| 方法名 | 方法描述 | 备注 |
| --- | --- | --- |
|  +(GPGameSDK_Pay*) defaultGPGamePay|  获取服务实例|  |
|  -(int)asyncGPPay:
(GPSDKGamePayment *)aPayment| 发起订单 |  |
| -(BOOL)openUrlResponse:(NSURL *)url |  跳转其他应用处理| appdelegate的openurl回调使用，具体使用方法请参照demo |
|  -(void)setAppScheme:(NSString*)appSchem| 设置属性appScheme| 该值用于从其他应用（支付宝钱包）跳转回来 |

表3-8 支付方法描述

| 方法原型 | - (int)asyncGPPay:(GPSDKGamePayment *)aPayment |
| --- | --- |
| 方法功能 | 提供发起订单功能 |
| 方法参数 | GPSDKGamePayment *aPayment：包含订单信息，aPayment详情请参考Demo 或者头文件 |
| 方法返回 | 1. 返回0正常进入sdk支付界面， 非0表示sdk支付环境异常，不允许支付：-1为登录有 问题，-2为订单不合法。 2. 支付后会广播通知kGPGameNotification_Pay_Result，返回GPGamePaymentResult对象，从GPGamePaymentResult对象中获取订单支付结果，并自动退出SDK支付界面。 3. 支付结果请参见表4-2。 |

表3-9 跳转方法描述

| 方法原型 | - (BOOL)openUrlResponse:(NSURL *)url |
| --- | --- |
| 方法功能 | 启动第三方应用处理数据 |
| 方法参数 |  NSURL *url 启动第三方应用的URL |
| 方法返回 |  YES：处理了该数据  NO：没有处理该数据 |

表3-10 充值渠道说明表

| 充值类型 | 说明|
| --- | --- |
| 支付宝 |  有安装支付宝钱包会跳转到支付宝钱包支付，否则在app弹出webview支付|
| 微信支付 |  如果安装了微信，跳转微信进行支付，否则不能跳转，并提示用户安装|

## 附录一
### 1 初始化环境错误码

表4-1  初始化环境错误码

| 错误代码 | 含义 |
| --- | --- |
|  GPInitErrorCodeNone＝0| 初始化成功 |
| GPInitErrorCodeNet＝1 |  网络异常|
|  GPInitErrorCodeConig=2| appID,secret配置错误  |
| GPInitErrorCodeUpdating=3 | 游戏更新中 |

### 2查询实名认证状态错误码

表4-2  查询实名认证状态错误码

| 错误代码 | 含义 |
| --- | --- |
|  GPQueryRealNameErrorCodeSuccess＝0| 查询成功 |
| GPQueryRealNameErrorCodeFail＝1 |  查询失败|

### 3打开实名认证弹窗错误码

表4-3 打开实名认证弹窗错误码

| 错误代码 | 含义 |
| --- | --- |
|  GPOpenRealNameWindowErrorCodeSuccess＝0| 实名成功 |
| GPOpenRealNameWindowErrorCodeCancel＝1 |  实名取消|
| GPOpenRealNameWindowErrorCodeOtherErr=2 |  其他错误。特殊原因调起实名认证弹窗失败：未初始化、未登录、同一时间内多次调用、SDK未支持等|

### 4 支付返回码

表4-4  支付返回码

| 错误代码 | 含义 |
| --- | --- |
|  GPSDKPayResultCodeSucceed＝0| 支付成功 |
| GPSDKPayResultCodePayForbidden＝1 |  支付被拒|
| GPSDKPayResultCodeNotEnough=2 |  余额不足|
| GPSDKPayResultCodePayHadFinished=3 |  重复支付|
| GPSDKPayResultCodeCancel=4 |  取消支付|
| GPSDKPayResultCodeServerError=5 |  服务端错误|
| GPSDKPayResultCodePayBackground=6 | 后台自动购买|
| GPSDKPayResultCodeBackgroundSucceed=7 | 轮询购买成功|
| GPSDKPayResultCodeBackgroundTimeOut=8 | 轮询购买超时|
| GPSDKPayResultCodeInitFailed＝100 | 初始化购买失败|
| GPSDKPayResultCodeOtherError=1000 | 其他问题购买失败|

### 5 通知类型

| 错误代码 | 含义 |
| --- | --- |
|  kGPGameNotification_Login_Succeed| 登录成功通知 |
| kGPGameNotification_Pay_Result|  支付结果通知|
| kGPGameNotification_Logout_Succeed |  注销登录通知|

注意：
收到通知更新UI需要在主线程执行，例如：
1) dispatch_async(dispatch_get_main_queue(), ^{
        //更新ui
 });
1)[self performSelectorOnMainThread:(SEL) withObject:(id) waitUntilDone:(BOOL)];

## 附录2 常见错误
### 1 编译错误
1)Unity3D工程如果出现编译错误undefined _OBJC_CLASS_$_CIColor...，请加入CoreImage.framework 和 CoreText.framework这两个framework。
2)cocos-2d项目编译问题，可以在Other C Flags(Other C++ Flags)填写-ObjC（也可以加入-all_load），如下图所示：

![](/media/202111/2021-11-17_180851_289797.png)
### 2 SDK参数设置错误
1)使用支付宝支付时，跳转到支付宝钱包，如果无法跳转回到游戏，检查是否正确设置了APPScheme。（详见本文档3.1第6项）
2)调用支付接口，如果返回-2（订单非法）。订单号，商品id，商品名不能为空，长度不能为0；订单号长度不能超过128位，商品单价和商品数量必须大于0。 
3)使用支付宝支付时，跳转到支付宝钱包后，能跳转回到游戏，但是支付成功之后SDK没有任何提示，支付界面没有关闭。需要调用openUrl。
4)用户的UIN是果盘提供的用户唯一标识符，果盘提供的accountName不能作为唯一标识。