v2ray_myanmar

Flutter plugin that embeds the V2Ray/Xray core with PRO controls tailored for Myanmar traffic. Run VPN tunnel or local proxy modes, inspect runtime status, and parse popular V2Ray share links from Dart.

Contents

• Features
• Requirements
• Installation
• Quick Start
• Runtime APIs
• Advanced Options
• Share Link Parser
• Platform Notes
• Example App
• Development & Testing
• Troubleshooting
• Contributing
• License

Features

• Dual-mode connectivity: system-level VPN (tun) or local SOCKS/HTTP proxy.
• Live telemetry via callback and statusStream (speed, traffic, state, uptime).
• Health tools: server delay checks, diagnostics map, watchdog, failover list.
• Full control over routing (allow/deny apps, CIDR routes, DNS servers, DoH).
• Share link parser for vmess, vless, trojan, ss, and socks.
• Production-ready Android implementation with notification customization.

Requirements

• Flutter 3.3.0 or newer, Dart 3.1.0 or newer.
• Android API 21+, or iOS 11+ when embedding the plugin.
• For VPN mode on Android, the host app must request VPN permission.

Installation

flutter pub add v2ray_myanmar

or add directly to pubspec.yaml:

dependencies:
  v2ray_myanmar: ^1.0.0

Run flutter pub get after editing the file.

Quick Start

import 'package:v2ray_myanmar/v2ray_myanmar.dart';

final client = V2rayMyanmar(onStatusChanged: (status) {
  // status.state => CONNECTED / CONNECTING / DISCONNECTED
  // status.uploadSpeed & status.downloadSpeed in bytes per second
});

Future<void> connectFromShareLink(String shareLink) async {
  final parsed = V2rayMyanmar.parseFromURL(shareLink);

  await client.initializeV2Ray(
    notificationIconResourceType: 'mipmap',
    notificationIconResourceName: 'ic_launcher',
  );

  if (await client.requestPermission()) {
    await client.startV2Ray(
      remark: parsed.remark.isEmpty ? 'My Server' : parsed.remark,
      config: parsed.getFullConfiguration(),
      proxyOnly: false, // set true for local proxy mode
    );
  }
}

Future<void> disconnect() => client.stopV2Ray();

Runtime APIs

Method	Purpose
initializeV2Ray	Prepares the core and bridges live status updates to your callback.
requestPermission	Prompts Android VPN permission flow; returns true elsewhere.
startV2Ray	Launches V2Ray/Xray with your JSON config and advanced toggles.
stopV2Ray	Stops the service and closes the tunnel/proxy.
statusStream	Listen to broadcast V2RayStatus updates (telemetry + state).
getServerDelay / getConnectedServerDelay	Measure response latency before or after connecting.
getState, getMode, setMode	Inspect and switch between VPN_TUN and PROXY_ONLY.
getLocalProxyPorts	Access automatically assigned local SOCKS/HTTP ports in proxy-only mode.
getDiagnostics	Platform-provided detail map for debugging and health checks.

All APIs throw ArgumentError when JSON payloads are invalid, helping catch misconfigured configs early.

Advanced Options

The startV2Ray call accepts optional tuning parameters:

• failoverConfigs, failoverThresholdMs, healthCheckIntervalMs
• blockedApps, allowedApps, bypassSubnets, routes, excludeRoutes
• dnsServers, preferDoH, dohUrl, dohBootstrap
• enableFakeDNS, fakeIpPool, fakeIpPoolV6
• enableIPv6, proxyOnly, allowInsecure
• showSpeedInNotification, notificationDisconnectButtonName

Example: bypass commonly used LAN ranges while keeping VPN mode active.

const lanBypass = [
  '0.0.0.0/5', '8.0.0.0/7', '11.0.0.0/8', '12.0.0.0/6',
  '16.0.0.0/4', '32.0.0.0/3', '64.0.0.0/2', '128.0.0.0/3',
  '160.0.0.0/5', '168.0.0.0/6', '172.0.0.0/12', '172.32.0.0/11',
  '172.64.0.0/10', '172.128.0.0/9', '173.0.0.0/8', '174.0.0.0/7',
  '176.0.0.0/4', '192.0.0.0/9', '192.128.0.0/11', '192.160.0.0/13',
  '192.169.0.0/16', '192.170.0.0/15', '192.172.0.0/14', '192.176.0.0/12',
  '192.192.0.0/10', '193.0.0.0/8', '194.0.0.0/7', '196.0.0.0/6',
  '200.0.0.0/5', '208.0.0.0/4', '240.0.0.0/4',
];

await client.startV2Ray(
  remark: parsed.remark,
  config: parsed.getFullConfiguration(),
  bypassSubnets: lanBypass,
);

Share Link Parser

The built-in parser converts common V2Ray/Xray share links into complete JSON configurations:

final vmess = V2rayMyanmar.parseFromURL('vmess://...');
final vless = V2rayMyanmar.parseFromURL('vless://...');
final trojan = V2rayMyanmar.parseFromURL('trojan://...');
final shadowsocks = V2rayMyanmar.parseFromURL('ss://...');
final socks = V2rayMyanmar.parseFromURL('socks://...');

final configJson = vmess.getFullConfiguration(indent: 4);

Every parser normalises transport settings, TLS/REALITY options, mux, and removes null values for minimal configs.

Platform Notes

Android

• Add the VPN permission to your host app manifest: <uses-permission android:name="android.permission.INTERNET" /> and <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />.
• For Play Store builds ensure ABI splits include x86_64, armeabi-v7a, and arm64-v8a. Recommended Gradle snippet:

android {
  splits {
    abi {
      enable true
      reset()
      include "x86_64", "armeabi-v7a", "arm64-v8a"
      universalApk true
    }
  }
  buildTypes {
    release {
      ndk {
        abiFilters "x86_64", "armeabi-v7a", "arm64-v8a"
        debugSymbolLevel 'FULL'
      }
    }
  }
}

iOS

• Ensure you have the Network Extension entitlement configured when distributing through the App Store.
• Update the notification icon resources if you provide custom branding.

Example App

Launch example/lib/main.dart to explore a complete UI:

• Import and export server and failover profiles from the clipboard.
• Toggle between VPN and proxy-only modes and inspect live latency.
• Edit allowed/bypassed apps, DNS, routes, DoH, and FakeDNS pools.

cd example
flutter run

Development & Testing

This package enforces flutter_lints and ships unit tests for core behaviour.

flutter analyze
flutter test

The tests cover:

• JSON validation before handing configs to the platform layer.
• Status bridging through initializeV2Ray.
• Share link parsing across all supported protocols.

Troubleshooting

• VPN permission denied: ensure the permission dialog was accepted and no other VPN app is active.
• Invalid configuration: catch ArgumentError from startV2Ray and revalidate your JSON or share link.
• Slow connection: run getServerDelay against multiple URLs and leverage failoverConfigs.
• Notification icon: pass your own notificationIconResourceName when calling initializeV2Ray.

Support

If this plugin helps your project, you can support future development with TRC-20 contributions:

TLbwVrZyaZujcTCXAb94t6k7BrvChVfxzi

Contributing

Pull requests are welcome! Please:

1. Create an issue for major changes.
2. Run flutter analyze and flutter test before submitting.
3. Update documentation and the changelog when relevant.

License

Released under the MIT License. See LICENSE for details.