1. 概述

1.1 ⽂档说明

本⽂档介绍如何将 QuickGameSDK海外版集成到 Unreal Engine iOS 项⽬中。SDK 提供了初始化、登录、退出登录、⽀付和上传⻆⾊信息等功能

接⼊时可参考 UE Demo，配合 iOS 原⽣接⼊⽂档： GameSDK/⽂档(Document)/iOS-SDK接⼊⽂档(核心篇).pdf（在下载的SDK资源获取此文档）

1.2 SDK简介

数据分析：集成 Firebase、Adjust、AppsFlyer 等分析⼯具

社交登录：⽀持 Facebook、Google 等第三方登录

1.3 版本信息

2. 快速开始

2.1 最⼩集成步骤

详细步骤请参考下⽅"集成步骤"章节

2.2 参考资源

• 核⼼接⼊⽂档: iOS-SDK接⼊⽂档(核⼼篇).pdf
• Facebook 登录: iOS-SDK接⼊⽂档(Facebook登录篇).pdf
• Google 登录: iOS-SDK接⼊⽂档(Google登录篇).pdf
• Firebase 配置: iOS-SDK接⼊⽂档(Firebase数据篇).pdf

3. 架构说明

3.1 分层架构设计

SDK 接⼝采⽤分层架构设计，接⼝调⽤层次如下：

UE 代码层（蓝图/C++）
↓
UGameSDKManager (UE 封装层)
- 类型转换: FString ↔ std::string
- 委托系统: UE 委托 ↔ std::function
- 线程安全: 确保回调在游戏线程执⾏
↓
QuickGameSDK::SDK (标准 C++ 接⼝层)
- 纯 C++ 接⼝
- 使⽤标准库类型（std::string, std::function）
- 单例模式
↓
GameSDKBridge (C 接⼝层)
- C ⻛格接⼝
- 回调函数指针
↓
GameSDKBridge.mm (Objective-C++ 桥接层)
- Objective-C 与 C++ 桥接
- 协议回调处理
- 主线程调⽤保证
↓
JYouLoginKit.framework (原⽣ iOS SDK)
- Objective-C 实现
- 协议回调模式

3.2 各层功能说明

4. ⽂件结构

4.1 SDK⽂件位置（GameSDK/SDK/）

SDK ⽂件应放置在项⽬根⽬录下的 GameSDK/SDK/ 目录：

QuickGameIOS/
└── GameSDK/
  └── SDK/
      ├── JYouLoginKit.framework       # 主 SDK 框架（必需）
      ├── SSBundle.bundle              # SDK 资源包（必需）
      ├── AdjustSdk.framework         # Adjust SDK（数据分析）
      ├── AdjustSigSdk.framework       # Adjust 签名 SDK
      ├── AppsFlyerLib.framework       # AppsFlyer SDK（数据分析）
      ├── FBAEMKit.framework           # Facebook AEM Kit
      ├── FBSDKCoreKit_Basics.framework # Facebook SDK 基础
      ├── FBSDKCoreKit.framework       # Facebook SDK 核⼼
      ├── FBSDKLoginKit.framework      # Facebook 登录 SDK
      ├── FirebaseAnalytics/            # Firebase Analytics 框架⽬录
      │   ├── FirebaseAnalytics.framework
      │   ├── FirebaseCore.framework
      │   ├── FirebaseMessaging.framework
      │   └── ... (其他 Firebase 框架)
      ├── FirebaseMessaging/           # Firebase Messaging 框架⽬录
      │   └── FirebaseMessaging.framework
      └── google/                      # Google Sign-In SDK ⽬录
          ├── GoogleSignIn.framework
          ├── GoogleSignIn.bundle
          ├── AppAuth.framework
          └── ... (其他 Google 框架)

4.2 源代码⽂件结构（Source/QuickGameIOS/IOS/）

