Getting Started

VPNWholesaler.com Custom In-App SDK is intended for Development Teams that want to fully customize their VPN apps based their requirements.

Custom In-App SDK -vs- VPNGN In-App SDK

Your anticipated development time with the Custom In-App SDK is significantly higher compared to a straightforward VPNGN In-App SDK integration.

Windows C++

System Requirements

Minimum OS version supported: Windows XP

Recommended Development tool

Visual Studio 2015 - Windows XP (v140_xp)

Follow the steps below to add the SDK static lib to your project:

1. Download the static library from the Downloads section
2. Unpack the downloaded archive to a folder.
3. Find both "kucore.lib" and "CoreAPI.h" files.
4. Place "kucore.lib" to a folder that contains the other static libraries of your project, or alternatively create a new folder named "Libs" in your project directory and place the file there.
5. Place "CoreAPI.h" to your project's folder that contains the other header files.
6. Add a new input dependency "CoreAPI.h" in your linker. For example, in MS Visual Studio: Project->Properties->Linker->Input->Additional Dependencies.
7. Add #include "CoreAPI.h" to the file that you plan to use the SDK commands with.
8. From the unpacked archive copy additional dependencies for corresponding architecture. You can find them in Dependencies forlder
9. Add those additional dependencies to linker settings. Essential dependencies are the following:

json-c.lib
libcurl.lib
Iphlpapi.lib
kucore.lib
Rpcrt4.lib
ws2_32.lib
wininet.lib
ssleay32.lib
libeay32.lib
rasapi32.lib

Windows C#

System Requirements

.Net Framework supported: 3.5, 4.5

Recommended Development tool

Visual Studio 2015

Please follow the steps below to use the SDK as a part of a .NET project:

1. Download dynamic library with dependencies
2. Define a callback signature. This callback will be invoked from SDK when the request result is ready. Please note that all operations in the SDK are called asynchronously and callback is invoked in the thread associated with SDK.

    [UnmanagedFunctionPointer(CallingConvention.Cdecl)]
    public delegate bool Callback([MarshalAs(UnmanagedType.LPStr)]string Mesg);

    Callback callback = new Callback(CallbackHandler);

    public bool CallbackHandler(String value)
    {
        Console.WriteLine(‘callback data = ‘ + value);
    }

3. Import main SDK methods from DLL:

    [DllImport("kucore.dll", CharSet = CharSet.Ansi, CallingConvention = CallingConvention.Cdecl)]
    public static extern void CmdProc(String param);

    [DllImport("kucore.dll", CharSet = CharSet.Ansi, CallingConvention = CallingConvention.Cdecl)]

    public static extern int InitOVSCore([MarshalAs(UnmanagedType.FunctionPtr)] Callback callbackPointer, String ovpn_path, bool isIKEv2Mode);
    [DllImport("kucore.dll", CharSet = CharSet.Ansi, CallingConvention = CallingConvention.Cdecl)]
    public static extern void FinalizeOVSCore();

4. Use the SDK methods in the same manner as a C++ project

macOS

System Requirements

Minimum OS version supported: Mac OS X 10.7

Recommended Development tool

Xcode 13

To add SDK static lib to your project:

1. Download the static library from the Downloads section
2. Unpack the downloaded archive to your project's folder
3. Add libkucore.a file to the Linked Framework and Libraries section in your project's General setting page
4. Add #include "CoreAPI.h" to the file that you plan to use the SDK commands with.

Mac Catalyst

System Requirements

Minimum OS version supported: macOS 11, iOS 12.1

Mac Catalyst - Supported Protocols

macOS currently supports only WireGuard and Shadowsocks2 protocols. iOS also supports IKEv2-IPSec.

Follow the following steps in order to use ShadowSocks and Wireguard protocols in your Mac Catalyst app:

1. Open Xcode

2. Create 2 Network Extensions for both protocols:

   a. Go to File -> New -> Target

   b. Select Network Extension

   c. Use product name SocketTunnel for ShadowSocks and WGTunnel for Wireguard

   d. Put the content of the corresponding folder into the newly created extension source code folder

   e. Add Network Extensions capability and select Packet Filter checkbox

3. For SocketTunnel extension ensure that:

   a. Framework and libraries section include: libVPNSDKSocksTunnel.xcframework and Tun2socks.xcframework

   b. Build settings:

     Enable bitcode: No
   
     Swift-Compiler - Search Paths - Import Paths: SocketTunnel

