跳到主要内容
版本：1.10.x

SDK 安装及应用

iOS 要求​

为了在 iOS 环境中使用 AppGuard SDK，需要满足以下要求。

  • Xcode 15.X
  • AppGuard for iOS SDK v1.10.1.3 及以上

AppGuard SDK 安装及应用​

AppGuard SDK 下载​

为了应用 AppGuard SDK，需要下载必要的文件。在 AppGuard Manager 中下载 SDK 及配置文件。

项目说明
AppGuard SDK以 static framework 形式提供的 AppGuardCore.framework
AppGuard Config FilesAppGuard 运行所需的配置文件 (appguard, appguard.crt, appguard.mf, appguard106000)
提示

请从项目中删除现有使用的 AppGuardCore.xcframework。

AppGuard SDK 应用方法​

  1. 将下载的 AppGuardCore.framework 文件复制到项目中。

  2. 在 Xcode 中选择 Project > TARGETS:ProjectName > Build Phases > Link Binary With Libraries，然后点击底部的 添加[+] 按钮。

  3. 在 [Choose frameworks and libraries to add:] 窗口中点击 [Add Other] 按钮，然后选择 [Add Files...]。

  4. 选择项目中复制的 AppGuardCore.framework 文件，并点击 [Open] 按钮。

  5. 确认 Link Binary With Libraries 部分已添加 AppGuardCore.framework 文件。

  6. 将 AppGuardCore.framework 的 Embed 属性设置为 Do Not Embed。

  • 在 Xcode 中的 Project > TARGETS:ProjectName > Build Settings > Other Linker Flags 项中添加 -lstdc++, -lz 选项。

AppGuard Config Files 应用方法​

  1. 将下载的最新配置文件 4 个（appguard, appguard.crt, appguard.mf, appguard106000）复制到项目中。

  2. 在 Xcode 中选择 Project > TARGETS:ProjectName > Build Phases > Copy Bundle Resources，然后点击底部的 添加[+] 按钮。

  3. 在 [Choose items to add:] 窗口中点击 [Add Other] 按钮。

  4. 选择项目中复制的 4 个配置文件，并点击 [Open] 按钮。

  5. 确认 [Copy Bundle Resources] 部分已添加配置文件。

在 Objective-C 中使用 AppGuard SDK​

必须的 API 应用​

为了使用 AppGuard SDK，需要实现以下的必需 API。

回调函数介绍​

AppGuard SDK 提供回调函数，以便将 AppGuard 的操作状态和检测事件信息传递给应用程序。此回调函数需要通过 APPGUARD_INIT API 注册到 AppGuard SDK。

typedef void (*PAPPGUARDAPPCALLBACK)(int type, int code, const char *pData);
static void APPGUARD_INIT(PAPPGUARDAPPCALLBACK);
警告

回调函数必须在项目中实现，并在调用 APPGUARD_INIT 时作为参数传递。

回调函数实现及注册​

回调函数应在应用程序的入口点最先注册。通常建议在 AppDelegate 源文件中实现和注册。

AppDelegate.m
/**
  * 声明与 AppGuard SDK 通信的回调函数
  * 通常建议在 AppDelegate 源文件顶部实现。
  */ 

#import <AppGuardCore/AppGuard.h>
#import <AppGuardCore/AppGuardDefine.h>

static void AppGuardAppCallback(int type, int code, const char* desc)
{
  if(type == APPGUARD_TYPE_KILL) 
  {
      /**
      * 如果检测到的内容根据策略设置为 kill 选项，则请求强制退出。
      * 检测到此消息时，应强制退出应用程序。
      * 建议通过消息框通知后退出应用程序。
      */
  }
  else if(type == APPGUARD_TYPE_S2AUTH_CALLBACK) 
  {
      if(code == APPGUARD_TYPE_CSAUTH_SUCCESS)
      {
        /**
          * 服务器认证成功。
          * 请使用 desc 参数传递的服务器认证 ID 在游戏服务器上执行重新验证操作。
          *
          * desc : 服务器认证 ID
          */

      }
      else if(code == APPGUARD_TYPE_CSAUTH_FALSE)
      {
        /**
          * 服务器认证失败。
          * 请使用 desc 参数传递的服务器认证 ID 在游戏服务器上执行重新验证操作。
          *
          * 服务器认证失败的原因可能是客户端的网络问题，因此需要通过游戏服务器进行重新验证。
          *
          * desc : 服务器认证 ID
          */
      }
  }
}

