Repository files navigation

VPN Client Engine Flutter is a Flutter plugin that offers a high-level Dart API for managing VPN connections, making it easy to integrate advanced VPN functionality into Flutter apps. It abstracts the complexities of working with different VPN protocols and drivers, providing a unified interface for developers. The plugin supports multiple VPN protocols, including V2Ray and WireGuard, allowing you to choose the best technology for your needs.

• Cross-Platform Compatibility: Built to work seamlessly across iOS, Android, Windows, macOS, and Linux, offering a consistent Dart interface that hides platform-specific code.
• Intuitive Dart API: Provides a simple, easy-to-use Dart interface for initializing the VPN engine, connecting/disconnecting, managing subscriptions, and listening for events via streams and futures.
• Protocol Agnostic: The core logic is abstracted to support multiple VPN protocols. Currently supportsV2Ray andWireGuard.
• Unified Core Management: Offers the ability to choose between different cores(now supportsV2RayCore andWireGuardCore) via theVpnCore interface, allowing developers to select the VPN technology that best suits their application requirements.
• Powered byflutter_v2ray: Utilizes theflutter_v2ray plugin to manage the core VPN functionality, ensuring a robust and efficient implementation for bothV2Ray andWireGuard.
• Seamless Integration with Native APIs: Leverages platform-specific VPN APIs likeVpnService on Android andNetworkExtension on iOS, ensuring optimal performance and security.

• ✅ iOS (15.0+)
• ✅ Android (5.0+)
• ✅ macOS (Intel/Silicon)
• ✅ Windows
• ✅ Unix (Linux/Debian/Ubuntu)

Each platform leverages native capabilities for VPN functionality:

• Android and iOS: Employs system VPN APIs (VpnService,NetworkExtension) for creating a secure VPN tunnel.
• Desktop (Windows, macOS, Linux): Can establish a TUN interface or operate as a local proxy, configurable based on the chosen driver.

Internally, the plugin acts as a bridge between Dart and the native engine. It uses a combination of Dart FFI (Foreign Function Interface) and platform-specific setup to communicate with the native library. The basic flow:

flowchart LR subgraph subGraph0["Flutter Application"]        UI@{ label: "Your Flutter App (<span style=\"color:\">Flutter UI)</span>" }  end subgraph subGraph1["Flutter Plugin"]        Plugin["VPNclient Engine Flutter"]  end subgraph subGraph2["Native Core"]        Core["VPNclient Engine Library"]  end    UI --> Plugin    Plugin --> Core    Core --> iOS["iOS"] & Android["Android"] & macOS["macOS"] & Windows["Windows"] & Linux["Linux"]    UI@{ shape: rect}

Diagram: Your Flutter app calls into the VPNclient Engine Flutter plugin (Dart layer). The plugin calls the native VPNclient Engine, which interfaces with the OS networking on each platform.

From a developer perspective, you primarily interact with theDart API provided by this plugin. The plugin takes care of invoking native methods and ensures asynchronous operations (like connecting or disconnecting) do not block the UI thread.

Because this plugin sets up actual VPN tunnels, a few platform-specific configurations are required:

