IOS端接入指引

环境配置

1.SDK说明

SDK目前支持在IOS7以上系统iPhone、iPad、iPod Touch等设备上运行，支持armv7、arm64平台，Xcode版本至少在11以上。

2.导入SDK

直接将NutGameSDK文件夹所有资源文件拖入项目中（使用copy items的方式），并选择游戏所在的Target，如下图所示：

ios

对于使用Unity 2019.3及以上版本导出的Xcode工程，工程中通常会有UnityFramework（包含 Unity 引擎的核心代码、渲染逻辑、游戏逻辑等）、Unity-iPhone（游戏的Target）这两个Target。在导入SDK文时，需要将SDK中所有的.framework、.a、.h/.m文件添加到UnityFramework这个Target，而.bundle文件及其他资源文件则应添加到Unity-iPhone这个Target。

txt

UnityFramework ->
		AlipaySDK.framework
		ATAuthSDK.framework
		CsSDK.framework
		QuickGame.framework
		YTXMonitor.framework
		YTXOperators.framework
		libWeChatSDK.a
		SDKIntegrationTooler.h
		SDKIntegrationTooler.m
Unity-iPhone ->
		AlipaySDK.bundle
		ATAuthSDK.bundle
		CsRes.bundle
		QuickGameResource.bundle
		Nut_LaunchScreen_Landscape_iPad.png
		Nut_LaunchScreen_Portrait_iPad.png
		Nut_LaunchScreen_Landscape_iPhone.png
		Nut_LaunchScreen_Portrait_iPhone.png

随后选择游戏所在的Target，在Build Phases选项中找到Link Binary With Libraries配置项，点击下方加号依次添加CoreMotion.framework、libz.tbd、libc++.tbd、这三个系统依赖库，如下图所示：

ios

3.配置"-ObjC"

选中游戏所在的Target，在Build Settings选项中搜索Other Linker Flags配置项，修改Other Linker Flags，添加"-ObjC"。

txt

Build Settings ->
			Linking ->
  				Other Linker Flags  -ObjC

4.添加URL scheme

选中游戏所在的Target，在Info选项中找到URL Types配置项，点击下方加号添加，将URL Schemes值设置为与Bundle Identifer相同，如下图所示：

ios

在完成URL Schemes配置后，还需要添加LSApplicationQueriesSchemes白名单，将下面数组复制到Info.plist文件中。

xml

<key>LSApplicationQueriesSchemes</key>
<array>
	<string>mqq</string>
	<string>mqqopensdkapi</string>
	<string>mqqopensdkapiV2</string>
	<string>mqqopensdkapiV3</string>
	<string>weixinurlparamsapi</string>
	<string>weixin</string>
	<string>weixinULAPI</string>
	<string>alipay</string>
	<string>alipays</string>
</array>

5.申请权限

需要添加相册权限用于保存游客账号信息，添加相机和相册权限用于给客服人员发送图片信息，将下方权限配置复制到Info.plist文件中。

xml

<key>NSPhotoLibraryAddUsageDescription</key>
<string>需要使用您的相册来保存游客账号信息</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>需要使用您的相册来保存游客账号信息</string>
<key>NSCameraUsageDescription</key>
<string>需要使用您的相机来给客服发送图片信息</string>

6.允许HTTP访问

从iOS9开始，ATS默认禁止应用使用http连接，要求所有的网络请求使用https连接，为了支持http连接，需要将下面配置复制到Info.plist文件中。

xml

<key>NSAppTransportSecurity</key>
<dict>
	<key>NSAllowsArbitraryLoads</key>
	<true/>
</dict>

选中游戏所在的Target，在Signing & Capabilities选项中，点击左上角+ Capability按钮搜索并添加Keychain Sharing，然后在Keychain Groups中添加一个新的组，组名为com.nutgamesdk.sharedgroup，如下图所示：

ios

txt

com.nutgamesdk.sharedgroup

8.横竖屏说明

在游戏内SDK具体的展示方向由游戏的delegate.window.rootviewcontroller来决定，SDK将自动适配游戏画面方向。

由于SDK内置客服为竖屏模式，若游戏是横屏时，需要在游戏所在的Target，在General选项下的Deployment Info配置项中勾选Portrait让游戏支持竖屏。

9.闪屏与角标

为了提升启动体验并确保多设备兼容性，游戏闪屏建议使用LaunchScreen.storyboard实现，通过使用ImageView（ContentMode建议使用AspectFit）组件承载闪屏图，并利用Size Classes可同时适配iPhone、iPad闪屏，从而实现统一又灵活的闪屏体验。在NutGameSDK文件夹中有提供iPhone、iPad（横屏、竖屏）坚果闪屏图片。若项目依旧使用Launch Image接入闪屏，用到的闪屏图片素材可在游戏闪屏和角标素材文件夹中找到。

竖屏适配（只需创建一个wC_hR的Size Class即可）

txt

