接入 SecureSphere SDK

SecureSphere SDK 支持常见客户端操作系统。本页面提供 Windows、Android、iOS/iPadOS 以及常见跨平台框架的接入说明。

Microsoft WindowsShield.exe / libshield.dll

Google Androidlibshield.aar

Apple iOS / iPadOSShield.h / libshield.a

接入原则
先完成 SDK 初始化并确认返回值为 0，再让业务连接 SecureSphere 在本机提供的回环地址与端口。

接入前准备

1

获取 AppID登录 SecureSphere 用户中心，创建对应实例并获取专属 AppID。用户中心同时可能显示 AppKey；本文客户端初始化示例使用 AppID。

2

下载对应平台 SDK请根据实际发布平台选择 Windows、Android、iOS 真机或 iOS 模拟器版本，不要混用不同平台二进制文件。

3

添加转发规则在用户中心为实例配置实际业务需要的 TCP 转发规则。SDK 初始化需要能够获取到当前 AppID 的有效配置。

不同系统的接入方法

Microsoft Windows

Windows 版本提供 Shield.exe 与 libshield.dll。开发者可根据项目情况选择零代码方式或动态库方式。

零代码接入

适合希望尽量减少代码改动的项目。将 Shield.exe、libshield.dll 与配置文件 Shield.ini 放在同一目录，配置 AppID 后运行 Shield.exe。

ini

[Shield]
AppID = DEVELOPEMENT_APP_ID
; 请将 DEVELOPEMENT_APP_ID 替换为自己的 AppID

动态库接入

适合需要自行控制 SDK 初始化时机的 Windows 项目。当前示例使用导出函数 Init，调用约定为 C 接口形式。

建议
Windows 项目建议在独立进程中加载 SDK 动态库，以降低与主业务进程发生兼容性冲突的可能性。

C / C++

extern "C" {
    typedef int (*InitFunc)(char *, char *);
}

HMODULE hMod = LoadLibrary("libshield.dll");
if (!hMod)
    return;

InitFunc init = (InitFunc)GetProcAddress(hMod, "Init");
if (!init)
    return;

// 请替换为自己的 AppID
int ret = init(NULL, "DEVELOPEMENT_APP_ID");
if (ret != 0)
    return;

// ret == 0，初始化成功

Google Android

Android SDK 以 libshield.aar 提供。将文件放到 App 主工程的 app/libs 目录。

1. 配置 app 级 build.gradle

Groovy

android {
    sourceSets.main {
        jniLibs.srcDirs = ['libs']
    }
}

dependencies {
    implementation files('libs/libshield.aar')
}

2. 在首个 Activity 或 Application 初始化

Java

import net.kaka888.netguard.Shield;

// 请替换为自己的 AppID
int iRet = Shield.Init(null, "DEVELOPEMENT_APP_ID");

if (iRet == 0) {
    // 初始化成功
}

初始化应尽量在业务网络连接建立前完成。不要在业务代码已经大量建立远端连接后才初始化 SDK。

Apple iOS / iPadOS

iOS/iPadOS SDK 包含：

头文件：Shield.h
静态库：libshield.a

请先将静态库加入 Xcode 工程，再包含头文件并初始化。

Objective-C

#import "Shield.h"

Shield *s = [Shield getInstance];

// 请替换为自己的 AppID
NSInteger iRet = [s Init:nil key:@"DEVELOPEMENT_APP_ID"];

if (iRet == 0) {
    // 初始化成功
}

真机与模拟器
请使用与目标环境匹配的 SDK 包。iOS 真机发布使用真机版本；Xcode 模拟器调试请使用对应的 Simulator 版本。两类静态库不要直接互换。

常见开发框架

uni-app / uni-app x

如果项目采用 uni-app / uni-app x，请使用 SecureSphere 提供的专用插件包，而不是只按照原生 Android/iOS 示例直接接入。

插件目录：uni_modules/netguard-sdk
Android 底层仍调用 Shield.Init(null, AppID)
iOS 底层仍调用 SecureSphere iOS 原生初始化接口
业务层调用插件暴露的 Init(AppID) 接口即可

注意
uni-app 客户请使用专用插件包，避免自行混用原生 AAR、iOS 静态库和 UTS 代码。

Cocos Creator

Cocos Creator 最终发布为 Android、iOS 或 Windows 原生客户端时，可以接入 SecureSphere SDK。接入位置在目标平台的原生工程层：

Android：将 libshield.aar 加入导出的 Android 工程，并通过 Java 原生桥接调用初始化。
iOS：将 Shield.h 与 libshield.a 加入 Xcode 工程，通过 Objective-C 原生桥接初始化。
Windows：按 Windows 动态库方式接入。

