Integrating the NetGuard SDK

The NetGuard SDK supports common client operating systems. This page provides all integration methods.

• To save costs or avoid technical details, join our Shared Defense Plan.
• To protect your privacy or offer DDoS protection to others, choose Private Deployment.
• You can also Build Your Own Server if you have sufficient funds and experience.

Download the SDK

• Developers need to Click Here to download the NetGuard SDK.
• Before integration, obtain your unique AppID and AppKey from the Dashboard.
• Integrate the NetGuard SDK into Your Client App as needed.

Integration Methods

Microsoft Windows

The Windows version of the NetGuard SDK includes Shield.exe and libshield.dll. The libshield.dll file exports a function named _Init, which follows the C calling convention (__cdecl). Developers can integrate using one of the following methods:

Zero-Code

This method is suitable for developers with limited programming knowledge. Simply create a configuration file, place it along with Shield.exe and libshield.dll, and then run Shield.exe. The configuration file must be named Shield.ini and should contain the following:

[Shield]
AppID = DEVELOPEMENT_APP_ID
; Replace DEVELOPEMENT_APP_ID with your own AppID

Dynamic Library

This method is suitable for developers with a Windows programming background. If you want to ensure that the NetGuard is initialized successfully before running other business logic, this method is recommended. The following code demonstrates how to integrate the SDK in C/C++:

/* 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 (*InitFunc)(char *, char *);
}

// 2. Load the dynamic library at the appropriate time and initialize it
HMODULE hMod = LoadLibrary("libshield.dll");
if (!hMod)
    return; // Failed to find libshield.dll
InitFunc init = (InitFunc)GetProcAddress(hMod, "Init");
if (!init)
    return; // Failed to find Init function
// Replace DEVELOPEMENT_APP_ID with your own AppID
if (init(NULL, "DEVELOPEMENT_APP_ID"))
    return; // Initialization fails if a nonzero value is returned
// Execution continues here if initialization is successful

Google Android

The Android version of the NetGuard SDK comes as a single AAR file. Place this AAR file in the libs directory of your main app project (typically app/libs).

1. Check and Add the Following to Your App-Level build.gradle

android {
    sourceSets.main {
        jniLibs.srcDirs = ['libs']
    }
}
dependencies {
    implementation files('libs/libshield.aar')
}

2. Initialize in the First Activity or Application Class

// Replace DEVELOPEMENT_APP_ID with your own AppID
int iRet = Shield.Init(null, "");
// Initialization fails if a nonzero value is returned

Apple iOS/iPadOS

The iOS version of the NetGuard SDK also supports iPadOS and includes the following two files:

• Header file: Shield.h
• Static library: libshield.a

The following code demonstrates how to load and initialize the NetGuard SDK in Objective-C:

// 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 a appropriate time
Shield *s = [Shield getInstance];
// Replace DEVELOPEMENT_APP_ID with your own AppID
NSInteger iRet = [s Init:nil key:@"DEVELOPEMENT_APP_ID"];
// Initialization fails if a nonzero value is returned

If Initialization Fails

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

Return value	Description
0	Initialization was successful
1	The AppID is null or empty
3	Cannot fetch configuration or no rules set
4	Cannot listen / Port conflict
9	The first parameter must be a null pointer

Obtain the Client's Real IP Address

Under normal circumstances, the origin server can only obtain the IP address of the Persistence Server, not the client’s IP address.

Please Click Here to download the appropriate IP plugin and install it on the origin server to obtain the client’s real IP address.

Please Note

• If the origin server is running Windows, the App services must be restarted after installation.
• If the origin server is running Linux, the plugin will take effect immediately after installation.
• Only Private Deployment or Shared Defense Plan can access the client's real IP.

Next Steps

• Log in to the Dashboard and correctly add forwarding rules as needed.
• Update the existing code to connect to the local loopback IP address instead of the original TCP server.
• Mobile Apps use the loopback IP address 127.0.0.1, while PC devices need to obtain the loopback IP address from the Dashboard.
• If you encounter other issues after integrating the NetGuard SDK, please refer to Frequently Asked Questions.