sh_country_detector

A lightweight, permissionless, and offline-first Flutter utility to detect the user's country automatically using device-side signals (SIM, Timezone, and Locale).

🚀 Why use sh_country_detector?

• Zero Permissions: No need for NSLocationWhenInUseUsageDescription or ACCESS_FINE_LOCATION. Respects user privacy.
• Offline First: Works without an internet connection using IANA timezone mappings.
• Lightning Fast: No network calls, no IP lookups, zero latency.
• Privacy Focused: No data ever leaves the device.
• Cross-Platform: Supports Android, iOS, Web, macOS, Windows, and Linux.

🛠 How it works

The detector uses a prioritized fallback strategy to determine the country:

1. SIM/Network Country Code (Mobile): Uses hardware signals from the SIM card/network provider for highest accuracy.
2. Timezone Mapping (Global): Maps the device's IANA Timezone ID (e.g., Europe/London) to a country code using an internal database of ~400 zones.
3. System Locale (Fallback): Uses the user's regional settings (e.g., en_US -> US) as a final fallback.

📦 Installation

Add this to your pubspec.yaml:

dependencies:
  sh_country_detector: ^0.0.1

💻 Usage

import 'package:sh_country_detector/sh_country_detector.dart';

void main() async {
  // Detect the user's country
  final Country? country = await CountryDetector.detect();

  if (country != null) {
    print('Detected: ${country.name} (${country.isoCode})');
  } else {
    print('Could not detect country');
  }
}

The Country Model

The Country object provides basic ISO 3166-1 information:

class Country {
  final String isoCode; // e.g., "US"
  final String name;    // e.g., "United States"
}

📱 Platform Support

iOS / Android note

For mobile platforms, the package uses MethodChannel to access native APIs for SIM and Timezone information. No extra configuration in AndroidManifest.xml or Info.plist is required!

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.