如果最终发布目标是纯 H5/Web 页面，则不能直接加载 Android AAR、Windows DLL 或 iOS 静态库。

如果初始化失败

初始化接口返回 0 表示成功；非零返回值表示初始化失败。常见返回值如下：

返回值	含义	建议检查
0	初始化成功	可以继续建立业务连接
1	AppID 为空	检查初始化参数是否填写 AppID
3	无法获取配置 / 没有设置有效规则	检查 AppID、用户中心规则是否已配置并生效，以及客户端网络是否能正常获取配置
4	无法监听 / 端口冲突	检查本地监听端口是否已被其他程序占用
9	第一个参数不是空指针	按平台示例将第一个参数传入 NULL / null / nil

排查原则
如果 Init = 3，先排查配置获取与规则；如果 Init = 0 但业务仍不通，再排查回环地址、业务端口以及 HTTP/HTTPS 协议适配。

接入之后的处理

登录 SecureSphere 用户中心，根据业务实际需要添加 TCP 转发规则。
确保 SDK 初始化返回 0。
修改原有客户端连接逻辑：不再直接连接原远端 TCP 服务，而是连接 SDK 在本机提供的回环地址。
移动端本地回环地址统一使用 127.0.0.1；PC 端请使用用户中心提供的回环 IP。
端口按照用户中心对应规则使用。业务端连接的本地端口必须与当前配置匹配。

重要
“初始化成功”和“业务连接成功”是两个阶段。回环地址写错通常不会让 Init 返回 3，但会造成初始化成功后业务连接失败。

HTTP / HTTPS / WebSocket 接入注意事项

SecureSphere 按四层 TCP 方式承载业务连接，不主动修改 HTTP Header、WebSocket 数据或其他应用层内容。因此，使用 HTTP/HTTPS/WSS 时需要注意原业务域名信息是否被保留。

HTTP Host

如果原业务请求为：

http://api.example.com/path

直接改成：

http://127.0.0.1:10000/path

请求中的 Host 可能变成 127.0.0.1。如果源服务依赖域名 Host 进行站点或接口路由，需要在客户端网络层保留/设置原 Host。

WebView 项目
如果业务基于 WebView，JavaScript 层直接修改受限制的 Host Header 往往不会生效。应在 Android/iOS 原生网络层进行请求拦截与适配，例如使用项目实际采用的 URLConnection、OkHttp 或等价网络组件。

HTTPS / WSS

HTTPS 与 WSS 除 Host 外还涉及证书域名与 TLS SNI。不要在未处理证书/SNI 的情况下简单把原域名全部替换成 127.0.0.1。建议保留原业务域名语义，并根据客户端网络库完成本地接入适配。

WebSocket

WebSocket 基于 TCP，可以通过原生客户端 SDK 承载。普通 ws:// 主要关注地址与端口；wss:// 还需要同时处理 TLS 证书与 SNI。

获取客户端真实 IP

正常情况下，回源服务器获取到的并不是终端客户端的真实 IP。若源服务需要获得客户端真实 IP，请登录 SecureSphere 用户中心下载对应平台的真实 IP 插件并安装到回源服务器。

Windows 回源服务器：安装插件后，需要重启对应的 App 服务端进程。
Linux 回源服务器：按提供的插件说明完成编译与安装后生效。

真实 IP 插件属于服务器侧配套组件；客户端 SDK 本身无需额外修改业务数据。

常见问题

1. Init 返回 3，但 AppID 已确认正确

继续检查该 AppID 是否存在有效转发规则、规则是否已启用并生效，以及当前客户端网络是否能够正常获取 SDK 配置。

2. Init 返回 0，但接口没有数据

优先检查业务是否真正连接了正确的本地回环 IP 与端口；如果是 HTTP/HTTPS/WebSocket，再检查 Host、SNI、证书和原业务协议是否保持一致。

3. 回环 IP 写错会导致 Init 返回 3 吗？

通常不会。回环 IP 是初始化成功以后业务连接 SDK 使用的地址；回环地址错误更常见的表现是 Init = 0，但后续业务无法建立连接。

4. 本地端口被其他程序占用怎么办？

SDK 无法建立本地监听时可能返回 4。请释放冲突端口或调整规则后重新初始化。

5. Cocos / uni-app 是否需要重新开发一套 SDK？

不需要。底层仍使用 SecureSphere 对应平台的原生 SDK；差异在于跨平台框架需要增加一层原生桥接。uni-app 请优先使用官方提供的专用插件包。