Source/QuickGameIOS/IOS/
├── QuickGameSDK.h         # 标准 C++ 接⼝头⽂件
├── QuickGameSDK.cpp      # 标准 C++ 接⼝实现
├── GameSDKBridge.h       # C 接⼝头⽂件
├── GameSDKBridge.mm      # Objective-C++ 桥接实现
├── GameSDKManager.h      # UE C++ 接⼝类（暴露给蓝图）
├── GameSDKManager.cpp    # UE C++ 接⼝实现
└── GameSDKAppDelegate.mm # AppDelegate URL回调处理

4.3 主要框架和资源包说明

• JYouLoginKit.framework  - 主 SDK 框架（静态框架）
• SSBundle.bundle  - SDK 资源包，包含 UI 资源、图⽚等

第三方 SDK 框架：

• Facebook SDK： FBSDKCoreKit.framework , FBSDKLoginKit.framework 等（动态框架）
• Google Sign-In： GoogleSignIn.framework , AppAuth.framework 等（静态框架）
• Firebase： FirebaseAnalytics.framework , FirebaseMessaging.framework 等（静态框架）
• Adjust： AdjustSdk.framework , AdjustSigSdk.framework （动态框架）
• AppsFlyer： AppsFlyerLib.framework （静态框架）

4.4 第三方SDK依赖

• Adjust SDK：用于归因分析和数据追踪
• AppsFlyer：用于移动归因和营销分析
• Facebook SDK：⽤于 Facebook 登录和数据追踪
• Firebase：用于数据分析、推送通知等
• Google Sign-In：用于 Google 账号登录

5. 集成步骤

5.1 ⽂件准备

5.1.1 SDK文件复制

• JYouLoginKit.framework
• SSBundle.bundle
• 所有第三⽅ SDK 框架

5.1.2 目录结构检查

确认目录结构如下：

QuickGameIOS/
├── GameSDK/
│   ├── SDK/                    # SDK ⽂件⽬录
│   │   ├── JYouLoginKit.framework
│   │   ├── SSBundle.bundle
│   │   └── ... (其他框架)
│   ├── Demo/                   # Demo 项⽬（参考）
│   └── ⽂档(Document)/         # SDK ⽂档
└── Source/
  └── QuickGameIOS/
      └── IOS/                # SDK 集成代码

5.2 编译配置

5.2.1 Build.cs配置说明

关键配置点：

1. SDK 路径设置

string SDKRoot = Path.GetFullPath(Path.Combine(ModuleDirectory,
"../../GameSDK/SDK"));

2. 主 SDK 框架

3. 第三⽅框架分类

动态框架（需要嵌⼊）：Facebook SDK、Adjust SDK

静态框架（仅链接）：Firebase、Google Sign-In、AppsFlyer

5.2.2 框架链接配置

在 QuickGameIOS.Build.cs 中，框架通过 PublicAdditionalFrameworks 添加：

// 静态框架示例
PublicAdditionalFrameworks.Add(
   new Framework(
       "JYouLoginKit",
       JYouLoginKitFrameworkPath,
       ""
   )
);
// 动态框架示例（需要在 Xcode 中嵌⼊）
PublicAdditionalFrameworks.Add(
   new Framework(
       "FBSDKCoreKit",
       FBSDKCoreKitFrameworkPath,
       ""
   )
);

5.2.3 资源包配置

资源包通过 AdditionalBundleResources 添加：

AdditionalBundleResources.Add(
   new BundleResource(SSBundlePath)
);

5.2.4 系统框架依赖

需要添加的系统框架：

PublicFrameworks.AddRange(new string[] {
   "Foundation",
   "UIKit",
   "StoreKit",
   "CoreTelephony",
   "SystemConfiguration",
   "Network",
   "Security",
   "UserNotifications",      // Firebase 推送需要
   "AdSupport",              // Facebook SDK 需要
   "AppTrackingTransparency", // Facebook SDK 需要
   "AuthenticationServices",  // Google登录需要
   "SafariServices",         // Google登录需要
   // ... 其他框架
});

