tencent_location_flutter

English | 简体中文

tencent_location_flutter is the main application-facing package for a federated Flutter wrapper around Tencent Location SDK. It lives in the flutter_tencent_location repository under packages/flutter_tencent_location and resolves the Android/iOS implementation packages automatically.

This is not an official Tencent package and does not represent Tencent Maps or Tencent Location Service.

Installation

dependencies:
  tencent_location_flutter:
    git:
      url: https://cnb.cool/nazo/tencent_location_flutter.git
      path: packages/flutter_tencent_location

Applications do not need to declare tencent_location_flutter_android, tencent_location_flutter_ios, or tencent_location_flutter_platform_interface directly.

Pinned native SDK versions:

Platform	Version	Notes
Android	`7.6.1.8`	Keeps geofencing, scene location, DR, extra data, device ID, and system-cache APIs available
iOS	`4.3.1`	Bundles `TencentLBS.xcframework` and links through SwiftPM

Host Configuration

Android hosts should declare at least:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

Background location, foreground service, and notification permissions must be added by the host application according to its target Android version.

iOS hosts should declare at least:

NSLocationWhenInUseUsageDescription
NSLocationAlwaysAndWhenInUseUsageDescription

Temporary full-accuracy authorization requires NSLocationTemporaryUsageDescriptionDictionary. Background location requires Background Modes > Location updates. Use a real iOS device for Tencent Location SDK verification.

Initialization

final TencentLocation location = TencentLocation.instance;

await location.setUserAgreePrivacy(true);
await location.initialize(
  const InitializeOptions(
    key: 'YOUR_TENCENT_LOCATION_KEY',
    coordinateType: TencentLocationCoordinateType.gcj02,
    requestLevel: TencentLocationRequestLevel.adminName,
  ),
);

Recommended order: get TencentLocation.instance, set privacy consent, initialize the SDK, request system location permissions from the host application, and then start one-shot or continuous location.

One-Shot Location and Address Fields

final TencentLocationData data = await location.getLocationOnce(
  options: const SingleLocationOptions(
    requestLevel: TencentLocationRequestLevel.formattedAddress,
    timeoutMillis: 10000,
  ),
);

print(data.addressDescription);

Field	Meaning
`address`	Native SDK address field
`addressDescription`	Display-oriented address description normalized by the plugin
`poiList`	Nearby POIs, depending on request level and native SDK response

For user-visible location text, prefer TencentLocationRequestLevel.formattedAddress and addressDescription. For nearby POIs, use TencentLocationRequestLevel.poi, but do not assume every result includes a display address.

Continuous Location

final LocationUpdateSession session = await location.startLocationUpdates(
  const LocationUpdateOptions(
    intervalMillis: 15000,
    requestLevel: TencentLocationRequestLevel.adminName,
    backgroundLocation: true,
    androidRequest: AndroidLocationRequestOptions(
      intervalMillis: 15000,
      locationMode: TencentAndroidLocationMode.highAccuracy,
      allowGps: true,
      allowCache: true,
    ),
    androidForegroundNotification: AndroidForegroundNotificationOptions(
      id: 1001,
      channelId: 'location_foreground',
      channelName: 'Tencent Location',
      title: 'Tencent Location',
      text: 'Continuous location is running',
    ),
  ),
);

session.updates.listen((TencentLocationData data) {
  print(data.toMap());
});

session.errors.listen((TencentLocationError error) {
  print(error.toMap());
});

await session.stop();

On Android, when a periodic geo session is already running, Tencent SDK one-shot refresh results follow the current periodic request level. Do not design a periodic geo session plus a one-shot poi request as the stable path for province/city/street/address/POI details. Use adminName or poi as the continuous request level, or stop the geo session before requesting detailed one-shot location.

Heading

Device heading is exposed through an independent event stream and is not derived from location bearing:

await location.startHeadingUpdates();

location.headingUpdates.listen((HeadingData data) {
  print(data.magneticHeading);
});

await location.stopHeadingUpdates();

Android uses SensorManager: TYPE_ROTATION_VECTOR, then TYPE_GEOMAGNETIC_ROTATION_VECTOR, then accelerometer plus magnetometer fallback. iOS uses CLLocationManager.startUpdatingHeading(). Both platforms keep publishing the last known heading roughly every 500 ms while the heading session is active.

Geofencing

await location.addGeofence(
  const GeofenceOptions(
    tag: 'office',
    latitude: 22.543096,
    longitude: 114.057865,
    radiusMeters: 150,
  ),
);

final List<GeofenceInfo> fences = await location.getValidGeofences();

The main package exposes circle, polygon, and district geofences through one Dart API. Runtime events are published through location.geofenceEvents.

China Region and Coordinate Conversion

final bool inChina = isCoordinateInChina(
  latitude: 22.543096,
  longitude: 114.057865,
);

final bool sameResult = location.isCoordinateInChina(
  latitude: 22.543096,
  longitude: 114.057865,
);

isCoordinateInChina(...) is a pure Dart offline function for checking whether a coordinate is inside the China region. The boundary data covers mainland China, Hong Kong, Macau, Taiwan, and islands represented by the source polygons.

Hong Kong, Macau, and Taiwan are all handled as part of the China region by this plugin.

isCoordinateInGcj02TransformRegion(...) only controls whether this plugin applies its WGS84 -> GCJ-02 approximate offset. It is a coordinate-conversion branch and must not be used to infer the China-region boundary or administrative status. Use isCoordinateInChina(...) for the full China-region check.

final TencentCoordinate gcj02 = wgs84ToGcj02(
  latitude: 22.543096,
  longitude: 114.057865,
);

final TencentCoordinate wgs84 = gcj02ToWgs84(
  latitude: gcj02.latitude,
  longitude: gcj02.longitude,
);

Coordinate conversion runs offline in Dart. It does not depend on Android/iOS native SDKs and does not perform network requests. It is suitable for normal mobile location workflows such as coordinate normalization, map display, and track storage preprocessing; it is not intended for surveying, legal boundaries, audits, asset ownership, or other workflows requiring official conversion parameters.

Platform-Specific APIs

Android:

final String? oaid = await location.android.getOaid();
final bool gpsSupported = await location.android.isGpsSupported();

final LocationUpdateSession sceneSession =
    await location.android.startLocationWithScene(
  TencentAndroidLocationScene.sport,
);

iOS:

await location.ios.requestWhenInUseAuthorization();

final LocationAccuracyAuthorization auth =
    await location.ios.requestTemporaryFullAccuracyAuthorization(
  const IosTemporaryAccuracyOptions(
    purposeKey: 'TemporaryLocationReason',
  ),
);

The location.android and location.ios namespaces are reserved for capabilities that cannot be reliably represented as a cross-platform API.

Not Exposed

Native SDK APIs marked as testing, debugging, or internal.
Android setDebuggable and SDK log listener APIs.
Tencent location request allowDirection. Device heading is provided by the independent heading stream; GPS bearing only represents movement direction.

License

Repository-authored wrapper code is licensed under the MIT License, an OSI-approved license. Bundled third-party SDK materials are not relicensed by this package. See ../../THIRD_PARTY_NOTICES.md.