4. Add Swift package: https://git.zx2c4.com/wireguard-apple

5. For WGTunnel ensure that:

   a. Framework and libraries section include: WGTunnel-1.xcframework, WGTunnel-2.xcframework, WireGuardKit

   b. Build settings:

   Enable bitcode: No
   
   Swift-Compiler - Search Paths - Import Paths: WGTunnel

6. Follow step 2 and onwards in the iOS instructions below.

iOS

System Requirements

Minimum OS version supported: iOS 9

Recommended Language

Swift

1. Download the library from the Downloads section and unpack the downloaded archive
2. Access the project on Xcode and Add VPNSDK.framework (or VPNSDK.xcframework for Mac Catalyst) to the Embedded Binaries section in the General tab
3. Turn on Personal VPN capability on Capabilities tab
4. Import the SDK to your main view controller: import VPNSDK
5. Implement OVSNotifyDelegate interface in the view controller class:

    func OVSNotifyCB(_ notify_code: OVS_NOTIFY_CODES, _ err_code: OVS_ERROR_CODES, _ data: String?) { }

6. Intialize SDK in viewDidLoad method of your main view:

    vpnsdk = VPNSDKLib()
    vpnsdk.InitOVSCore(self)

7. Use vpnsdk.CmdProc method to call SDK methods

Android

System Requirements

Minimum OS version supported: Android KitKat API 19

Recommended Development tool

Android Studio

Follow the steps below to add the SDK library to your project:

1. Create new project or open existing one in Android Studio
2. Download the library from the Downloads section
3. Unpack downloaded archive to the libs subfolder of your application
4. Switch to project files view in the project explorer
5. Add SDK to libs folder
6. Add the following lines to your application build.gradle:

    implementation fileTree(include: ['vpnsdk-release.aar'], dir: 'libs')
    implementation 'com.squareup.retrofit2:retrofit:2.3.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.3.0'
    implementation 'com.squareup.okhttp3:logging-interceptor:3.9.1'
    implementation 'com.google.code.gson:gson:2.8.0'
    implementation 'com.wireguard.android:tunnel:1.0.20211029'

7. Syncronize project with gradle files
8. Add import com.vpnwholesaler.vpnsdk.VPNSDK; to the main activity source file
9. Initialize the SDK in Activity OnCreate handler:

    VPNSDK.InitOVSCore(new VPNSDK.OVSNotifyCB() {
    @Override
    public void onNotify(String s) {
    }
    }, this);

10. If you target SDK 31+ add the following code to application section of AndroidManifest:

    <service
    android:name="com.wireguard.android.backend.GoBackend$VpnService"
    android:exported="false"
    android:permission="android.permission.BIND_VPN_SERVICE">
    <intent-filter>
    <action
    android:name="android.net.VpnService" />
    </intent-filter>
    </service>

11. Add the following permissions to AndroidManifest:

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission
    android:name="android.permission.FOREGROUND_SERVICE"/>

12. Create notification icon using Android Studio New Image Asset Wizard

13. Add the following code to AndroidManifest under application section:

    <meta-data
            tools:replace="android:value"
            android:name="VPN_NOTIFICATION_ICON" 
                            android:value="ic_launcher" /> 
    <meta-data
            tools:replace="android:value"
            android:name="VPN_PENDING_INTENT" 
                            android:value="android.intent.action.MAIN" /> 
    <meta-data
            tools:replace="android:value"
            android:name="VPN_PENDING_INTENT_ACTIVITY" 
                            android:value=".MainActivity" /> 

Where:

VPN_NOTIFICATION_ICON is name of icon created at previous step.

VPN_PENDING_INTENT_ACTIVITY: Name of activity which is supposed to be open when user clicks on notification.

VPN_PENDING_INTENT: Intent which is supposed to be invoked when user clicks on notification.

14. Add android.bundle.enableUncompressedNativeLibs=false to gradle.properties file

15. Add android:extractNativeLibs="true" to application tag in AndroidManifest

Linux (Ubuntu)

1. Download the library from the Downloads section and unpack the downloaded archive

2. The library can be used in two different ways:

   2.1. As a static library linked to the application:

   Link the project with lubkucore.a and add -

   #include "CoreAPI.h"

   to the file that you plan to use the SDK commands with.

   2.2. As a separate process listening to commands on localhost:

   Run ovscore binary as a daemon by using the following prompt -

   ovscore -d

   The process will listen to commands on TCP port 6733.

   You can find an example of a client application in the ovsconsole.cpp file.