5.2.5 宏定义

确保定义了 WITH_GAMESDK 宏：

PublicDefinitions.Add("WITH_GAMESDK=1");

5.3 Info.plist配置

5.3.1 ⽹络访问权限（NSAppTransportSecurity）

SDK 需要访问⽹络接⼝，需要允许 HTTP 连接：

NSAppTransportSecurity

   NSAllowsArbitraryLoads
   

5.3.2 URL Schemes⽩名单（LSApplicationQueriesSchemes）

⽤于⽀持第三⽅登录，需要在⽩名单中声明：

LSApplicationQueriesSchemes

   
   fbapi
   fb-messenger-api
   fbauth2
   fbshareextension
   
   googlegmail
   googlechrome
   
   
 

5.3.3 第三⽅登录URL Schemes（CFBundleURLTypes）

Facebook URL Scheme：

CFBundleURLTypes

   
       CFBundleTypeRole
       Editor
       CFBundleURLSchemes
       
           fbYOUR_FACEBOOK_APP_ID
       
   

Google URL Scheme：

   CFBundleTypeRole
   Editor
   CFBundleURLSchemes
   
       com.googleusercontent.apps.YOUR_CLIENT_ID
   

5.3.4 权限描述

相册权限：

NSPhotoLibraryUsageDescription
需要访问相册以保存和选择图⽚
NSPhotoLibraryAddUsageDescription
需要访问相册以保存图⽚

相机权限：

NSCameraUsageDescription
上传头像等场景需要使⽤到您的相机

通知权限（Firebase 推送需要）：

NSUserNotificationsUsageDescription
需要通知权限以接收推送消息

IDFA 追踪权限（App Tracking Transparency / Facebook SDK 需要）：

NSUserTrackingUsageDescription
⽤于提供个性化⼴告体验和数据分析

重要说明：

建议描述⽂字要符合应⽤的实际⽤途，避免审核被拒

5.3.5 Facebook配置项

FacebookAppID
YOUR_FACEBOOK_APP_ID
FacebookClientToken
YOUR_FACEBOOK_CLIENT_TOKEN
FacebookDisplayName
您的应⽤名称

5.3.6 Google配置项

GIDClientID
YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com

5.4 Xcode配置

5.4.1 动态框架嵌⼊

配置步骤：

如下图：

5.4.2 静态框架链接

静态框架（如 JYouLoginKit、Firebase、Google Sign-In）会⾃动链接，⽆需⼿动嵌⼊

5.4.3 资源⽂件检查

GoogleSignIn.bundle  - Google Sign-In 资源

5.4.4 GoogleService-Info.plist配置

3. 在 Build.cs 中配置路径：

string GoogleServiceInfoPath = Path.Combine(Path.GetFullPath(Path.Combine(ModuleDirectory,
"../../GameSDK/Demo")), "GoogleService-Info.plist");
if (File.Exists(GoogleServiceInfoPath))
{
   AdditionalBundleResources.Add(
       new BundleResource(GoogleServiceInfoPath)
   );
}

6. 接⼝调⽤

6.1 在蓝图中使⽤

6.1.1 初始化SDK

在蓝图中调⽤ Get Instance 节点（类型：GameSDKManager）

输⼊参数： Product Code （产品Code，从 GameSDK 后台获取）

InitFail (2001)  - 初始化失败

示例流程：

Event BeginPlay
→ Get Instance (GameSDKManager)
→ Bind Event to On Init Complete
→ Initialize SDK (Product Code: "your_product_code")

6.1.2 登录

2. 绑定登录回调

注意：登录会弹出 SDK 的登录界⾯，⽤户可以选择不同的登录⽅式

6.1.3 退出登录

注意：退出登录后，⽤户需要重新登录才能使⽤需要登录的功能

6.1.4 ⽀付

Extras  - 透传参数（可选，JSON 字符串）

Message  - 消息

6.1.5 上传⻆⾊信息

