Flutter 插件开发实战：桥接原生 SDK
Flutter 的强大之处在于其跨平台能力，而 Flutter 插件（Plugin） 则是实现与平台特定功能（如您的广告 SDK）通信的桥梁。
本文将一步步通过了解原理，配置环境，创建项目，指导您完成一个基础 Flutter 插件的创建、原生代码的集成，最终实现 Flutter 层对底层原生 SDK 的调用。
一、Flutter 插件开发核心原理
Flutter 插件是 Dart 代码和平台特定原生代码的结合体。它们之间通过 Platform Channel (平台通道) 进行通信，主要涉及三个关键概念：
| 概念 |
作用 |
MethodChannel |
负责 Dart 层与原生层之间的 方法调用 和 数据传输。 |
| Dart 层 |
插件的公共接口，供 Flutter 应用调用。它通过 MethodChannel 将方法调用发送给原生层。 |
| 原生层 (Android/iOS/HarmonyOS) |
接收 Dart 发来的调用，执行原生 SDK 的功能（如初始化、加载广告），并将结果通过 MethodChannel 返回给 Dart 层。 |
二、开发环境准备
涉及到的平台有Android、IOS、Harmony，会涉及到Flutter 环境的切换，所以安装FVM进行项目Flutter环境版本管理。下面是对版本管理工具 FVM 的安装、常用命令，以及项目启动、依赖构建和在各平台 IDE 中打开的全部流程。
1. FVM (Flutter 版本管理) 环境安装
FVM (Flutter Version Management) 是一款强大的工具，用于管理和切换不同 Flutter 项目所需的 SDK 版本。安装如下，可以下载一个flutter_sdk 并在系统环境变量Path中配置dart的bin路径，通过dart pub global activate fvm 进行下载安装fvm，或者选择Chocolatey。
windows: 在系统环境变量中配置dart_sdk环境。
mac: 在.bash_profile中配置dart_sdk环境。
| 步骤 |
操作 |
说明 |
| 1. 基础 Flutter SDK |
首先需 下载并安装 基础的 Flutter SDK。 |
这是 FVM 依赖运行的环境基础。 |
| 2. 配置 Dart 环境变量 |
确保 Dart SDK 的路径已添加到您的系统 Path 环境变量 中。 |
Dart SDK 随 Flutter SDK 一起提供，完成 Flutter 环境变量配置即可。 |
| 3. 安装 FVM |
在命令行（CMD 或 PowerShell）中执行 Dart 包全局激活命令： |
dart pub global activate fvm |
安装完FVM之后，会在用户名下生成fvm目录，这里可以通过 fvm config --cache-path D:\...\fvm <换成自己的路径> 设置。并将其路径配置到环境变量中。
用于不同flutter_sdk版本缓存。如下：
执行完 fvm install 3.35.3等之后就会在fvm/versions/下载对应flutter版本。而当前我们系统环境配置的是Google Flutter环境，而鸿蒙版的flutter_sdk是无法通过fvm install 来下载的。我们只需要进入到fvm/versions下面打开命令行，通过git克隆即可。鸿蒙官方文档
git clone -b 3.22.0-ohos https://gitcode.com/openharmony-tpc/flutter_flutter.git custom_3.22.0
mac:
windows:
fvm config --cache-path D:\wangfei\soft\flutter_windows\fvm 操作之后，会将Flutter_SDK每一个版本缓存到此路径下versions里面。作为fvm缓存仓库。这里建议将fvm缓存仓库和项目放在同一磁盘里面例如都在D盘。
2. FVM 常用操作命令
安装 FVM 后，您可以使用以下命令来管理和设置项目所需的 Flutter SDK 版本。
| 命令 |
作用 |
默认路径（示例） |
fvm install <version> |
下载指定版本的 Flutter SDK 到 FVM 的本地缓存中。 |
Windows: C:\Users\用户名\fvm\versions
mac:/Users/用户名/fvm/versions
|
fvm list |
在项目根目录下执行，查看 FVM 缓存中已安装的所有 SDK 版本。 |
- |
fvm use <version> |
在项目根目录下执行，使当前项目配置并使用指定的 Flutter SDK 版本。 |
在项目根目录创建 .fvm 文件夹。 |
fvm list可以查看当前导入fvm的所有flutter_sdk版本。下面都是通过fvm install version 下载配置的。
3. 创建 Flutter 插件项目
使用 flutter create 命令并指定类型为 plugin，即可创建一个包含所有平台代码模板的插件项目。
假设您的插件名为 ads_sdk。
如果要支持鸿蒙，需要在创建项目的文件夹下面，执行fvm flutter use custom_3.22.0，
让其后续支持鸿蒙环境下执行命令。避免创建失败。
# --template=plugin 表示创建插件项目
fvm flutter create --template=plugin --platforms=android,ios,ohos ads_sdk
选择编译器打开，我使用的是AndroidStudio
4. 首次运行与构建依赖
在项目环境中，执行以下步骤以准备编译所需的依赖和平台工具。
A. 下载平台编译工具
这是首次切换 Flutter 版本或首次运行项目时，Flutter SDK 为项目下载 运行所需的“平台工具”和“Web SDK” 的正常准备步骤。
在项目根目录下，执行任务 Flutter 命令触发：
fvm flutter run
custom_3.22.0 是鸿蒙端环境
B. 构建平台依赖
在进入原生 IDE 之前，建议先构建一次 Flutter 插件，为各平台生成所需的配置文件和代码。
进入项目 example 目录 下对应的平台文件夹（例如：ads_sdk/example/android），然后执行相应的构建命令：
| 平台 |
目标目录 |
构建命令 |
| Android |
ads_sdk/example/android |
fvm flutter build apk --debug 或 --release
|
| iOS |
ads_sdk/example/ios |
fvm flutter build ipa --release (通常用于发布) |
| HarmonyOS (Ohos) |
ads_sdk/example/ohos |
fvm flutter build hap --release |
5. 打开与配置各平台项目
在完成上述构建步骤后，即可使用各平台的原生 IDE 打开项目，并进行后续的库依赖配置和开发工作。
| 平台 |
IDE |
打开路径 |
关键操作 |
| Android |
Android Studio |
ads_sdk/example/android |
打开项目后，等待 Gradle 同步完成，然后进行原生库依赖配置。 |
| HarmonyOS |
DevEco Studio |
ads_sdk/example/ohos |
打开项目，配置原生 SDK 依赖。 |
| iOS |
Xcode |
ads_sdk/example/ios/Runner.xcworkspace |
务必打开 .xcworkspace 文件，配置原生库依赖。 |
完成在原生 IDE 中项目的打开和库依赖的配置后，您就可以开始进行 Flutter 插件的原生层开发工作。
因为我们创建的是flutter插件项目，所以各端编译器打开构建依赖完成之后。互相之间的依赖都已完成。直接可以进行开发了。
下图是AndroidStudio打开项目/example/android，依赖同步完成之后的目录。我们主要的开发工作也在ads_sdk这个module中进行。
下图是DevEco Studio打开项目/example/ohos，依赖同步完成之后的目录。我们主要的开发工作也在ohos.ads_sdk这个module中进行。
四、Flutter 层 (Dart) API 设计与实现
这次文章基于我们原生各端【Android、IOS、Harmony】广告SDK进行开发一款Flutter插件，其目的是让Flutter项目开发者可以快速的接入我们的广告SDK【广告，聚合】。
明确开发流程：
我们创建的Flutter插件项目，其项目下/lib 是flutter统一调用公共层，而amps/android|ios|ohos 是各个对应平台需要实现调用各端广告SDK的模块。
[Flutter项目] //example【相当于媒体项目，这个不用管，一般作为demo运行验证】
↓
[Flutter插件 SDK层] //amps_sdk/lib
↓
[各端 SDK（aar、framwork、har）] //amps_sdk/android|ios|harmony
1. 定义 MethodChannel
在 Dart 代码中，首先初始化 MethodChannel，通道名称需要保持 Android/iOS/Windows 原生代码中的通道名称一致（通常默认是 ads_sdk）。
默认会在lib下面创建三个文件，ads_sdk.dart、ads_sdk_method_channel.dart、ads_sdk_platform_interface.dart 。提供了一个获取平台版本的案例，我全部删除，在ads_sdk创建一个全局唯一的MethodChannel ，当然MethodChannel 可以创建多个。我这里默认所有的Flutter端调用都通过此通道进行。
// lib/ads_sdk.dart
import 'package:flutter/services.dart';
class AmpsSdk {
static const MethodChannel channel = MethodChannel('amps_sdk');
}
2. Flutte层设计实现
广告SDK，简单的几个模块，SDK初始化、开屏、插屏、原生、自渲染。所以我们在Flutter端也分为五个模块。
为了和Android以及Harmony各端原生广告SDK调用一致，我们尽可能Flutter调用也统一。如下是Flutter调用样式
AMPSAdSdk().init(sdkConfig, _callBack);。初始化SDK，入参为sdkConfig(sdk)所需要的各种参数，_callBack 初始化成功失败相关回调。
flutter 没有接口，所以通过方法类型参数代替实现回调。其他入参过多，通过构造者模式设计接口。可以查看相关数据文件。
import 'dart:async';
import 'ads_sdk.dart';
import 'data/amps_init_config.dart';
import 'data/common.dart';
class AMPSAdSdk {
AMPSIInitCallBack? _callBack;
static bool testModel = false;
AMPSAdSdk() {
AdsSdk.channel.setMethodCallHandler(
(call) async {
switch (call.method) {
case AMPSInitChannelMethod.initSuccess:
_callBack?.initSuccess?.call();
break;
case AMPSInitChannelMethod.initializing:
_callBack?.initializing?.call();
break;
case AMPSInitChannelMethod.alreadyInit:
_callBack?.alreadyInit?.call();
break;
case AMPSInitChannelMethod.initFailed:
var map = call.arguments as Map<dynamic, dynamic>;
_callBack?.initFailed?.call(map[AMPSSdkCallBackErrorKey.code],
map[AMPSSdkCallBackErrorKey.message]);
break;
}
},
);
}
// 发送数据给native
Future<void> init(AMPSInitConfig sdkConfig,AMPSIInitCallBack callBack) async {
_callBack = callBack;
// 使用时
await AdsSdk.channel.invokeMethod(
AMPSAdSdkMethodNames.init,
sdkConfig.toMap(AMPSAdSdk.testModel),
);
}
}
typedef InitSuccessCallBack = void Function();
typedef InitializingCallBack = void Function();
typedef AlreadyInitCallBack = void Function();
typedef InitFailedCallBack = void Function(int? code, String? msg);
// 1. 定义回调接口（抽象类）
class AMPSIInitCallBack {
// 初始化成功的回调
late final InitSuccessCallBack? initSuccess;
// 正在初始化的回调
late final InitializingCallBack? initializing;
// 已经初始化的回调
late final AlreadyInitCallBack? alreadyInit;
// 初始化失败的回调
late final InitFailedCallBack? initFailed;
AMPSIInitCallBack({this.initSuccess, this.initializing, this.alreadyInit, this.initFailed});
}
入参AMPSInitConfig如下，通过构造者模式构建API，为了大量的数据传递和解析方便我这里采用了Map传递。只需要Flutte端key和各端一一对应即可。
import 'amps_sdk_api_keys.dart';
//UI模式【自动、黑色、浅色】
enum UiModel { uiModelAuto, uiModelDark, uiModelLight }
//坐标系类型
enum CoordinateType {
wgs84('WGS84'),
gcj02('GCJ02'),
baidu('BAIDU');
final String value;
const CoordinateType(this.value);
@override
String toString() => value;
}
//适龄标记
enum UnderageTag {
unknown(-1),
maturity(0),
underage(1);
final int value;
const UnderageTag(this.value);
}
//初始化设置, 国家类型选项
class CountryType {
static const COUNTRY_TYPE_CHINA_MAINLAND = 1;
static const COUNTRY_TYPE_OTHER = 0;
}
//支持的货币类型
class CurrencyType {
static const CURRENCY_TYPE_CNY = "CNY"; //人民币
static const CURRENCY_TYPE_USD = "USD"; //美元
static const CURRENCY_TYPE_JPY = "JPY"; //日元
static const CURRENCY_TYPE_EUR = "EUR"; //欧元
static const CURRENCY_TYPE_GBP = "GBP"; //英镑
static const CURRENCY_TYPE_IDR = "IDR"; //印尼盾
static const CURRENCY_TYPE_MYR = "MYR"; //马来西亚林吉特
static const CURRENCY_TYPE_PHP = "PHP"; //菲律宾比索
static const CURRENCY_TYPE_KRW = "THB"; //泰铢
}
/// 记录三方传入的位置信息，用于上报
class AMPSLocation {
/// 经度
double? longitude;
/// 纬度
double? latitude;
/// 坐标系类型，对应原代码中的AMPSConstants.CoordinateType
/// （默认 0：GCJ02 1:WGS84 2:BAIDU，仅支持QM渠道）
CoordinateType? coordinate;
/// 时间戳
int? timeStamp = 0;
/// 构造函数，支持初始化时设置属性
AMPSLocation({
this.longitude,
this.latitude,
this.coordinate,
int? timeStamp,
}) {
this.timeStamp = timeStamp ?? 0; // 确保默认值为0
}
// 转为 Map
Map<String, dynamic> toJson() {
return {
AMPSLocationKey.latitude: latitude,
AMPSLocationKey.longitude: longitude,
AMPSLocationKey.timeStamp: timeStamp,
AMPSLocationKey.coordinate: coordinate?.value
};
}
}
// 假设的工具类
class StrUtil {
static bool isEmpty(String? str) => str == null || str.isEmpty;
static String replace(String str, String pattern, String replacement) {
return str.replaceAll(RegExp(pattern), replacement);
}
}
/// 用户控制类. 重写相关方法设置SDK可用内容
class AMPSCustomController {
/// 是否可以使用PhoneState权限
bool isCanUsePhoneState;
/// 透传OAID
String OAID;
/// 是否允许使用个性化推荐
/// true: 允许 false: 不允许
bool isSupportPersonalized;
/// 适龄标记
/// 取值参考 [UnderageTag]
UnderageTag getUnderageTag;
/// userAgent
String? userAgent;
/// 是否可以使用传感器
bool isCanUseSensor;
/// 是否允许SDK自身获取定位
bool isLocationEnabled;
/// 用于记录，三方设置的位置信息
AMPSLocation? location;
AMPSCustomController({
required AMPSCustomControllerParam? param,
}) : isCanUsePhoneState = param?.isCanUsePhoneState ?? false,
OAID = param?.OAID ?? "",
isSupportPersonalized = param?.isSupportPersonalized ?? true,
getUnderageTag = param?.getUnderageTag ?? UnderageTag.unknown,
userAgent = param?.userAgent,
isCanUseSensor = param?.isCanUseSensor ?? true,
isLocationEnabled = param?.isLocationEnabled ?? true,
location = param?.location;
// 转为 Map
Map<String, dynamic> toJson() {
return {
AMPSControllerKey.isCanUsePhoneState: isCanUsePhoneState,
AMPSControllerKey.oaid: OAID,
AMPSControllerKey.isSupportPersonalized: isSupportPersonalized,
AMPSControllerKey.getUnderageTag: getUnderageTag.value, // 枚举用名称传递
AMPSControllerKey.userAgent: userAgent,
AMPSControllerKey.isCanUseSensor: isCanUseSensor,
AMPSControllerKey.isLocationEnabled: isLocationEnabled,
AMPSControllerKey.location: location?.toJson(), // 嵌套对象序列化
};
}
}
/// AMPSCustomController 的参数类
class AMPSCustomControllerParam {
/// 是否可以使用PhoneState权限
final bool? isCanUsePhoneState;
/// 透传OAID
final String? OAID;
/// 是否允许使用个性化推荐
final bool? isSupportPersonalized;
/// 适龄标记
final UnderageTag? getUnderageTag;
/// userAgent
final String? userAgent;
/// 是否可以使用传感器
final bool? isCanUseSensor;
/// 是否允许SDK自身获取定位
final bool? isLocationEnabled;
/// 三方设置的位置信息
final AMPSLocation? location;
AMPSCustomControllerParam({
this.isCanUsePhoneState,
this.OAID,
this.isSupportPersonalized,
this.getUnderageTag,
this.userAgent,
this.isCanUseSensor,
this.isLocationEnabled,
this.location,
});
}
// AMPSInitConfig类，用于表示初始化配置
class AMPSInitConfig {
// 媒体的账户ID
String appId;
// 日志模式
final bool _isDebugSetting;
final bool _isUseHttps;
// 是否测试广告位(是否计价)
final bool isTestAd;
// 添加支持的现金类型
final String currency;
// 国家
final int countryCN;
final String appName;
final UiModel uiModel;
final bool adapterStatusBarHeight;
final String userId;
final String? province;
final String? city;
final String? region;
// 聚合模式下，提前初始化的第三方广告渠道平台
final List<String>? adapterNames;
// 聚合模式下，传递第三方广告渠道平台初始化参数
final Map<String, Map<String, dynamic>> extensionParam;
final Map<String, dynamic> optionFields;
final AMPSCustomController adController;
final bool isMediation;
static bool isMediationStatic = false;
void a7bc8pp9i7d(String a5) {
appId = a5;
}
// 构造函数，接收Builder对象并进行初始化
AMPSInitConfig(AMPSBuilder builder)
: appId = builder.appId,
appName = builder.appName,
_isDebugSetting = builder.isDebugSetting,
_isUseHttps = builder.isUseHttps,
userId = builder.userId,
optionFields = builder.optionFields,
currency = builder.currency,
countryCN = builder.countryCN,
isTestAd = builder.isTestAd,
adController = builder.adController,
uiModel = builder.uiModel,
adapterStatusBarHeight = builder.adapter,
province = builder.province,
city = builder.city,
region = builder.region,
adapterNames = builder.adapterNames,
extensionParam = builder.extensionParam,
isMediation = builder.isMediation;
// 转为 Map（用于JSON序列化）
Map<String, dynamic> toMap(bool testModel) {
return {
// 基础类型直接传递
AMPSInitConfigKey.testModel: testModel,
AMPSInitConfigKey.appId: appId,
AMPSInitConfigKey.isDebugSetting: _isDebugSetting,
AMPSInitConfigKey.isUseHttps: _isUseHttps,
AMPSInitConfigKey.isTestAd: isTestAd,
AMPSInitConfigKey.currency: currency,
AMPSInitConfigKey.countryCN: countryCN,
AMPSInitConfigKey.appName: appName,
AMPSInitConfigKey.userId: userId,
AMPSInitConfigKey.province: province,
AMPSInitConfigKey.adapterStatusBarHeight: adapterStatusBarHeight,
AMPSInitConfigKey.city: city,
AMPSInitConfigKey.region: region,
AMPSInitConfigKey.isMediation: isMediation,
// 枚举类型：用名称或值传递
AMPSInitConfigKey.uiModel: uiModel.name, // 假设 UiModel 是枚举
// 列表类型
AMPSInitConfigKey.adapterNames: adapterNames,
// Map 转为 Map（Flutter 中 Map 可直接序列化）
AMPSInitConfigKey.extensionParam: extensionParam,
AMPSInitConfigKey.optionFields: optionFields,
// 嵌套对象：通过 toJson 转换
AMPSInitConfigKey.adController: adController.toJson(),
};
}
// 获取uiModel的方法
UiModel getUiModel() {
return uiModel;
}
// 获取appId的方法
String getAppId() {
return appId;
}
// 获取设置的省份
String? getProvince() {
return province;
}
// 获取设置的城市
String? getCity() {
return city;
}
// 获取设置的地区
String? getRegion() {
return region;
}
// 获取设置的第三方平台参数
Map<String, Map<String, dynamic>> getExtensionParams() {
return extensionParam;
}
List<String>? getAdapterNames() {
return adapterNames;
}
// 获取设置的某个第三方平台参数
Map<String, dynamic> getExtensionParamItems(String key) {
if (extensionParam.containsKey(key)) {
return extensionParam[key] ?? <String,dynamic>{};
}
return <String,dynamic>{};
}
// 获取appName的方法
String getAppName() {
return appName;
}
// 获取isDebugSetting的方法
bool isDebugSetting() {
return _isDebugSetting;
}
// 获取isUseHttps的方法
bool isUseHttps() {
return _isUseHttps;
}
// 获取userId的方法
String getUserId() {
return userId;
}
// 获取用户设置的userAgent
String? getUserAgent() {
return adController.userAgent;
}
// 禁用奔溃日志收集，默认否【默认收集日志】
bool disableCrashCollect() {
if (optionFields.containsKey(OptionFieldKey.crashCollectSwitch)) {
final disableCrashCollect =
optionFields[OptionFieldKey.crashCollectSwitch];
if (disableCrashCollect is bool) {
return disableCrashCollect;
}
}
return false;
}
String getLightColor() {
if (optionFields.containsKey(OptionFieldKey.colorLight)) {
final lightColor = optionFields[OptionFieldKey.colorLight];
if (lightColor is String) {
return lightColor;
}
}
return "";
}
String getDarkColor() {
if (optionFields.containsKey(OptionFieldKey.colorDark)) {
final darkColor = optionFields[OptionFieldKey.colorDark];
if (darkColor is String) {
return darkColor;
}
}
return "";
}
//用于提供获取用户是否统一SDK自身定位。
bool isLocationEnabled() {
return adController.isLocationEnabled;
}
//用于提供获取用户是否统一SDK自身定位。
AMPSLocation? getUserLocation() {
return adController.location;
}
// 获取optionFields的方法
Map<String, dynamic> getOptionFields() {
return optionFields;
}
// 获取currency的方法
String getCurrency() {
return currency;
}
// 获取countryCN的方法
int getCountryCN() {
return countryCN;
}
// 获取isTestAd的方法
bool getIsTestAd() {
return isTestAd;
}
// 获取自定义OAID的方法
String getCustomOAID() {
return adController.OAID;
}
// 获取是否可以使用电话状态的方法
bool isCanUsePhoneState() {
return adController.isCanUsePhoneState;
}
// 获取是否可以使用传感器
bool isCanUseSensor() {
return adController.isCanUseSensor;
}
}
class AMPSBuilder {
String appId;
String appName = "";
bool isDebugSetting = true;
bool isUseHttps = false;
String userId = "";
Map<String, dynamic> optionFields = {};
String currency = "";
int countryCN = CountryType.COUNTRY_TYPE_CHINA_MAINLAND;
bool isTestAd = false;
bool adapter = true;
UiModel uiModel = UiModel.uiModelAuto;
AMPSCustomController adController = AMPSCustomController(param: null);
String? province;
String? city;
String? region;
List<String>? adapterNames = [];
late Map<String, Map<String, dynamic>> extensionParam;
bool isMediation = false;
// 构造函数，接收appId和context并进行初始化
AMPSBuilder(this.appId) {
extensionParam = <String, Map<String, dynamic>>{};
}
// 设置是否启用聚合功能
AMPSBuilder setIsMediation(bool isMediation) {
this.isMediation = isMediation;
return this;
}
// 设置省份
AMPSBuilder setProvince(String pro) {
province = pro;
return this;
}
// 设置城市
AMPSBuilder setCity(String city) {
this.city = city;
return this;
}
// 设置地区
AMPSBuilder setRegion(String region) {
this.region = region;
return this;
}
// 设置初始化第三方广告平台
AMPSBuilder setAdapterNames(List<String> adapters) {
adapterNames = adapters;
return this;
}
/*
* 设置某个渠道平台特有配置参数
* key：渠道参数key，在AMPSConstants.ExtensionParamKey选择
* param：具体参数集合
*/
AMPSBuilder setExtensionParamItems(String key, Map<String, dynamic> param) {
extensionParam[key] = param;
return this;
}
// 设置广告控制器
AMPSBuilder setAdCustomController(AMPSCustomController controller) {
adController = controller;
return this;
}
// 设置appName
AMPSBuilder setAppName(String appName) {
this.appName = appName;
return this;
}
// 设置调试模式
AMPSBuilder setDebugSetting(bool debugSetting) {
isDebugSetting = debugSetting;
return this;
}
// 设置是否使用HTTPS
AMPSBuilder setUseHttps(bool isUseHttps) {
this.isUseHttps = isUseHttps;
return this;
}
// 设置用户ID
AMPSBuilder setUserId(String userId) {
this.userId = userId;
return this;
}
// 设置选项字段
AMPSBuilder setOptionFields(Map<String, dynamic> optionFields) {
this.optionFields = optionFields;
return this;
}
// 设置货币类型
AMPSBuilder setCurrency(String currency) {
this.currency = currency;
return this;
}
// 设置国家代码
AMPSBuilder setCountryCN(int countryCN) {
this.countryCN = countryCN;
return this;
}
// 设置UI模型
AMPSBuilder setUiModel(UiModel uiModel) {
this.uiModel = uiModel;
return this;
}
// 设置是否为测试广告
AMPSBuilder setIsTestAd(bool isTestAd) {
this.isTestAd = isTestAd;
return this;
}
// 设置落地页是否适配状态栏高度
AMPSBuilder setLandStatusBarHeight([bool adapter = true]) {
this.adapter = adapter;
return this;
}
// 构建AMPSInitConfig对象的方法
AMPSInitConfig build() {
return AMPSInitConfig(this);
}
}
记得导出flutter相关的文件到amps_sdk_export.dart，方便外部调用。我们可以在example中main中尝试调用初始化SDK。
import 'dart:collection';
import 'package:ads_sdk/amps_ad_sdk.dart';
import 'package:flutter/material.dart';
import 'package:ads_sdk/amps_sdk_export.dart';
import 'widgets/blurred_background.dart';
import 'widgets/button_widget.dart';
enum InitStatus {
normal,
initialing,
alreadyInit,
success,
failed
}
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
initialRoute: 'SplashPage',
routes: {
'SplashPage':(context)=>const SplashPage(title: '开屏页面')
},
);
}
}
class SplashPage extends StatefulWidget {
const SplashPage({super.key, required this.title});
final String title;
@override
State<SplashPage> createState() => _SplashPageState();
}
class _SplashPageState extends State<SplashPage> {
late AMPSIInitCallBack _callBack;
InitStatus initStatus = InitStatus.normal;
late AMPSInitConfig sdkConfig;
@override
void initState() {
//SystemChrome.setEnabledSystemUIMode(SystemUiMode.manual, overlays: []);
super.initState();
_callBack = AMPSIInitCallBack(
initSuccess: () {
debugPrint("adk is initSuccess");
setState(() {
initStatus = InitStatus.success;
});
},
initializing: () {
debugPrint("adk is initializing");
},
alreadyInit: () {
debugPrint("adk is alreadyInit");
setState(() {
initStatus = InitStatus.alreadyInit;
});
},
initFailed: (code, msg) {
initStatus = InitStatus.failed;
debugPrint("adk is initFailed");
debugPrint("result callBack=code$code;message=$msg");
});
HashMap<String, dynamic> optionFields = HashMap();
optionFields["crashCollectSwitch"] = true;
optionFields["lightColor"] = "#FFFF0000";
optionFields["darkColor"] = "#0000FF00";
HashMap<String, dynamic> ksSdkEx = HashMap();
ksSdkEx["crashLog"] = true;
ksSdkEx["ks_sdk_roller"] = "roller_click";
ksSdkEx["ks_sdk_location"] = "baidu";
sdkConfig = AMPSBuilder("33545")
.setCity("北京")
.setRegion("朝阳区双井")
.setCurrency(CurrencyType.CURRENCY_TYPE_USD)
.setCountryCN(CountryType.COUNTRY_TYPE_CHINA_MAINLAND)
.setDebugSetting(true)
.setIsMediation(false)
.setIsTestAd(false)
.setLandStatusBarHeight(true)
.setOptionFields(optionFields)
.setProvince("北京市")
.setUiModel(UiModel.uiModelDark)
.setUseHttps(true)
.setUserId("12345656")
.setExtensionParamItems("KuaiShouSDK", ksSdkEx)
.setAppName("Flutter测试APP")
.setAdapterNames(["ampskuaishouAdapter", "ampsJdSplashAdapter"])
.setAdCustomController(AMPSCustomController(
param: AMPSCustomControllerParam(
isCanUsePhoneState: true,
isCanUseSensor: true,
isSupportPersonalized: true,
isLocationEnabled: true,
getUnderageTag: UnderageTag.underage,
userAgent:
"Mozilla/5.0 (Phone; OpenHarmony 5.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 ArkWeb/4.1.6.1 Mobile",
location: AMPSLocation(
latitude: 39.959836,
longitude: 116.31985,
timeStamp: 1113939393,
coordinate: CoordinateType.baidu)))) //个性化，传感器等外部设置
.setIsMediation(false)
.setUiModel(UiModel.uiModelAuto)
.build();
AMPSAdSdk.testModel = true;
}
@override
Widget build(BuildContext context) {
return Scaffold(body: Stack(
alignment: AlignmentDirectional.center,
children: [
const BlurredBackground(),
Column(children: [
const SizedBox(height: 100,width: 0),
ButtonWidget(
buttonText: getInitResult(initStatus),
backgroundColor: getInitColor(initStatus),
callBack: () {
AMPSAdSdk().init(sdkConfig, _callBack);
}
),
const SizedBox(height: 20,width: 0),
ButtonWidget(
buttonText: '开屏show案例页面',
callBack: () {
// 使用命名路由跳转
Navigator.pushNamed(context, 'SplashShowPage');
}
),
const SizedBox(height: 20,width: 0),
ButtonWidget(
buttonText: '开屏组件案例页面',
callBack: () {
// 使用命名路由跳转
Navigator.pushNamed(context, 'SplashWidgetPage');
}
)
],),
],
));
}
String getInitResult(InitStatus status) {
switch (status) {
case InitStatus.normal:
return '点击初始化SDK';
case InitStatus.initialing:
return '初始化中';
case InitStatus.alreadyInit:
return '已初始化';
case InitStatus.success:
return '初始化成功';
case InitStatus.failed:
return '初始化失败';
}
}
Color? getInitColor(InitStatus initStatus) {
switch (initStatus) {
case InitStatus.normal:
return Colors.blue;
case InitStatus.initialing:
return Colors.grey;
case InitStatus.alreadyInit:
return Colors.green;
case InitStatus.success:
return Colors.green;
case InitStatus.failed:
return Colors.red;
}
}
}
五、原生层 (Android) 的实现与桥接
以 Android 为例，我们需要修改 android/src/main/.../AdsSdkPlugin.kt 文件来接收 Dart 层的调用，并调用底层的 Android 原生广告 SDK。
这样我们可以在外部example/lib/main 里面进行调用SDK接口了。
1. 接收 Dart 调用
通过AndroidStudio打开项目/example/android依赖完成之后，ads_sdk module中找到 AdsSdkPlugin 类(不同名称插件项目不一样，我这里是AdsSdkPlugin)，这是接收 Dart 调用并进行处理的入口。代码如下，这里可以发现MethodChannel都在AdsSdkPlugin这个类里面，而外部模块调用很多【初始化、开屏、插屏、原生、自渲染】可能几十个上百个，我们是要所有的接收和处理都放到AdsSdkPlugin这一个类里面么？当然可以，但最好不要，代码要求的是分层，高内聚低耦合。所以接下来我们需要设计原生端代码结构。
package com.example.ads_sdk
import io.flutter.embedding.engine.plugins.FlutterPlugin
import io.flutter.plugin.common.MethodCall
import io.flutter.plugin.common.MethodChannel
import io.flutter.plugin.common.MethodChannel.MethodCallHandler
import io.flutter.plugin.common.MethodChannel.Result
/** AdsSdkPlugin */
class AdsSdkPlugin: FlutterPlugin, MethodCallHandler {
private lateinit var channel : MethodChannel
override fun onAttachedToEngine(flutterPluginBinding: FlutterPlugin.FlutterPluginBinding) {
channel = MethodChannel(flutterPluginBinding.binaryMessenger, "ads_sdk")
channel.setMethodCallHandler(this)
}
override fun onMethodCall(call: MethodCall, result: Result) {
//全部这里接收各个模块【初始化、开屏、插屏、原生、自渲染】的方法，耦合度过高。
case ....初始化：
初始化一堆操作
break;
case ...开屏load
break;
case ...开屏getEcpm
break;
case ...开屏notifyLoss
break;
....
....
}
override fun onDetachedFromEngine(binding: FlutterPlugin.FlutterPluginBinding) {
channel.setMethodCallHandler(null)
}
}
2. 代码架构设计
整个插件开发过程，我们使用一个MethodChannel进行Flutter和各端的通信和调用，而整个SDK功能划分为【初始化、开屏、插屏、原生、自渲染】五个模块，而每个模块可能有十多个方法都会调用，整个调用加起来可能几十个方法调用，每一个调用涉及到一个庞大的功能，可能导致此页面各个模块业务逻辑耦合在一起。最简单的我这里将这五个模块单独管理类进行管理，相互解耦。
可能有开发者使用五个Plugin [AdsSdkPlugin,AdsSplashPlugin,AdsNativePlugin....],每个Plugin对应一个MethodChannel进行模块划分，当然也可以，但是我发现插件项目自动生成的AdsSdkPlugin会被依赖到依赖了插件的项目中的GeneratedPluginRegistrant中，而这里统一默认注册了插件项目默认生成的AdsSdkPlugin。如果你创建了五个Plugin,每次项目依赖都会导致其他Pluging丢失，只有默认的AdsSdkPlugin存在。所以推荐使用默认生成的AdsSdkPlugin，而不是创建多个Plugin进行代码模块划分。
首先创建 AMPSEventManager 单例进行管理MethodChannel分发。在onMethodCall中根据Flutter端invoke的方法名称进行判断属于那个模块，再次分发到对应的管理对象中【AMPSSDKInitManager、AMPSSplashManager、AMPSInterstitialManager...】。
package com.example.amps_sdk.manager
class AMPSEventManager private constructor() : MethodCallHandler {
private var channel: MethodChannel? = null
private var mContext: WeakReference<Activity>? = null // 在 Android 中通常使用 Context
companion object {
private var sInstance: AMPSEventManager? = null
fun getInstance(): AMPSEventManager {
return sInstance ?: synchronized(this) {
sInstance ?: AMPSEventManager().also { sInstance = it }
}
}
}
fun setContext(context: Activity) {
this.mContext = WeakReference(context) // 存储 application context 避免内存泄漏
}
fun getContext(): Activity? {
return this.mContext?.get()
}
/**
* 初始化 MethodChannel 并设置回调处理器
* @param binaryMessenger Flutter引擎的BinaryMessenger
*/
fun init(binaryMessenger: BinaryMessenger) {
if (channel == null) {
channel = MethodChannel(binaryMessenger, "amps_sdk") // "amps_sdk" 是通道名称
channel?.setMethodCallHandler(this) // 将当前类设置为回调处理器
}
}
/**
* 处理来自 Flutter 的方法调用
*/
override fun onMethodCall(call: MethodCall, result: Result) {
when {
InitMethodNames.contains(call.method) -> {//InitMethodNames 初始化相关的所有方法名称
AMPSSDKInitManager.getInstance().handleMethodCall(call, result)
}
SplashMethodNames.contains(call.method) -> {
AMPSSplashManager.getInstance().handleMethodCall(call, result)
}
InterstitialMethodNames.contains(call.method) -> {
//AMPSInterstitialManager.getInstance().handleMethodCall(call, result)
}
NativeMethodNames.contains(call.method) -> {
//AMPSNativeManager.getInstance().handleMethodCall(call, result)
}
else -> {
result.notImplemented() // 如果方法名未被识别
}
}
}
/**
* 从原生端向 Flutter 发送消息
* @param method 方法名
* @param args 参数，可以是 null 或任何 Flutter 支持的类型
*/
fun sendMessageToFlutter(method: String, args: Any?) { // args 类型改为 Any? 更灵活
channel?.invokeMethod(method, args)
}
/**
* 释放资源，清除 MethodChannel 的回调处理器和 Context
*/
fun release() {
channel?.setMethodCallHandler(null)
channel = null // 可选，如果不再需要这个channel实例
mContext = null
}
}
3. 集成原生 SDK 依赖
要真正调用您的原生广告 SDK，需要在 Android 插件的配置文件中添加依赖。
打开 android/build.gradle (插件根目录下的 android 文件夹内)，在 dependencies 块中添加您的原生 SDK 依赖。
这种方式在开发过程中可用，但是广告SDK的具体字节码是不会打包到最终包体的，还需要三方在对应项目Android模块重新依赖广告SDK。比较麻烦，最好是将其发布到maven仓库，避免复杂的依赖，当然可以使用本地maven仓库形式进行依赖，三方只需要在对应部分增加maven依赖配置即可。
allprojects {
repositories {
google()
mavenCentral()
maven {
name = "myrepo"
url = uri("file://${rootProject.projectDir.parentFile.parentFile}/android/m2repository")
}
}
}
对于本地maven构建，查看项目中build.gradle.kts
group = "com.example.ads_sdk"
version = "1.0-SNAPSHOT"
// At the top of your build.gradle
String mavenLocalRepoPath = "${rootProject.projectDir.toURI()}/m2repository"
// Ensure the directory exists
new File(mavenLocalRepoPath).mkdirs()
buildscript {
ext.kotlin_version = "2.1.0"
repositories {
google()
mavenCentral()
maven {
url "file:///D:/pgram/ads_sdk/android/m2repository"
}
}
dependencies {
classpath("com.android.tools.build:gradle:8.10.1")
classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version")
}
}
allprojects {
repositories {
google()
mavenCentral()
maven {
name = "myrepo"
url = uri("file:///${mavenLocalRepoPath}")
}
}
}
apply plugin: "com.android.library"
apply plugin: "kotlin-android"
apply plugin: "maven-publish"
publishing {
publications {
// 第一个 AAR 的 Publication
libraryOne(MavenPublication) {
groupId = 'com.example'
artifactId = 'amps-sdk'
version = '1.0'
//示例：假设你的模块名为 'amps_sdk' (与项目名一致)
//并且你要发布 release AAR
// 这个路径是相对于当前 build.gradle 所在模块的
artifact "libs/beiziSDK_v5.3.0.3.aar"//在同一目录层级。所以可以写成libs/amps.aar
}
release(MavenPublication) {
groupId = 'com.example'
artifactId = 'common'
version = '1.0'
//示例：假设你的模块名为 'amps_sdk' (与项目名一致)
//并且你要发布 release AAR
// 这个路径是相对于当前 build.gradle 所在模块的
artifact "libs/common_5.1.1.1.aar"
}
}
repositories {
maven {
name = 'myrepo'
url = mavenLocalRepoPath
}
}
}
//通过调试tasks调试路径：不需要调试之后删除即可
tasks.register("anotherTask") {
doLast {
//def mavenLocalRepo = file("m2repository")
def a = uri("file://${rootProject.projectDir.parentFile.parentFile}/android/m2repository")
logger.lifecycle(">>>>> [EXECUTION] 路径0=${a}")
logger.lifecycle(">>>>> [EXECUTION] 路径1=${rootProject.projectDir.toURI()}") // 使用 lifecycle 确保默认可见
logger.lifecycle(">>>>> [EXECUTION] 路径1=${rootProject.projectDir.toURI()}") // 使用 lifecycle 确保默认可见
logger.lifecycle(">>>>> [EXECUTION] 路径2=${rootProject.projectDir.parentFile.parentFile}") // 使用 lifecycle 确保默认可见
}
}
android {
namespace = "com.example.amps_sdk"
compileSdk = 36
compileOptions {
sourceCompatibility = JavaVersion.VERSION_11
targetCompatibility = JavaVersion.VERSION_11
}
kotlinOptions {
jvmTarget = JavaVersion.VERSION_11.toString()
}
sourceSets {
main.java.srcDirs += "src/main/kotlin"
test.java.srcDirs += "src/test/kotlin"
}
defaultConfig {
minSdk = 24
}
dependencies {
//compileOnly fileTree(dir: 'libs', include: '*.aar')
// 依赖第一个 AAR (amps-sdk)
api ('com.example:amps-sdk:1.0')
// 依赖第二个 AAR (common)
api ('com.example:common:1.0')
implementation ('androidx.annotation:annotation:1.8.0')
implementation ('androidx.appcompat:appcompat:1.7.1')
implementation ('com.google.android.material:material:1.13.0')
testImplementation ('junit:junit:4.13.2')
androidTestImplementation ('androidx.test.ext:junit:1.3.0')
androidTestImplementation ('androidx.test.espresso:espresso-core:3.7.0')
testImplementation("org.jetbrains.kotlin:kotlin-test")
testImplementation("org.mockito:mockito-core:5.19.0")
}
testOptions {
unitTests.all {
useJUnitPlatform()
testLogging {
events "passed", "skipped", "failed", "standardOut", "standardError"
outputs.upToDateWhen {false}
showStandardStreams = true
}
}
}
}
六、事件回调处理 (EventChannel)
原生 SDK 通常会通过**回调（Callback）**来通知应用广告加载成功、展示或点击等事件。Flutter 使用 EventChannel 来处理这种原生到 Dart 的持续数据流。
1. Dart 层 (EventChannel)
在example/lib/main中调用AMPSAdSdk().init(),其本质是MethodChannel通过invoke调用原生端对于MethodChannel对应方法名称。
Future<void> init(AMPSInitConfig sdkConfig,AMPSIInitCallBack callBack) async {
_callBack = callBack;
// 使用时
await AdsSdk.channel.invokeMethod(
AMPSAdSdkMethodNames.init,
sdkConfig.toMap(AMPSAdSdk.testModel),
);
}
原生端Android监听位置匹配到AMPSAdSdkMethodNames.INIT，进行真正广告SDK调用。
class AMPSSDKInitManager private constructor() {
companion object {
@Volatile
private var instance: AMPSSDKInitManager? = null
fun getInstance(): AMPSSDKInitManager {
return instance ?: synchronized(this) {
instance ?: AMPSSDKInitManager().also { instance = it }
}
}
}
fun handleMethodCall(call: MethodCall, result: Result) {
val method: String = call.method
val flutterParams: Map<String, Any>? = call.arguments as? Map<String, Any>
when (method) {
AMPSAdSdkMethodNames.INIT -> {
val context = AMPSEventManager.getInstance().getContext()
if (context != null && flutterParams != null) {
val ampsConfig = AMPSInitConfigConverter().convert(flutterParams)
initAMPSSDK(ampsConfig, context)
result.success(true)
} else {
if (context == null) {
result.error("CONTEXT_UNAVAILABLE", "Android context is not available.", null)
} else {
result.error("INVALID_ARGUMENTS", "Initialization arguments are missing or invalid.", null)
}
}
}
else -> result.notImplemented()
}
}
fun initAMPSSDK(ampsInitConfig: AMPSInitConfig?, context: Context) {
val callback = object : IAMPSInitCallback {
override fun successCallback() {
sendMessage(AMPSInitChannelMethod.INIT_SUCCESS)
}
override fun failCallback(p0: AMPSError?) {
sendMessage(AMPSInitChannelMethod.INIT_FAILED, mapOf("code" to p0?.code, "message" to p0?.message))
}
}
if (ampsInitConfig != null) {
SDKLog.setLogLevel(SDKLog.LOG_LEVEL.LOG_LEVEL_ALL);
AMPSSDK.init(context, ampsInitConfig,callback)
}
}
fun sendMessage(method: String, args: Any? = null) {
AMPSEventManager.getInstance().sendMessageToFlutter(method, args)
}
}
原生端SDK收到初始化SDK结果之后，通过AMPSEventManager.getInstance().sendMessageToFlutter(method, args)也就是MethodChannel最终通知Flutter端结果。Flutter端收到结果，通过callBack回调给用户。
总结
文章基本对 Flutter 插件开发实战、桥接原生 SDK 讲解了一遍——从Platform Channel 通信原理的底层逻辑，到FVM 多版本管理的环境搭建，再到Dart 层统一接口设计,原生层解耦架构实现的全流程开发，最后覆盖双向事件流转的联调关键，完整覆盖了多平台（Android、iOS、HarmonyOS）广告 SDK 桥接的核心环节，原生回调转发,模块解耦等实战痛点提供了具体方案（如构造者模式封装参数、AMPSEventManager 统一分发事件），可直接作为插件开发的落地参考。 当然，实际开发中可能还会遇到更多细节问题：比如 iOS 端的 Pod 依赖配置、HarmonyOS 端的 HAP 包构建适配、原生 SDK 异步回调的线程安全处理，或是插件发布到 Pub 仓库的规范配置等。如果大家在实操中遇到这类疑问，或是对现有流程有优化建议，都可以在评论区讨论交流。后续也会针对这些延伸场景补充更细致的教程，比如多 Channel 通信优化、插件版本迭代的兼容性处理等内容，帮助大家更顺畅地完成 Flutter 与原生能力的桥接工作。
登录