...

/**
  * 注册与 AppGuard SDK 通信的回调函数
  *
  * 使用 APPGUARD_INIT API 注册回调函数。
  *
  * 建议在 AppDelegate 的 didFinishLaunchingWithOptions 函数中实现 APPGUARD_INIT API。
  */ 
- (Bool)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *) launchOptions {
  // 使用 APPGUARD_INIT API 将回调函数注册到 AppGuard SDK
  APPGUARD_INIT(AppGuardAppCallback);
}

完成上述操作后，即可准备好使用 AppGuard SDK。构建并运行项目以确保 AppGuard SDK 正常工作。

提示

有关 AppGuard SDK 提供的 API 的详细信息，请参阅 AppGuard SDK API Reference。

在 Swift 中使用 AppGuard SDK​

AppGuard Swift 接口说明​

要在使用 Swift 编写的项目中使用用 Objective-C 编写的 AppGuard API，需要使用 Bridging Header 方式。为了便于在 Swift 项目中使用用 Objective-C 编写的 AppGuard API，提供以下 3 个文件。

文件名说明语言
AppGuard-Bridging-Header.h用于连接 Swift 和 Objective-C 模块的 Bridging HeaderObjective-C
AppGuardWarpper.hAppGuard API 接口声明Objective-C
AppGuardWarpper.mmAppGuard API 接口实现Objective-C

