维智定位SDK Flutter 插件：在 Android / iOS / HarmonyOS 上调用原生 Wayz 定位SDK 完成持续定位、正/逆地理编码、场所搜索等功能。

SDK与Flutter插件：Flutter插件源码不附带 Android/ iOS / HarmonyOS SDK，需由开发者自行导入SDK按平台提供集成文档对接。

安装wz_location_plugin

在应用 pubspec.yaml 中依赖本插件：

本地 path

dependencies:
  wz_location_plugin:
    path: ../wz_location_plugin  # 改为相对你工程的实际路径

然后执行：

flutter pub get

Android 集成

下载 SDK

  • 将官网下载的sdk（示例：wayz-sdk-android-7.1.0.jar）放在 android/app/libs/ 下。
  • 在 android/app/build.gradle 中导入sdk。示例
dependencies {
   implementation files('libs/wayz-sdk-android-7.1.0.jar')
}
  • 在 ../wz_location_plugin/android/build.gradle 中导入sdk。示例
dependencies {
  // 这里sdk路径需配置为实际路径
  compileOnly files('../../../android/app/libs/wayz-sdk-android-7.1.0.jar')
}

添加权限（AndroidManifest.xml）

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

    <!--用于进行网络定位-->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"></uses-permission>
    <!--用于访问GPS定位-->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"></uses-permission>
    <!--用于读取手机当前的状态，获取基站信息-->
    <uses-permission android:name="android.permission.READ_PHONE_STATE"></uses-permission>
    <!--用于获取运营商信息，用于支持提供运营商信息相关的接口-->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"></uses-permission>
    <!--用于访问wifi网络信息，wifi信息会用于进行网络定位-->
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"></uses-permission>
    <!--用于获取wifi的获取权限，wifi信息会用来进行网络定位-->
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE"></uses-permission>
    <!--用于访问网络，网络定位需要上网-->
    <uses-permission android:name="android.permission.INTERNET"></uses-permission>
    <!--用于申请调用A-GPS模块-->
    <uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS"></uses-permission>
    <!-- 基础前台服务权限（兼容 Android 8.0-11） -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
    <!-- Android 12+ 定位类前台服务专用权限 -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION"/>
    <!-- 后台定位核心权限（Android 10+） -->
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>

添加定位服务

<application>
    <service android:name="com.wayz.location.WzService"></service>
</application>

iOS 集成

下载 SDK

  1. 从 Wayz 获取官方的 wzLib.xcframework。

  2. 将 wzLib.xcframework 放在ios目录下（即 /ios/WayzLocal/wzLib.xcframework）。

  3. 在 App 的 ios/Podfile 的 target 'Runner' 中flutter_install_all_ios_pods 之前加入pod 'WayzLocal', :path => 'WayzLocal'：

    target 'Runner' do

  # Wayz wzLib.xcframework 为静态产物时需配置静态 linkage
	# 否则 CocoaPods 报 transitive static binary 错误
  use_frameworks! :linkage => :static
  use_modular_headers!
 	# 导入wzLib.xcframework
  pod 'WayzLocal', :path => 'WayzLocal'

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
  target 'RunnerTests' do
    inherit! :search_paths
  end
end

  4. 执行 pod install 后再编译。

  • 最低 iOS 版本与示例一致为 13.0（platform :ios, '13.0'）。

隐私与权限（Info.plist）

至少配置「使用期间」定位用途说明，若需后台定位再配置「始终」相关键，例如：

<key>NSLocationWhenInUseUsageDescription</key>
<string>是否允许使用您的定位？</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>是否允许后台一直使用定位？</string>

需要后台定位时，在 Info.plist 中配置 UIBackgroundModes 含 location。

  <key>UIBackgroundModes</key>
    <array>
    <string>location</string>
  </array>

HarmonyOS 集成