Nut_LaunchScreen_Portrait_iPhone_wC_hR.png
// iPad支持
Nut_LaunchScreen_Portrait_iPad_wR_hR.png

横屏适配（需要分别创建wR_hC、wC_hC的Size Class）

txt

Nut_LaunchScreen_Landscape_iPhone_wC_hC.png
Nut_LaunchScreen_Landscape_iPhone_wR_hC.png
// iPad支持
Nut_LaunchScreen_Landscape_iPad_wR_hR.png

游戏的icon需要在右下角加入坚果游戏角标，素材可在游戏闪屏和角标素材文件夹中找到。

10.修改Bitcode

若出现在模拟器上可以运行，但是真机上报错的情况，可尝试在游戏所在的Target，在Build Settings选项下搜索Enable Bitcode配置项，将该配置项设置为NO来解决当前问题。

接入流程

为了方便游戏方接入，SDK提供了工具类SDKIntegrationTooler，游戏方在接入SDK时请务必使用该工具类接入，不建议跳过该工具类直接使用SDK提供的API，特殊情况可根据需求自行修改该工具类。

1.微信、支付宝回调（必接）

为了保证与支付宝、微信可以正常回调，需要将下面代码复制到AppDelegate中以完成适配。

Objective-C

#import "SDKIntegrationTooler.h"

// 支付宝、微信回调配置
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
    return [SDKIntegrationTooler application:application continueUserActivity:userActivity restorationHandler:restorationHandler];
}

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url options:(NSDictionary *)options {
    return [SDKIntegrationTooler application:application openURL:url options:options];
}

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)source annotation:(id)annotation {
    return [SDKIntegrationTooler application:application openURL:url sourceApplication:source annotation:annotation];
}

2.回调通知

2.1.初始化通知（必接）

设置SDK初始化成功通知监听，SDK初始化成功后，就可以调用SDK登录等其它相关操作。

Objective-C

// 监听SDK初始化成功通知
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(handleSDKInitSuccess) name:@"NutGameSDKInitSuccess" object:nil];

// SDK初始化成功通知回调
- (void)handleSDKInitSuccess {
	// SDK初始化成功
}

2.2.登录通知（必接）

设置SDK登陆成功通知监听，登录成功后可得到当前小号信息，并进行游戏登陆等相关处理。

Objective-C

// 监听SDK登陆成功通知
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(handleLoginSuccess:) name:@"NutGameSDKLoginSuccess" object:nil];

// SDK登陆成功通知回调
- (void)handleLoginSuccess:(NSNotification *)notification {
	NSDictionary *userInfo = notification.userInfo;
	NSString *userId = [userInfo objectForKey:@"userId"];
	NSString *token = [userInfo objectForKey:@"token"];
	
	// 获得小号信息，进入游戏
}

登录顺序图：

    sequenceDiagram
        autonumber
        坚果SDK->>坚果服务器: 发起小号登录请求
        坚果服务器->>坚果SDK: 返回小号的uid、token
        坚果SDK->>游戏客户端: 提供小号uid、token用于登录游戏
        游戏客户端-->>游戏服务器: 提交小号uid、token去登录
        游戏服务器-->>坚果服务器: 验证小号uid、token有效性
        坚果服务器->>游戏服务器: 返回验证结果
        游戏服务器-->>游戏客户端: 返回登录结果

2.3.登出通知（必接）

设置SDK登出通知监听，收到SDK登出通知后，应同步处理游戏登出。

Objective-C

// 监听SDK登出通知
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(handleLogout) name:@"NutGameSDKLogout" object:nil];

// SDK登出通知回调
- (void)handleLogout {
	// SDK已登出，处理游戏登出
}

2.4.支付通知（必接）

设置SDK支付成功通知监听，支付成功后，可以拿到订单支付信息（以服务端通知为准，客户端支付通知仅作为参考）。

Objective-C

// 监听SDK内购支付成功通知
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(handlePaySuccess:) name:@"NutGameSDKPaySuccess" object:nil];

// SDK内购支付成功回调
- (void)handlePaySuccess:(NSNotification *)notification {
	NSLog(@"支付成功 %@", notification);
}

支付顺序图：

    sequenceDiagram
        autonumber
        actor 玩家
        玩家-->>游戏客户端: 点击购买道具
        游戏客户端-->>游戏服务器: 提交购买道具请求
        游戏服务器-->>游戏客户端: 创建订单，返回订单号
        游戏客户端-->>坚果SDK: 调用支付接口，传入订单信息
        坚果SDK->>坚果服务器: 发起支付流程
        坚果服务器->>游戏服务器: 发送支付结果通知
        游戏服务器-->>游戏客户端: 发放道具
        游戏服务器-->>坚果SDK: 返回发放道具结果
        游戏客户端-->>玩家: 获得道具

3.初始化（必接）

打开SDK工具类SDKIntegrationTooler.m，将SDK_PRODUCT_CODE的值修改为当前接入游戏的productCode（由负责对接的运营提供）。