调⽤ Update Role Info 节点

2. 必填参数

3. 可选参数

Party Name  - 工会名称

6.1.6 获取用户信息

Is Guest  - 是否为游客（返回 bool）

6.1.7 回调处理

回调绑定示例：

Event BeginPlay
→ Get Instance (GameSDKManager)
→ Bind Event to On Init Complete
→ Bind Event to On Login Complete
→ Bind Event to On Pay Complete

6.2 在C++中使⽤

6.2.1 使⽤UGameSDKManager（推荐）

这是推荐的⽅式，⽀持蓝图，使⽤简单：

#include "IOS/GameSDKManager.h"
// 获取实例
UGameSDKManager* SDKManager = UGameSDKManager::GetInstance();
// 初始化
SDKManager->InitializeSDK(TEXT("YOUR_PRODUCT_CODE"));
// 绑定回调
SDKManager->OnInitComplete.AddDynamic(this, &AMyGameMode::HandleInitComplete);
SDKManager->OnLoginComplete.AddDynamic(this, &AMyGameMode::HandleLoginComplete);
SDKManager->OnPayComplete.AddDynamic(this, &AMyGameMode::HandlePayComplete);
// 登录
SDKManager->Login();
// 退出登录
SDKManager->Logout();
// ⽀付
SDKManager->Pay(
   TEXT("product_id"),
   TEXT("商品名称"),
   TEXT("商品描述"),
   6.00f,  // 价格
   TEXT("order_12345"),
   TEXT(""),  // ⽀付回调地址URL
   TEXT("")   // Extras
);
// 上传⻆⾊
SDKManager->UpdateRoleInfo(
   TEXT("role_123"),
   TEXT("⻆⾊名"),
   TEXT("server_1"),
   TEXT("服务器1"),
   TEXT("10"),  // Level
   TEXT("1"),   // VIP
   TEXT(""),    // Power
   TEXT(""),    // Balance
   TEXT("")     // Party
);
// 获取⽤户信息
FString UserId = SDKManager->GetUserId();
FString Token = SDKManager->GetUserToken();
bool bIsLogined = SDKManager->IsLogined();
bool bIsGuest = SDKManager->IsGuest();

void AMyGameMode::HandleInitComplete(EGameSDKStatus Status)
{
   if (Status == EGameSDKStatus::InitSuccess)
   {
       UE_LOG(LogTemp, Log, TEXT("SDK initialized successfully"));
       // 初始化成功，可以调⽤登录
       SDKManager->Login();
   }
   else
   {
       UE_LOG(LogTemp, Error, TEXT("SDK initialization failed"));
   }
}
void AMyGameMode::HandleLoginComplete(EGameSDKStatus Status, const FString& UserId, const
FString& Token, const FString& Message)
{
   if (Status == EGameSDKStatus::ErrorNone)
   {
       UE_LOG(LogTemp, Log, TEXT("Login success: UserId=%s"), *UserId);
       // 登录成功，保存⽤户信息
   }
}
void AMyGameMode::HandlePayComplete(EGameSDKStatus Status, const FString& OrderNo, const
FString& ProductId, const FString& TransactionId, const FString& Message)
{
   if (Status == EGameSDKStatus::OrderSuccess)
   {
       UE_LOG(LogTemp, Log, TEXT("Pay success: OrderNo=%s, ProductId=%s"), *OrderNo,
*ProductId);
       // ⽀付成功
   }
}

6.2.2 使⽤QuickGameSDK::SDK标准接⼝

如果需要使⽤标准 C++ 接⼝（不依赖 UE 对象系统）