下载 SDK

  1. 从 Wayz 获取官方的 wayz-sdk-hmos-next_3.0.0.har放到应用鸿蒙工程 ohos/libs/
  2. 在应用 ohos/oh-package.json5 中声明依赖。例如："wzlocation": "file:./libs/wayz-sdk-hmos-next_3.0.0.har"
  3. 在 ../wz_location_plugin/ohos/oh-package.json5 中导入sdk。示例
"dependencies": {
    "wzlocation": "file:../../../ohos/libs/wayz-sdk-hmos-next_3.0.0.har"
 }

隐私与权限

在/ohos/entry/src/main/module.json5添加权限：

{
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.LOCATION",
        "reason": "$string:permission_reason_location",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.LOCATION_IN_BACKGROUND",
        "reason": "$string:permission_reason_location_in_background",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "always"
        }
      },
      {
        "name": "ohos.permission.APPROXIMATELY_LOCATION",
        "reason": "$string:permission_reason_approx_location",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.APP_TRACKING_CONSENT",
        "reason": "$string:permission_reason_app_tracking_consent",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.GET_WIFI_INFO",
        "reason": "$string:permission_reason_get_wifi_info",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.GET_NETWORK_INFO",
        "reason": "$string:permission_reason_get_network_info",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.KEEP_BACKGROUND_RUNNING",
        "reason": "$string:permission_reason_keep_background_running",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "always"
        }
      }
    ]
  }
}

在/ohos/entry/src/main/resources/base/element/string.json添加权限说明：

{
  "string": [
    {
      "name": "permission_reason_location",
      "value": "允许应用在前台运行时获取位置信息"
    },
    {
      "name": "permission_reason_location_in_background",
      "value": "允许应用在后台运行时获取位置信息"
    },
    {
      "name": "permission_reason_approx_location",
      "value": "允许应用获取设备模糊位置信息"
    },
    {
      "name": "permission_reason_app_tracking_consent",
      "value": "允许应用获取设备唯一标识符"
    },
    {
      "name": "permission_reason_get_wifi_info",
      "value": "允许应用获取连接wifi信息"
    },
    {
      "name": "permission_reason_get_network_info",
      "value": "允许应用获取网络信息"
    },
    {
      "name": "permission_reason_keep_background_running",
      "value": "允许应用进行长时任务"
    }
  ]
}

Dart 集成与使用

1. 引用

import 'package:wz_location_plugin/wz_location_plugin.dart';

2. 隐私合规

在使用定位功能之前调用以下方法，标识用户已同意隐私政策：

WzLocationPlugin.updatePrivacyShow(true, false);
WzLocationPlugin.updatePrivacyAgree(true);

 

3. 配置 Key

WzLocationPlugin().setApiKey('你的 apiKey');//官网获取

4.单次定位

WzLocationPlugin().setLocationOption(
  WzLocationOption(
    apiKey: '你的 apiKey', //官网获取
    interval: 5000,//定位时间间隔，单位毫秒
    isLocateOnce: true,//是否是单次定位
  ),
);
StreamSubscription<Map<String, Object?>>? onLocationChangedSub = WzLocationPlugin().onLocationChanged().listen(
          (event) => log('onLocationChanged: $event'),
          onError: (Object e, StackTrace st) => log('onLocationChangederror: $e'),
        );
  };
// 调用前需判断是否授权定位相关权限
WzLocationPlugin().startLocation();

5.连续定位

WzLocationPlugin().setLocationOption(
  WzLocationOption(
    apiKey: '你的 apiKey', //官网获取
    interval: 5000,//定位时间间隔，单位毫秒
    isLocateOnce: false,//是否是单次定位
  ),
);
StreamSubscription<Map<String, Object?>>? onLocationChangedSub = WzLocationPlugin().onLocationChanged().listen(
          (event) => log('onLocationChanged: $event'),
          onError: (Object e, StackTrace st) => log('onLocationChangederror: $e'),
        );
  };
// 调用前需判断是否授权定位相关权限
WzLocationPlugin().startLocation();