Developer Guide

Install the NetGuard SDK in a Windows, Android, or iOS client app, not the server app. Start by downloading the client SDK, then follow the platform sections for synchronous initialization. Once initialized, the app connects to the SDK's local address and NetGuard forwards its traffic.

Prerequisites

• Confirm the app platforms, minimum OS versions, and release model;
• Identify the TCP, UDP, or in-app web traffic to be forwarded;
• Sign in to the administration console, configure the origin, protocol, and application port, and obtain the AppId;
• Allow approved Shield servers to reach the origin and remove direct-origin addresses;
• Use the files, version, and checksum confirmed for your project.

Integration Flow

1. Download and add the SDK for the target platform;
2. Initialize it synchronously during application startup;
3. After success, point the application at the assigned local address;
4. Validate normal traffic, network changes, node failover, and seamless reconnection;
5. Before release, restrict the origin to approved Shield servers.

Example Projects

The example repository includes Windows, Android, iOS, and UniApp integration examples for SDK initialization and basic forwarding. It is provided for demonstration; use the delivered NetGuard version and project notes for production.

Windows

The Windows SDK provides Shield.exe and Shield.dll and supports Windows 7 or later. Windows applications can use zero-code startup or synchronous dynamic library integration:

Zero-Code Startup

Place Shield.exe, Shield.dll, and the application in one directory. Create Shield.ini, set the AppId and application path, then run Shield.exe:

[Shield]
AppID = YOUR_APP_ID
; Replace YOUR_APP_ID with your own AppId
AppExe = YOUR_APP.exe
; Replace YOUR_APP.exe with the path to your App

AppExe accepts a relative or absolute path. This option is suitable for Windows apps that should integrate without code changes.

Dynamic Library Integration

/* It is recommended to load this dynamic library in a separate process.
 * Loading it directly into the App process might cause the App to crash
 * or fail to connect to the server
 */

// 1. Declare the function from the SDK
extern "C" {
    typedef int (__stdcall *InitFunc)(char *, char *);
}

// 2. Load the dynamic library at the appropriate time and initialize it
HMODULE mod = LoadLibraryA("Shield.dll");
if (!mod)
    return; // Failed to find Shield.dll

InitFunc init = (InitFunc)GetProcAddress(mod, "Init");
if (!init)
    return; // Failed to find Init function

// Replace YOUR_APP_ID with your own AppId
int result = init(NULL, "YOUR_APP_ID");
if (result != 0)
    return; // Initialization fails if a nonzero value is returned
// Execution continues here if initialization is successful

SDK service threads continue running after initialization, so keep the dynamic library loaded until process exit. Run the SDK in a separate process when application isolation is preferable, especially when the Windows app has multiple business processes or could crash after loading the SDK directly. The business processes can then share the local service provided by that dedicated SDK process.

Android

The Android SDK is delivered as an AAR and supports Android 4.4 (API 19) or later. Place it in the application's app/libs directory:

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

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

Initialize it synchronously during application startup:

// Replace YOUR_APP_ID with your own AppId
int result = Shield.Init(null, "YOUR_APP_ID");
if (result != 0) {
    // Initialization fails if a nonzero value is returned
}

Initialization may make network requests. Choose the calling thread to fit your application's startup lifecycle.

iOS

The iOS SDK provides Shield.h and libshield.a, supports iOS/iPadOS 12 or later, and requires the system frameworks listed in the delivery notes:

// 1. First, add libshield.a to your iOS project, otherwise, the build will fail.

// 2. Include the header file
#import "Shield.h"

// 3. Initialize at an appropriate time
Shield *shield = [Shield getInstance];
// Replace YOUR_APP_ID with your own AppId
NSInteger result = [shield Init:nil key:@"YOUR_APP_ID"];
if (result != 0) {
    // Initialization fails if a nonzero value is returned
}

If Initialization Fails

The following table lists common return values of the initialization function.

Code	Meaning
0	Initialization was successful
1	The AppId is null or empty
3	Cannot fetch configuration or no forwarding rule is set
4	Cannot listen on the local address or the port is in use
9	A reserved parameter is invalid

Additional platform codes may be introduced in a delivery. Use the header and notes supplied with that version.

Obtain the Client IP

Under normal circumstances, the origin can obtain the IP address of the Shield server, but not the client's real IP.

Download and install the appropriate real IP plugin on the origin. Supported systems, versions, and deployment files are defined in the project delivery notes.

On Windows, restart the app services after installation. On Linux, the plugin takes effect immediately after installation. Real client IP support is available only in private deployments.

Next Steps

• Log in to the administration console and add the forwarding rules correctly;
• Point the application at the local address assigned to its instance;
• Android and iOS use 127.0.0.1;
• Windows applications obtain their local address from the administration console;
• Use one NetGuard instance per Windows application, with the local address assigned to that instance;
• A Windows application with multiple business processes can share a local service provided by a dedicated SDK process;
• NetGuard does not forward to ports 0–1023.

Release Checklist

1. Allow only approved Shield servers through the origin firewall;
2. Remove direct-origin addresses from the client;
3. Record the SDK version, checksum, and rollback build;
4. Roll out to a controlled client cohort before expanding;
5. Validate application traffic, network changes, sleep, background recovery, and node failover;
6. Monitor origin connections, node bandwidth, client latency, and initialization errors.

For troubleshooting, see Q&A and include the platform, SDK version, error code, time of occurrence, and reproduction steps.