Setup
Installation of the service, basic methods and examples of their use.
Getting Started
Sign in at pango-cloud.com.
Create a project and use a name for your project as a Public key. Private key is optional.
Use SDK where
carrierId
equals given Public Key and backend url equals default SDK url or url provided by Pango team.
Note that at this time, it is not possible for users to create their own accounts directly if they do not already have an account established with us. Please contact your sales representative to initiate account creation as part of the project and client onboarding process or contact us. We apologize for any inconvenience.
Install Unified SDK service
Run the commands below from the directory where SDK service executable is located.
Default installation
UnifiedSDK.Service.exe -i "ServiceName"
where:
-i "ServiceName"
- command to register UnifiedSDK service in the system with the nameServiceName
.
During this call:
Service executable file will be registered as windows service with specified name (
ServiceName
).Service will create the configuration file into the default folder
"C:\ProgramData\UnifiedSDK.Service"
.Service will use default fixed names for the command and event pipes -
UnifiedSDKVPNCommandPipe/UnifiedSDKVPNEventPipe
.
If several service instances are installed this way on one device, it can cause collisions and incorrect interaction between the client (UnifiedSDK Core
) and the host (UnifiedSDK service
).
This installation option is suitable for testing, but use in Production, please use the installation options below.
Static pipe names installation
UnifiedSDK.Service.exe -i "ServiceName" -d "c:\ProgramData\MyApp" -c "CommandPipeName" -e "EventPipeName"
where:
-d "c:\ProgramData\MyApp"
- configure path to the data folder.-c "CommandPipeName"
- command pipe name.-e "EventPipeName"
- event pipe name.
We recommend to specify -d
option to avoid possible conflicts with other applications using the same data folders.
Also we recommend to specify -c
and -e
options to avoid possible conflicts with other applications using the same pipe names.
During this call:
Service executable file will be registered as windows service with specified name (
ServiceName
).Service will create the configuration file into the specified
-d
folder"c:\ProgramData\MyApp"
.Service will use specific names for the command and event pipes -
CommandPipeName/EventPipeName
.
Dynamic pipe names installation
UnifiedSDK.Service.exe -i "ServiceName" -d "c:\ProgramData\MyApp" -dpn "HKEY_LOCAL_MACHINE\SOFTWARE\MyApp"
where:
-dpn "HKEY_LOCAL_MACHINE\SOFTWARE\MyApp"
- enable dynamic pipe names mode and place the generated names to the specified registry key path.
During this call:
Service executable file will be registered as windows service with specified name (
ServiceName
).Service will create the configuration file into the specified
-d
folder"c:\ProgramData\MyApp"
.Service will create dynamic names for the command and event pipes itself and save them in the Windows registry at the specified path.
In this case you must provide same registry path to SDK instance.
Additional information about command line arguments can be found there:
Service command line argumentsSet up UnifiedSDK Core
Add UnifiedSDK.Core.dll
/ UnifiedSDK.Core.net48.dll
to your project.
Create UnifiedSDK.Core.SDK class instance
Default
C#
var sdk = new SDK();
C++
auto sdk = gcnew SDK();
In this case SDK will use default fixed names for the command and event pipes - UnifiedSDKVPNCommandPipe/UnifiedSDKVPNEventPipe
.
Optional parameter MessageFormat
defines the message format for command pipe. By default: MessageFormat.XML
.
Using CreateWithFixedNaming
PipeOptions
CreateWithFixedNaming
PipeOptionsC#
var pipeOptions = PipeOptions.CreateWithFixedNaming("CommandPipeName", "EventPipeName");
var sdk = new SDK(pipeOptions, logger);
C++
auto pipe_options = PipeOptions::CreateWithFixedNaming("CommandPipeName", "EventPipeName");
auto sdk = gcnew SDK(pipe_options, logger);
In this case SDK will use specific names for the command and event pipes - CommandPipeName/EventPipeName
.
Using CreateWithDynamicNaming
PipeOptions
CreateWithDynamicNaming
PipeOptionsC#
var pipeOptions = PipeOptions.CreateWithDynamicNaming("HKEY_LOCAL_MACHINE\SOFTWARE\MyApp");
var sdk = new SDK(pipeOptions, logger);
C++
auto pipe_options = PipeOptions::CreateWithDynamicNaming("HKEY_LOCAL_MACHINE\SOFTWARE\MyApp");
auto sdk = gcnew SDK(pipe_options, logger);
In this case SDK will use the command and event pipe names that were created during the service installation with the -dpn
command line argument.
Initialize the SDK
Initialize the SDK by sending an initialization request to the UnifiedSdkService with the required parameters:
- Backend URI: The URL of the backend API.
- AppVersion: The version of your application.
- CarrierId: The unique public key.
- DeviceId: The device ID.
- DeviceName: The device name.
- [Optional] Reserve URIs: Optional reserve backend server URIs. By default: null.
- [Optional] EventMessageFormat: The format of the event messages from UnifiedSdkService (XML or JSON). By default: MessageFormat.XML
.
- [Optional] Required events from UnifiedSdk service that will be sent by the event pipe. By default: ServiceEvents.Default (StateChanged | ErrorOccurred | TrafficChanged | ProcessExited)
.
- [Optional] PrependDeviceIdWithCarrierId: A value indicating whether to prepend device ID with carrier ID.
- [Optional] PreventDeviceIdEncode: A value indicating whether to prevent device ID encode
C#
var initRequest = new InitializeRequest
{
BaseUri = backendAddress,
ReserveUris = [.. reserveAddresses.Split(Environment.NewLine, StringSplitOptions.RemoveEmptyEntries)],
AppVersion = appVersion,
CarrierId = carrierId,
DeviceId = deviceId,
DeviceName = Environment.MachineName,
EventMessageFormat = MessageFormat.JSON,
Events = ServiceEvents.HydraEvents,
};
var initResponse = await sdk.InitializeAsync(initRequest).ConfigureAwait(false);
C++
auto init_request = gcnew InitializeRequest();
init_request->BaseUri = backend_url;
init_request->AppVersion = "1.0.0.0";
init_request->CarrierId = carrier_id;
init_request->DeviceId = device_id;
init_request->DeviceName = Environment::MachineName;
init_request->EventMessageFormat = MessageFormat::JSON;
init_request->Events = ServiceEvents::HydraEvents;
auto init_response = sdk->Initialize(init_request);
An example response looks as follows:
{
"Message": "Ok",
"Result": "Ok"
}
More details about backend addresses configuration can be found there:
Backend URL ConfigurationDeviceId configuration
To find detailed information about generating a unique Device Identifier, please refer to this page.
Generating a Unique Device IdentifierThe DeviceId used for Backend requests has a default format of <carrier_id>_<device_id>
, which is then encoded to base64. The CarrierId and DeviceId are provided as parameters in the InitializeRequest.
However, the InitializeRequest includes two additional settings that allow you to control the generation of the DeviceId:
PreventDeviceIdEncode
- This setting indicates whether the DeviceId should be encoded to base64. If set to true, the DeviceId will be used as-is without base64 encoding.PrependDeviceIdWithCarrierId
- This setting indicates whether the DeviceId should be prepended with the CarrierId. If set to true, the CarrierId will be added to the beginning of the DeviceId.
var initRequest = new InitializeRequest
{
BaseUri = backendAddress,
ReserveUris = [.. reserveAddresses.Split(Environment.NewLine, StringSplitOptions.RemoveEmptyEntries)],
AppVersion = appVersion,
CarrierId = carrierId,
DeviceId = deviceId,
PrependDeviceIdWithCarrierId = true, // Optional, enabled by defaul
PreventDeviceIdEncode = false, // Optional, disabled by default
DeviceName = Environment.MachineName,
EventMessageFormat = MessageFormat.JSON,
Events = ServiceEvents.HydraEvents,
};
var initResponse = await sdk.InitializeAsync(initRequest).ConfigureAwait(false);
Authentication
Pango Partner VPN Backend supports OAuth authentication with a partner's OAuth server as the primary authentication method.
Steps to Implement OAuth
Deploy and configure the OAuth service. Ensure that the service is publicly available on the Internet.
Configure the Partner Backend to use the OAuth service.
Implement client OAuth for your application.
Retrieve the access token in the client app. This token will be used to initialize and sign in.
Authentication method types
AuthenticationMethod.Anonymous;
AuthenticationMethod.OAuth
AuthenticationMethod.Firebase
Custom Authentication
Login Implementation Example
var loginRequest = new LoginRequest
{
Method = AuthenticationMethod.Anonymous,
Token = null,
};
var loginResponse = await sdk.LoginAsync(loginRequest).ConfigureAwait(false);
An example response looks as follows:
{
"Message": "OK",
"Result": "Ok",
"UserId": "12345678",
...
}
Custom Authentication
Custom Authentication allows you to integrate your existing authentication system with our cloud platform. Instead of using a predefined authentication method such as google
, facebook
, or oauth
, you can pass a custom string identifier to indicate your preferred authentication mechanism.
To implement Custom Authentication:
Replace the authentication method enum value with a string that uniquely identifies your authentication system, such as your company name or a specific identifier.
Obtain a token (
TOKEN
) from your authentication system.Pass this custom string and the token received from your authentication system as parameters to the
LoginAsync
method.
Example login implementation using Custom Authentication:
var loginRequest = new LoginRequest
{
Method = "YourCustomAuthenticationIdentifier",
Token = TOKEN,
};
var loginResponse = await sdk.LoginAsync(loginRequest).ConfigureAwait(false);
Updating the SDK
Follow these steps to update the Unified SDK:
(Optional) Stop the current SDK service.
Download the latest version of the Unified SDK.
Reinstall the SDK service by running the following command:
UnifiedSDK.Service.exe -i "ServiceName" -d "c:\ProgramData\MyApp" -c "CommandPipeName" -e "EventPipeName"
(Optional) Start the Unified SDK service.
Uninstalling the SDK
To uninstall the SDK, run the following command:
UnifiedSDK.Service.exe -u "ServiceName"
App is responsible to install and remove the NetFilter driver on app install/uninstall.
SDK is responsible to start and stop NetFilter driver on SDK service Init and service stop.
Last updated
Was this helpful?