#include "IOS/QuickGameSDK.h"
using namespace QuickGameSDK;
// 获取实例
SDK& sdk = SDK::GetInstance();
// 初始化（使⽤ lambda 回调）
sdk.Initialize("YOUR_PRODUCT_CODE", [](Status status) {
   if (status == Status::InitSuccess) {
       // 初始化成功
       UE_LOG(LogTemp, Log, TEXT("SDK initialized"));
   }
});
// 登录
sdk.Login([](Status status, const std::string& userId, const std::string& token, const
std::string& message) {
   if (status == Status::Success) {
       // 登录成功
       FString UserIdStr = UTF8_TO_TCHAR(userId.c_str());
       UE_LOG(LogTemp, Log, TEXT("Login success: %s"), *UserIdStr);
   }
});
// ⽀付
sdk.Pay(
   "product_id",
   "商品名称",
   "商品描述",
   6.00f,
   "order_12345",
   "",  // ⽀付回调地址URL
   "",  // Extras
   [](Status status, const std::string& orderNo, const std::string& productId,
      const std::string& transactionId, const std::string& message) {
       if (status == Status::OrderSuccess) {
           // ⽀付成功
       }
   }
);
// 上传⻆⾊
sdk.UpdateRoleInfo(
   "role_123",
   "⻆⾊名",
   "server_id",
   "服务器名",
   "10",  // ⻆⾊等级
   "1",   // VIP等级
   "",    // Power
   "",    // Balance
   ""     // Party
);

7. API参考

7.1 UGameSDKManager类

7.1.1 静态⽅法

获取单例实例

说明：⾸次调⽤会创建实例，后续调⽤返回同⼀实例

7.1.2 初始化与登录

初始化 SDK

回调： OnInitComplete 委托

回调： OnLoginComplete 委托

退出登录，清除登录状态

7.1.3 ⽀付接口

回调： OnPayComplete 委托

7.1.4 角色信息接口

PartyName  - ⼯会名称

7.1.5 ⽤户信息查询

返回值：⽤户ID字符串，未登录时返回空字符串

返回值：⽤户Token字符串，⽤于服务器验证

返回值： true 表示已登录， false 表示未登录

返回值： true 表示是游客， false 表示已绑定账号

7.1.6 回调委托

FOnLoginComplete OnLoginComplete

const FString& Message  - 消息

7.2 QuickGameSDK::SDK类

7.2.1 标准C++接⼝

获取单例实例

初始化 SDK

void Login(LoginCallback callback = nullptr)

void Logout()

退出登录

发起⽀付

std::string GetUserId()

std::string GetUserToken()

获取⽤户Token

是否已登录

7.2.2 回调函数类型

初始化回调

enum class EGameSDKStatus : uint8
{
   Unknown = 0,           // 未知状态
   ErrorNone = 1000,      // 事件成功（登录成功）
   InitSuccess = 2000,    // 初始化成功
   InitFail = 2001,       // 初始化失败
   OrderSuccess = 3000,   // ⽀付成功
   OrderFail = 3001,      // ⽀付失败
   OrderCancel = 3002,    // ⽀付取消
   OrderUnknown = 3003    // ⽀付未知状态
};

if (Status == EGameSDKStatus::InitFail)
{
   // 检查 ProductCode 是否正确
   // 检查⽹络连接
   // 检查 SDK ⽂件是否完整
}

if (Status == EGameSDKStatus::OrderFail)
{
   // 检查⽹络连接
   // 检查商品ID是否正确
   // 检查订单号是否唯⼀
}

FacebookAppID
YOUR_FACEBOOK_APP_ID
FacebookClientToken
YOUR_FACEBOOK_CLIENT_TOKEN
FacebookDisplayName
您的应⽤名称

   CFBundleTypeRole
   Editor
   CFBundleURLSchemes
   
       fbYOUR_FACEBOOK_APP_ID
   

fbapi
fb-messenger-api
fbauth2
fbshareextension

GIDClientID
YOUR_CLIENT_ID.apps.googleusercontent.com

   CFBundleTypeRole
   Editor
   CFBundleURLSchemes
   
       com.googleusercontent.apps.YOUR_CLIENT_ID
   

NSUserNotificationsUsageDescription
需要通知权限以接收推送消息