AppGuard Swift 接口 Bridging 应用​

  1. 将下载的 AppGuard Swift 接口文件夹 /appguard_swift_interfaces 内的 3 个文件（AppGuard-Bridging-Header.h, AppGuardWrapper.h, AppGuardWrapper.mm）复制到项目文件夹中。

  2. 通过 [Drag & Drop] 将复制的文件添加到 Xcode 项目中。

  3. 在 [Choose options for adding these files:] 窗口中点击 [Finish] 按钮。

  4. 在 [Would you like to configure an Objective-C bridging header?] 窗口中点击 [Don't Create] 按钮。

  5. 在 Project > TARGETS:项目名称 > Build Settings > Swift Compiler - General > Objective-C Bridging Header 项中添加 $(SRCROOT)/MyProject/AppGuard-Bridging-Header.h 路径。

信息

完成上述操作后，即可准备好在 Swift 项目中使用 AppGuard API。

AppGuard Swift API 必须应用​

回调函数介绍​

对于 Swift 项目，AppGuardWarpper.mm 文件顶部定义了 APPGUARDGAMECALLBACK 函数。此函数用于检测和报告恶意用户的异常行为。如果根据管理页面设置的安全策略需要强制退出，则会通知应用程序。

可以按照以下示例代码进行应用，以处理检测和报告的内容。

AppGuardWarpper.mm
// AppGuardWarpper.mm

static void APPGUARDGAMECALLBACK(int type, int code, const char* desc)
{
  if(type == APPGUARD_TYPE_KILL) 
  {
      /**
      * 如果检测到的内容根据策略设置为 kill 选项，则请求强制退出。
      * 检测到此消息时，应强制退出应用程序。
      * 建议通过消息框通知后退出应用程序。
      */
  }
  else if(type == APPGUARD_TYPE_S2AUTH_CALLBACK) 
  {
      if(code == APPGUARD_TYPE_CSAUTH_SUCCESS)
      {
        /**
          * 服务器认证成功。
          * 请使用 desc 参数传递的服务器认证 ID 在游戏服务器上执行重新验证操作。
          *
          * desc : 服务器认证 ID
          */

      }
      else if(code == APPGUARD_TYPE_CSAUTH_FALSE)
      {
        /**
          * 服务器认证失败。
          * 请使用 desc 参数传递的服务器认证 ID 在游戏服务器上执行重新验证操作。
          *
          * 服务器认证失败的原因可能是客户端的网络问题，因此需要通过游戏服务器进行重新验证。
          *
          * desc : 服务器认证 ID
          */
      }
  }
}
提示

请在 APPGUARDGAMECALLBACK() 函数内实现退出消息处理逻辑。

警告

在服务发布时，请务必 移除 APPGUARDGAMECALLBACK() 函数内的日志输出函数。

回调函数注册​

AppGuard 初始化并与 SDK 通信所需的必需 API 函数。请在 AppDelegate.swift 的 application 函数内务必调用 AppGuard 初始化函数 APPGUARD_INIT API。这是在 Swift 项目中注册回调函数的操作。

AppDelegate.swift
// AppDelegate.swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions:
    [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        //* 使用 APPGUARD_INIT API 将回调函数注册到 AppGuard SDK
        let obj = AppGuardWarpper()
        obj.initAppGuard()

        return true
    }
信息

完成上述操作后，即可准备好在 Swift 项目中使用 AppGuard。

提示

有关 AppGuard SDK 提供的 API 的详细信息，请参阅 AppGuard SDK API Reference。

AppGuard SDK Privacy Manifests 应用​

要在 AppGuard SDK v1.10.1.3 版本及以上中应用 Privacy Manifests，请按照以下步骤操作。

AppGuardCore.framework 的模块将 与链接 AppGuardCore.framework 的 TARGETS 合并并分发。

与 Apple 的 Privacy Manifests 相关的 PrivacyInfo.xcprivacy 必须 包含在链接 AppGuard SDK 的 TARGETS 的 PrivacyInfo.xcprivacy 中 AppGuardCore.framework 的 PrivacyInfo.xcprivacy 内容。

因此，请参考以下指南进行合并操作，以 将 AppGuardCore.framework 相关内容添加到 PrivacyInfo.xcprivacy 中。

  • 如果 Xcode 项目中 已经存在使用中的 PrivacyInfo.xcprivacy 文件

    • 比较 AppGuardCore.framework 内部的 PrivacyInfo.xcprivacy 文件与现有的 PrivacyInfo.xcprivacy 文件，确认缺失部分。
    • 如果有缺失部分，请将其添加到现有的 PrivacyInfo.xcprivacy 文件中并合并。

  • 如果 Xcode 项目中 不存在 PrivacyInfo.xcprivacy 文件

    • 请按照与 AppGuard Config Files 添加方式相同的步骤进行以下操作。

      • 复制 AppGuardCore.framework 内部的 PrivacyInfo.xcprivacy 文件并添加到 Xcode 项目中。

      • 在 Xcode 中选择 Project > TARGETS:ProjectName > Build Phases > Copy Bundle Resources，然后点击底部的 添加[+] 按钮。

      • 在 [Choose items to add:] 窗口中点击 [Add Other] 按钮。

      • 选择复制的 PrivacyInfo.xcprivacy 文件，并点击 [Open] 按钮。

      • 确认 [Copy Bundle Resources] 部分已添加 PrivacyInfo.xcprivacy 文件。

信息

在 AppGuard for iOS SDK v1.10.1.3 版本及以上中，以 AppGuardCore.framework 名称分发，且该 SDK 以 static framework 制作并分发。

提示

在 AppGuard for iOS SDK v1.10.1.3 版本及以上中，Apple 要求的 Privacy Manifest 中指定的 Required reason API 项目中，除 NSPrivacyAccessedAPICategoryUserDefaults 外未使用其他 API。

对于 以 static framework 链接的第三方 SDK，可能也需要与 AppGuard SDK 一样进行 客户的 PrivacyInfo.xcprivacy 合并操作。