Objective-C

#import "SDKIntegrationTooler.h"
// sdk产品code
#define SDK_PRODUCT_CODE @"填入productCode"

在游戏启动时调用SDK初始化方法。

Objective-C

[SDKIntegrationTooler initSDK];

4.登录（必接）

拉起SDK登录弹窗，需要在SDK初始化成功之后调用，否则调用无效。

Objective-C

[SDKIntegrationTooler login];

5.登出（必接）

调用SDK登出，SDK登出后游戏也应同步进行登出等相关操作。

Objective-C

[SDKIntegrationTooler logout];

6.上报角色（必接）

玩家登录成功进入游戏后，需要立即对当前角色的信息进行上报，请务必保证角色信息的准确性，之后每当用户的角色信息改变时就需要执行角色信息的上报操作。

Objective-C

// 角色信息
NSDictionary *roleInfo = @{
	@"roleId": @"10086",
	@"roleName": @"会唱跳的坤坤",
	@"roleLevel": @"240",
	@"vipLevel": @"18",
	@"rolePower": @"1880000",
	@"serverId": @"100001",
	@"serverName": @"雷霆一区"
};
// 上报角色
[SDKIntegrationTooler uploadRole:roleInfo];

roleInfo字段说明

字段名	类型	说明
roleId	NSString	角色ID（必传）
roleName	NSString	角色名称（必传）
roleLevel	NSString	角色等级（可选）
vipLevel	NSString	VIP等级（可选）
rolePower	NSString	角色战斗力（可选）
serverId	NSString	服务器ID（必选）
serverName	NSString	服务器名称（必选）

7.支付（必接）

调起SDK支付页面，需要同时上传当前角色信息，请务必保证订单信息以及角色信息的准确性。

Objective-C

// 商品信息
NSDictionary *goodParam = @{
	@"productId": @"1001001",
	@"productName": @"麻痹戒指",
	@"productDesc": @"", //（可选）
	@"price": @"648", // 单位：元
	@"orderNo": @"1000202020154",
	@"url": @"", //（可选）
	@"extras": @"", //（可选）
};
// 角色信息
NSDictionary *roleParam = @{
  @"roleId": @"10086",
  @"roleName": @"会唱跳的坤坤",
  @"roleLevel": @"240",
  @"vipLevel": @"18",
  @"rolePower": @"1880000",
  @"serverId": @"100001",
  @"serverName": @"雷霆一区"
};
// 发起支付
[SDKIntegrationTooler pay:goodParam withRole:roleParam];

goodParam字段说明

字段名	类型	说明
productId	NSString	商品ID（必传）
productName	NSString	商品名称（必传）
productDesc	NSString	商品描述（可选）
price	NSString	内购商品价格（必传、单位：元）
orderNo	NSString	游戏方订单号（必传、唯一）
url	NSString	支付回调通知地址（可选）
extras	NSString	透传参数（可选）

防沉迷相关

SDK自带防沉迷系统，会自动弹出防沉迷窗口，包含实名认证、未成年登录限制、充值限制，开发者无需再做处理。

1.获取年龄

获取当前登录用户的年龄，返回值NSString类型，如果未实名则返回0。

Objective-C

[SDKIntegrationTooler getAge];

2.获取实名认证与否

当前登录用户是否实名，返回值BOOL类型，如果未实名则返回NO。

Objective-C

[SDKIntegrationTooler isRealName];

IOS端接入指引 ​

环境配置 ​

1.SDK说明 ​

2.导入SDK ​

3.配置"-ObjC" ​

4.添加URL scheme ​

5.申请权限 ​

6.允许HTTP访问 ​

7.配置KeyChain Sharing ​

8.横竖屏说明 ​

9.闪屏与角标 ​

10.修改Bitcode ​

接入流程 ​

1.微信、支付宝回调（必接） ​

2.回调通知 ​

2.1.初始化通知（必接） ​

2.2.登录通知（必接） ​

2.3.登出通知（必接） ​

2.4.支付通知（必接） ​

3.初始化（必接） ​

4.登录（必接） ​

5.登出（必接） ​

6.上报角色（必接） ​

7.支付（必接） ​

防沉迷相关 ​

1.获取年龄 ​

2.获取实名认证与否 ​

IOS端接入指引

环境配置

1.SDK说明

2.导入SDK

3.配置"-ObjC"

4.添加URL scheme

5.申请权限

6.允许HTTP访问

7.配置KeyChain Sharing

8.横竖屏说明

9.闪屏与角标

10.修改Bitcode

接入流程

1.微信、支付宝回调（必接）

2.回调通知

2.1.初始化通知（必接）

2.2.登录通知（必接）

2.3.登出通知（必接）

2.4.支付通知（必接）

3.初始化（必接）

4.登录（必接）

5.登出（必接）

6.上报角色（必接）

7.支付（必接）

防沉迷相关

1.获取年龄

2.获取实名认证与否