• Android: No special code is needed (the plugin internally uses Android'sVpnService), but you must declare the following in your app’s AndroidManifest.xml:

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

  These ensure the app can open network connections and run a foreground service for the VPN. The plugin will handle launching the VPN service. (Note: You donot need to declareBIND_VPN_SERVICE in the manifest; the plugin uses the VpnService class which has that intent filter built-in.)

• iOS: Enable the Personal VPN capability for your app target in Xcode (this adds the necessary entitlements). Additionally, in your Info.plist, you might need to include a usage description for VPN if required. The VPNclient Engine uses a custom bundle identifier for its network extension (click.vpnclient.engine with anallow-vpn key), but if you integrate via this plugin, typically enabling the capability is sufficient. When you run the app the first time, iOS will prompt the user to allow the VPN configuration.

• Windows: The app should be run with administrator privileges to create a TUN interface via WinTun. Alternatively, have the WinTun driver installed (which is usually present if WireGuard is installed on the system). No manifest changes are needed, but the user might need to approve driver installation if not already present.

• macOS/Linux: The application will likely require root privileges or proper entitlements to create a tunnel (on macOS, Network Extension needs to be signed with the correct entitlements; on Linux, either run with root or configure/dev/net/tun access for the user). For development on macOS, you can enable "Network Extensions" in the sandbox if running unsigned.

Once the above are set up, you can use the plugin in your Dart code as shown below.

To start using VPN Client Engine Flutter, ensure you have Flutter installed and set up your project accordingly.

flutter pub add vpnclient_engine_flutter

// Initialize the EngineVPNclientEngine.initialize();// Clear subscriptionsVPNclientEngine.ClearSubscriptions();// Add subscriptionVPNclientEngine.addSubscription(subscriptionURL:"https://pastebin.com/raw/ZCYiJ98W");//VPNclientEngine.addSubscriptions(subscriptionURLs: ["https://pastebin.com/raw/ZCYiJ98W"]);// Update subscriptionawaitVPNclientEngine.updateSubscription(subscriptionIndex:0);// Listen for connection status changesVPNclientEngine.onConnectionStatusChanged.listen((status) {print("Connection status: $status");  });//Connect to server 1awaitVPNclientEngine.connect(subscriptionIndex:0, serverIndex:1);// Set routing rulesVPNclientEngine.setRoutingRules(    rules: [RoutingRule(appName:"YouTube", action:"proxy"),RoutingRule(appName:"google.com", action:"direct"),RoutingRule(domain:"ads.com", action:"block"),    ],  );// Ping a serverVPNclientEngine.ping(subscriptionIndex:0, index:1);VPNclientEngine.onPingResult.listen((result) {print("Ping: sub=${result.subscriptionIndex}, server=${result.serverIndex}, latency=${result.latencyInMs} ms");  });awaitFuture.delayed(Duration(seconds:10));//DisconnectawaitVPNclientEngine.disconnect();

Initializes the VPN Client Engine. This should be called before using any other method.

Connects to the specified VPN server.

• index: Index of the server fromgetServerList().s

Disconnects the active VPN connection.

Returns the current connection status (connected,disconnected,connecting,error).

Fetches the list of available VPN servers.

Pings a specific server to check latency.

• index: Index of the server fromgetServerList().
• Returns: Latency in milliseconds.

Configures routing rules for apps or domains.

• rules: List of routing rules (e.g., route YouTube traffic through VPN, block ads.com).

Loads VPN subscriptions from the provided list of links.

• subscriptionLinks: A list of subscription file URLs.

Returns statistics for the current VPN session (e.g., data usage, session duration).

Enables or disables auto-connect functionality.

• enable:true to enable,false to disable.

Enables or disables the kill switch.

• enable:true to enable,false to disable.

Triggered when VPN connection status changes.

• Payload:ConnectionStatus (e.g.,connected,disconnected,error).

Triggered when an error occurs.

• Payload:ErrorCode andErrorMessage.

Triggered when the VPN server is switched.

• Payload:newServerAddress.

Triggered when a ping operation completes.

• Payload:serverIndex andlatencyInMs.

Triggered when a subscription is loaded successfully.

• Payload:subscriptionDetails.

Triggered periodically with updated data usage statistics.

• Payload:dataUsed anddataRemaining.

Triggered when routing rules are applied.

• Payload:List<RoutingRule>.

Triggered when the kill switch is activated.

Enum:connecting,connected,disconnected,error.

• address
• latency
• location
• isPreferred

• appName
• domain
• action (block,allow,routeThroughVPN).

• type (socks5,http)
• address
• port
• credentials

Enum:invalidCredentials,serverUnavailable,subscriptionExpired,unknownError.

• expiryDate
• dataLimit
• usedData

We welcome contributions! Please fork the repository and submit pull requests.

This project is licensed under theVPNclient Extended GNU General Public License v3 (GPL v3). SeeLICENSE.md for details.

⚠️Note: By using this software, you agree to comply with additional conditions outlined in theVPNсlient Extended GNU General Public License v3 (GPL v3)

For issues or questions, please open an issue on our GitHub repository.