Skip to main content

ubidding_flutter 4.2.0 copy "ubidding_flutter: ^4.2.0" to clipboard
ubidding_flutter: ^4.2.0 copied to clipboard

retracted

Flutter bridge plugin for UBiddingAdSDK supporting splash, interstitial, rewarded video, banner and native ads on Android and iOS.

ubidding_flutter #

UBiddingAdSDK 的 Flutter 桥接插件。下文是 Android / iOS 接入指南。

简介 #

UBidding Flutter 适配器为 Android 和 iOS 提供统一 Dart 接口,支持开屏、插屏、激励视频、Banner 与原生信息流五种广告形态。信息流包含模板和自渲染两种场景。

项目 本文基线
指南版本 1.0(文档版本,不代表插件版本)
修订日期 2026-11-17
Flutter 适配器 ubidding_flutter 4.2.0
Android UBidding SDK 4.1.2.11
iOS UBidding SDK 4.1.2.13

插件包只含桥接代码。原生 SDK 制品、广告账号和广告位由接入方准备;示例中的占位 ID 应替换为相应平台的配置。各广告源的加载、点击、关闭和真机投放由接入方在目标设备上验收。

安装 #

前提条件 #

环境 要求 / 当前项目基线
Flutter ≥ 3.38.8
Dart ≥ 3.10.7 且 < 4.0.0
Android 最低版本 API 24(Android 7.0)
Android 编译配置 compileSdk 36、JDK 17;项目基线 AGP 8.11.1 / Gradle 8.14
iOS 最低版本 iOS 13.0
iOS 工具链 Xcode、CocoaPods;本项目验证环境 Xcode 26.1 / CocoaPods 1.16.2
业务配置 分平台 App ID,五种形态的 Slot ID;模板与自渲染使用对应广告位

在宿主 pubspec.yaml 中加入:

dependencies:
  flutter:
    sdk: flutter
  ubidding_flutter: 4.2.0
flutter pub get

统一导入:

import 'package:ubidding_flutter/ubidding_flutter.dart';

Android 配置 #

UBidding SDK 与广告源 SDK

插件仅以 compileOnly 引用核心 SDK,宿主负责运行时打包。三方广告 AAR 与 Adapter 放在宿主工程,不放进 Flutter 插件目录。本仓库示例放在 example/android/libs。核心 AAR、所选广告源 SDK 与其 UBidding Adapter 必须匹配,避免重复引入同一 SDK。

  1. 将核心 AAR UBidding.SDK_4.1.2.11.aar 放入宿主管理的目录,例如 android/ubidding-sdk/。三方广告 AAR 与 Adapter 另放在宿主 android/libs/,不要放进 Flutter 插件目录。
  2. 在宿主 android/gradle.properties 中配置核心目录(相对路径基于宿主 Android 根目录):
android.useAndroidX=true
android.enableJetifier=true
UBIDDING_ANDROID_SDK_DIR=ubidding-sdk

Gradle 属性优先于同名环境变量。命令行可用 -PUBIDDING_ANDROID_SDK_DIR=... 覆盖;Android Studio Run 推荐使用上述属性,避免依赖 IDE 未继承的终端环境。

核心 AAR 锁定 SHA-256:

6ed75c5a1fd28237f61a56b2a8216164cca6ac50e6517ed20565b3ff42af2451
shasum -a 256 android/ubidding-sdk/UBidding.SDK_4.1.2.11.aar

目录、文件或校验值错误会在构建阶段给出 sdk_directory_missing、sdk_directory_invalid、sdk_missing 或 sdk_checksum_mismatch 诊断。使用对应交付包解决,不修改校验规则或 pub 缓存。

Android 项目配置

以下为 Groovy android/app/build.gradle 配置片段,合并到宿主现有配置中;保留 Flutter 插件配置与宿主自己的包名、签名。

android {
    compileSdk 36
    defaultConfig {
        minSdk 24
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
}

def configuredSdkDir = project.findProperty('UBIDDING_ANDROID_SDK_DIR') ?:
        System.getenv('UBIDDING_ANDROID_SDK_DIR')
if (!configuredSdkDir) {
    throw new GradleException('Set UBIDDING_ANDROID_SDK_DIR')
}
def ubiddingSdkDir = rootProject.file(configuredSdkDir)

def adnDirectory = rootProject.file('libs')

dependencies {
    implementation files(new File(ubiddingSdkDir, 'UBidding.SDK_4.1.2.11.aar'))
    // 三方广告 AAR 与 Adapter 放在宿主 android/libs,不包含核心 AAR。
    implementation fileTree(dir: adnDirectory, include: ['**/*.aar'])
}

本地 AAR 不自动携带 Maven 传递依赖。当前示例 App 的广告源组合补充如下依赖;这是示例组合,不是每个宿主都必需的最小集合。按所选广告源交付说明核对:

dependencies {
    implementation 'com.google.code.gson:gson:2.8.6'
    implementation 'com.github.bumptech.glide:glide:4.16.0'
    implementation 'androidx.recyclerview:recyclerview:1.1.0'
    implementation 'androidx.cardview:cardview:1.0.0'
    implementation 'com.squareup.okhttp3:okhttp:4.9.3'
    implementation 'com.github.zjupure:webpdecoder:2.6.4.16.0'
    implementation 'androidx.room:room-runtime:2.2.6'
    implementation 'androidx.appcompat:appcompat:1.2.0'
    implementation 'com.google.android.material:material:1.2.1'
    implementation 'androidx.percentlayout:percentlayout:1.0.0'
    implementation 'androidx.constraintlayout:constraintlayout:2.0.4'
    implementation 'androidx.localbroadcastmanager:localbroadcastmanager:1.0.0'
}

AndroidManifest 与资源配置

在宿主 android/app/src/main/AndroidManifest.xml 声明联网权限,并检查 Release 的合并清单:

<uses-permission android:name="android.permission.INTERNET" />
  • 所选广告源的 Activity、Provider、下载路径 XML 及资源按该版本 SDK 交付说明配置;先检查 AAR 已合并的内容,再补齐缺项。
  • Provider authority 使用宿主 ${applicationId},避免固定为示例包名。
  • 位置、设备状态及存储等可选权限仅按实际业务添加;隐私开关和系统运行时授权分别处理。
  • 保留 Flutter embedding v2 与宿主 MainActivity 注册;全屏展示依赖有效、前台可用的 Activity。

混淆、资源与架构

Release 开启 R8 / 资源裁剪时,合入 UBidding 及所选广告源交付包的混淆规则、资源保留文件,验证 Release 实际展示。NOW 的旧版 keep 规则不直接视为本版本 UBidding 配置。

ABI 选择应与全部交付 AAR 的 JNI 架构一致,通常先验证 arm64-v8a 真机;宿主有 32 位需求时另外核对 armeabi-v7a。Debug 成功不替代 R8、资源裁剪和 Release 验证。

iOS 配置 #

UBidding SDK 与广告源依赖

当前 Core 依赖在 plugin Podspec,Adapter 精确声明在 example/ios/Podfile;以下为示例宿主组合,SDK 二进制不随 Flutter 源码包附带:

依赖名称 当前示例版本 用途
UBiddingAdSDK 4.1.2.13 核心 SDK
UBiddingGdtAdapter 4.16.11.1 优量汇适配器
UBiddingKSAdapter 5.9.10.1.1 快手适配器
UBiddingBaiduAdapter 10.060.2 百度适配器
UBiddingGromoreAdapter 7.8.0.7.1 GroMore 适配器
UBiddingQuMengAdapter 1.9.4.0.1 趣盟适配器
UBiddingFancyAdapter 3.0.23.1 Fancy 适配器
UBiddingWangMaiAdapter 8.0.0.1.0 旺脉适配器
UBiddingJTAdapter 4.5.5.1.2 JT 适配器
UBiddingUBiXAdapter 2.12.1.1 UBiX 适配器
UBiddingAdProfAdapter 2.1.8.2.2 AdProf 适配器

以上版本与 example/ios/Podfile 一致。宿主按投放选择引入,并检查传递依赖。

仓库示例 Podfile.lock 已按当前 Podspec 重新解析;历史真机结果不代表本次新版本组合的投放验收。

iOS 项目配置

插件最低 iOS 13.0。本仓库示例把工程部署目标设为 15.0。插件 podspec 已精确依赖已发布的 UBiddingAdSDK 4.1.2.13,宿主 Podfile 按投放声明 Adapter,不必再写一条本地 Core。

宿主 ios/Podfile 保留 Flutter 模板的 podhelper、flutter_install_all_ios_pods 与 post_install。在现有 target 'Runner' do 内按需加入与示例相同的精确版本:

platform :ios, '13.0'
source 'https://cdn.cocoapods.org/'

target 'Runner' do
  pod 'UBiddingGdtAdapter', '4.16.11.1'
  pod 'UBiddingKSAdapter', '5.9.10.1.1'
  pod 'UBiddingBaiduAdapter', '10.060.2'
  pod 'UBiddingGromoreAdapter', '7.8.0.7.1'
  pod 'UBiddingQuMengAdapter', '1.9.4.0.1'
  pod 'UBiddingFancyAdapter', '3.0.23.1'
  pod 'UBiddingWangMaiAdapter', '8.0.0.1.0'
  pod 'UBiddingJTAdapter', '4.5.5.1.2'
  pod 'UBiddingUBiXAdapter', '2.12.1.1'
  pod 'UBiddingAdProfAdapter', '2.1.8.2.2'
  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

当前 Core 链接需要显式 UBiddingUBiXAdapter。未投放的广告源可以不声明。不要排除模拟器 arm64;当前 SDK 与 Adapter 含 arm64 模拟器切片。

使用本地 Core 时,目录内只能有一个 UBiddingAdSDK.podspec 或 .podspec.json,名称必须是 UBiddingAdSDK,版本必须是 4.1.2.13。本仓库示例通过 ios/sdk_config.rb 读取 UBIDDING_IOS_SDK_PATH;普通宿主可直接写 pod 'UBiddingAdSDK', :path => '目录'。私有 spec 仓库用 UBIDDING_POD_SOURCE,且仍保留 https://cdn.cocoapods.org/。

flutter pub get
cd ios
pod install

使用 Xcode 打开 Runner.xcworkspace,配置宿主 Bundle ID、开发团队及签名。

Info.plist 与系统权限

按实际业务配置跟踪、位置说明。下面仅为启用相应能力时的片段,不表示默认采集:

<key>NSUserTrackingUsageDescription</key>
<string>经您的同意,使用设备标识提供广告服务</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>经您的同意,使用位置信息提供广告服务</string>

ATT 与位置授权由宿主业务发起,初始化接口不代替系统授权。按所选广告源配置 SKAdNetwork ID 与必要网络规则;优先限定实际需要的域名,不默认全局关闭 ATS。

初始化 #

推荐流程:宿主隐私同意 → 启动初始化页 → 初始化成功 → 广告首页 → 广告页手动加载。初始化失败保留启动页,显示错误并允许重试;广告页不重复初始化、不修改 App ID。

import 'package:ubidding_flutter/ubidding_flutter.dart';

Future<void> initializeUBidding() async {
  // 由宿主在隐私同意流程完成后调用。
  final result = await UBidding.initialize(
    const UBiddingConfig(
      appId: 'YOUR_PLATFORM_APP_ID',
      debugLogEnabled: false,
      sensorEnabled: false,
      privacy: UBiddingPrivacyConfig(),
      user: UBiddingUserInfo(channel: 'YOUR_CHANNEL'),
    ),
  );
  if (!result.success) {
    throw StateError(result.message ?? 'SDK 初始化失败');
  }
  // 业务在此开放广告入口;页面退出不重置整个 SDK。
}
接口 说明
UBidding.initialize(config) 返回 Future<UBiddingInitializeResult>,确认成功后开放入口
UBidding.isInitialized Future<bool>,查询原生初始化状态
UBidding.sdkVersion Future<String>,查询当前平台实际 SDK 版本
UBidding.pluginVersion 当前 Flutter 适配器版本字符串

等价配置的进行中/成功初始化共享结果;初始化失败或 success: false 后,同一配置可以再试。另一份配置抛出 restart_required,两端 SDK 都只让首次生效的初始化配置起作用,更换配置需要重启进程。空 appId 在 Flutter 层返回 invalid_argument,不进入原生。运行期隐私变更使用 updatePrivacyConfig:Android 只更新显式传入的项,iOS 返回 not_supported。

初始化配置 #

参数 类型 默认值 / 说明
appId String 必填,使用当前平台对应 App ID
debugLogEnabled bool false;联调按需开启,正式环境关闭
sensorEnabled bool? null 沿用原生;false/true 显式设置
privacy UBiddingPrivacyConfig 所有可选布尔开关默认 null,缺省沿用原生
user UBiddingUserInfo? 可选用户配置
extra Map<String, String> 空 Map;原生扩展字段

隐私配置 #

表中“—”表示当前桥接没有对应平台映射;传入跨平台对象不表示该平台会采集对应信息。

参数 类型 说明 Android iOS
canUseLocation bool? 位置访问开关 ✓ ✓
canReadInstalledPackages / appList bool? / List 应用列表访问/宿主提供列表 ✓ —
canUsePhoneState / imei bool? / String? 手机状态访问/宿主提供 IMEI ✓ —
canUseWifiState bool? Wi-Fi 状态访问 ✓ —
canWriteExternalStorage bool? 外部存储写入 ✓ —
canUseOaid / oaid bool? / String? OAID 访问/宿主提供值 ✓ —
canUseAndroidId / androidId bool? / String? Android ID 访问/宿主提供值 ✓ —
canUseMacAddress / macAddress bool? / String? MAC 地址访问/宿主提供值 ✓ —
canReadIdfa / idfa bool? / String? IDFA 访问/宿主提供值 — ✓
canReadNetworkType bool? 网络类型访问 — ✓
personalizedAds bool? 个性化广告;iOS 映射为反向限制开关 ✓ ✓
programmaticRecommendation bool? 程序化推荐 ✓ —

提供自定义标识不等于开启采集权限。SDK 开关、宿主隐私同意与系统权限分别核对;只传入已获同意、确有业务需要的数据。当前没有 NOW 的 customLocation 字段。

用户信息配置 #

参数 类型 说明 Android iOS
userId String? 用户标识 ✓ ✓
channel String? 渠道 ✓ ✓
subChannel String? 子渠道 ✓ ✓
subscriber bool? 订阅状态,null 为未指定 ✓ ✓
segmentId String? 分组标识 ✓ ✓
custom Map<String, String> 自定义用户信息 ✓ —

可选字符串提供时应非空;当前 API 没有 NOW 的年龄、性别枚举。日志与验证材料中对用户标识脱敏。

广告类型 #

广告类型 Dart 对象 展示方式 Android iOS
开屏 UBiddingSplashAd 全屏 show() ✓ ✓
插屏 UBiddingInterstitialAd 全屏 show() ✓ ✓
激励视频 UBiddingRewardedAd 全屏 show() ✓ ✓
Banner UBiddingBannerAd 嵌入 buildView() ✓ ✓
信息流:模板/自渲染 UBiddingNativeAd 遍历 nativeAdDatas,逐条 data.buildView() ✓ ✓

此表为接口覆盖,不代表所有广告源组合均通过真机验收。

广告请求类 UBiddingAdRequest #

参数 类型 说明
slotId String 必填且非空,匹配平台与广告形态
width / height double? Banner/信息流必填,有限且大于 0,使用 Flutter 逻辑尺寸
fetchAdTimeOut int? Android 原生 SDK 超时原值;iOS 无对应公开入口,不是插件截止
interstitialCloseAfterClick bool? 默认 null;显式 false/true 透传
extra Map<String, Object?> 原生请求扩展,值需适配 StandardMessageCodec

嵌入尺寸范围 (0, 2147483647]。高度 0 不表示自动高度;父布局约束也不替代请求中的显式宽高。

广告对象通用接口 #

接口 说明
request / requestId / type 请求配置、自动生成的请求 ID、广告类型
events Stream<UBiddingAdEvent>;先订阅,再加载;支持多订阅
load() 加载命令受理;完成不代表广告加载成功
finalizeAd() 主动结束当前原生竞价,结果仍监听加载事件
showStatus iOS 原生展示状态整数;Android 返回 not_supported
isReady() 返回 Future<bool>,展示/挂载前再次查询
adInfo 返回 Future<UBiddingAdInfo?>,未就绪时信息可能为空
reportWin(info) / reportLoss(info) 竞价结果上报,见下文
dispose() 异步幂等释放句柄并关闭事件流
isDisposed 本地已释放状态

只有全屏对象具有 show();Banner 和 Native 单条条目具有 buildView()。Native 单条还支持 setVideoMute/startVideo/pauseVideo/resumeVideo/stopVideo。当前对象无公开 state 属性,业务依据事件维护自己的页面状态。

通用页面使用示例 #

下面展示一页拥有一个广告句柄的基本流程,可用于五种形态。页面进入不自动加载;全屏成功后手动展示,嵌入式成功后自动挂载。生产项目可将状态移入独立控制器,本仓库示例的 AdPageController 即为此结构。

import 'dart:async';
import 'package:flutter/material.dart';
import 'package:ubidding_flutter/ubidding_flutter.dart';

class AdDemoPage extends StatefulWidget {
  const AdDemoPage({super.key, required this.createAd});
  final UBiddingAd Function() createAd;

  @override
  State<AdDemoPage> createState() => _AdDemoPageState();
}

class _AdDemoPageState extends State<AdDemoPage> {
  UBiddingAd? _ad;
  StreamSubscription<UBiddingAdEvent>? _subscription;
  bool _closed = false, _loading = false, _ready = false;
  bool _attached = false, _presenting = false;
  int _generation = 0;
  String _status = 'idle';
  Future<void>? _closing;

  void _update(String status) {
    if (!_closed && mounted) setState(() => _status = status);
  }

  bool _active(UBiddingAd ad, int generation) =>
      !_closed && mounted && identical(_ad, ad) && generation == _generation;

  Future<void> _releaseCurrent() async {
    final ad = _ad;
    final subscription = _subscription;
    _ad = null;
    _subscription = null;
    try {
      await subscription?.cancel();
    } finally {
      await ad?.dispose();
    }
  }

  Future<void> _load() async {
    if (_closed || _loading || _ready || _presenting) return;
    final generation = ++_generation;
    _loading = true;
    _attached = false;
    _update('loading');
    try {
      // 先完成视图移除,再清理旧句柄;重试创建新请求 ID。
      await WidgetsBinding.instance.endOfFrame;
      await _releaseCurrent();
      if (_closed || !mounted || generation != _generation) return;
      final ad = widget.createAd();
      _ad = ad;
      _subscription = ad.events.listen((event) {
        if (!_active(ad, generation)) return;
        switch (event.type) {
          case 'loadSuccess':
            unawaited(_onLoaded(ad, generation));
            break;
          case 'loadFailure':
          case 'showFailure':
          case 'renderFailure':
          case 'dismiss':
            _loading = _ready = _presenting = _attached = false;
            _update('${event.type}: ${event.error?.code ?? ''} '
                '${event.error?.message ?? ''}');
            break;
          default:
            // 视频完成与奖励验证是不同事件,业务分别处理。
            debugPrint('${event.type} requestId=${event.requestId}');
        }
      });
      await ad.load(); // 仅命令受理,保持 loading 等待事件。
    } catch (error) {
      if (!_closed && mounted && generation == _generation) {
        _loading = false;
        _update('$error');
      }
    }
  }

  Future<void> _onLoaded(UBiddingAd ad, int generation) async {
    try {
      final ready = await ad.isReady();
      if (!_active(ad, generation)) return;
      _loading = false;
      _ready = ready;
      _attached = ready && ad is UBiddingEmbeddedAd;
      _update(ready ? 'ready' : 'not ready');
    } catch (error) {
      if (_active(ad, generation)) {
        _loading = false;
        _update('$error');
      }
    }
  }

  Future<void> _show() async {
    final ad = _ad;
    if (!_ready || _presenting || ad is! UBiddingFullScreenAd) return;
    final generation = _generation;
    _presenting = true;
    _update('checking ready');
    try {
      final ready = await ad.isReady();
      if (!_active(ad, generation)) return;
      if (!ready) throw StateError('广告尚未就绪');
      _ready = false;
      _update('showing');
      await ad.show(); // 展示结果仍以 show/showFailure/dismiss 事件为准。
    } catch (error) {
      if (_active(ad, generation)) {
        _presenting = false;
        _ready = false;
        _update('$error');
      }
    }
  }

  Future<void> _close() => _closing ??= _closeOnce();
  Future<void> _closeOnce() async {
    _closed = true;
    ++_generation; // 先使迟到事件及异步查询失效。
    if (mounted) setState(() => _attached = false);
    await WidgetsBinding.instance.endOfFrame;
    await _releaseCurrent();
  }

  Future<void> _leave() async {
    try {
      await _close();
    } catch (error) {
      debugPrint('Ad cleanup: $error');
    }
    if (mounted) Navigator.of(context).pop();
  }

  @override
  void dispose() {
    _closed = true;
    ++_generation;
    // 路由被外部移除时的兜底:先让当前帧卸载 PlatformView。
    unawaited((_closing ??= () async {
      await WidgetsBinding.instance.endOfFrame;
      await _releaseCurrent();
    }()).catchError((Object error) => debugPrint('Ad cleanup: $error')));
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    final ad = _ad;
    return PopScope(
      canPop: _closed,
      onPopInvokedWithResult: (didPop, result) {
        if (!didPop) unawaited(_leave());
      },
      child: Scaffold(
        appBar: AppBar(title: const Text('UBidding 广告')),
        body: ListView(children: [
          Text(_status),
          ElevatedButton(
            onPressed: !_closed && !_loading && !_ready && !_presenting
                ? _load : null,
            child: const Text('加载'),
          ),
          if (ad is UBiddingFullScreenAd)
            ElevatedButton(
              onPressed: _ready && !_presenting ? _show : null,
              child: const Text('展示'),
            ),
          if (_attached && ad is UBiddingEmbeddedAd)
            ad.buildView(key: ValueKey(ad.requestId)),
        ]),
      ),
    );
  }
}

示例仅在页面真正退出时清理;原生广告覆盖页面、系统弹窗或应用暂时失焦不等同于退出。外部路由管理器应在删除页面前调用等价的异步清理逻辑,dispose 作为兜底。

开屏广告 #

将通用页面的创建函数配置为:

AdDemoPage(
  createAd: () => UBiddingSplashAd(
    request: const UBiddingAdRequest(
      slotId: 'YOUR_SPLASH_SLOT_ID',
    ),
  ),
)

收到 loadSuccess 后开启展示;展示前再次查询 isReady()。开屏是独立全屏广告页示例,不自动插入 SDK 初始化流程;业务启动投放另行设计等待、失败与超时回退。

插屏广告 #

AdDemoPage(
  createAd: () => UBiddingInterstitialAd(
    request: const UBiddingAdRequest(
      slotId: 'YOUR_INTERSTITIAL_SLOT_ID',
      interstitialCloseAfterClick: false,
    ),
  ),
)

在适当业务间隙展示,避免同时触发多个全屏广告;iOS 展示需前台可用的窗口与 ViewController。关闭后再次加载使用新句柄。

激励视频广告 #

AdDemoPage(
  createAd: () => UBiddingRewardedAd(
    request: const UBiddingAdRequest(
      slotId: 'YOUR_REWARDED_SLOT_ID',
    ),
  ),
)

分别处理 videoStart、videoComplete、videoError、videoSkip 与 rewardVerify。videoComplete 不直接等于奖励有效;奖励回调的原始字段位于 event.extra,应结合广告源规则和业务服务端校验发奖,并对同一请求幂等奖励处理。

AdDemoPage(
  createAd: () => UBiddingBannerAd(
    request: const UBiddingAdRequest(
      slotId: 'YOUR_BANNER_SLOT_ID',
      width: 320,
      height: 50,
    ),
  ),
)

尺寸为示例值,以广告位和父容器可用尺寸为准;仅在加载成功且 ready 后插入 buildView()。嵌入对象不使用全屏 show()。

原生信息流广告 #

模板广告

AdDemoPage(
  createAd: () => UBiddingNativeAd(
    request: const UBiddingAdRequest(
      slotId: 'YOUR_TEMPLATE_FEED_SLOT_ID',
      width: 360,
      height: 250,
    ),
  ),
)

自渲染广告

AdDemoPage(
  createAd: () => UBiddingNativeAd(
    request: const UBiddingAdRequest(
      slotId: 'YOUR_SELF_RENDER_FEED_SLOT_ID',
      width: 360,
      height: 250,
    ),
  ),
)

两种形态使用同一 UBiddingNativeAd 接口,由广告位配置及返回 Offer 的原生类型区分,不是设置 Dart renderType。建议提供两个独立页面入口并使用不同 Slot ID。

  • 模板:SDK 提供模板视图,关注 renderSuccess、renderFailure 与 show。
  • 自渲染:加载后遍历 nativeAdDatas,每个 data.getMaterial 获取素材,再以 UBiddingNativeLayout 指定全部原生槽位,通过 data.buildView(nativeLayout: layout) 挂载。plugin 无默认卡片排版。
  • 新增坐标、字号、颜色及点击类型配置;开屏 bottom 使用宿主原生工厂。
  • 同一条 data 仅挂载到一个容器,不同条目可同时展示。普通 Widget rebuild 不应新建广告或重新 load()。
  • 从 Widget 树移除视图会解绑,句柄仍由页面持有;按 ready 状态可以重新挂载。最终退出时另行 dispose()。
  • Android 桥接内部使用 SDK 的 UMTFeedAdView 容器;宿主使用 buildView(),不自行用普通 FrameLayout 替代 SDK 注册容器。
  • 模板素材类型:Android 在 loadSuccess 后读取 data.expressMaterialType;自渲染和 iOS 为 null。类型只作样式参考,最终模板宽高以 SDK renderSize 为准。
  • 隐私图标:自渲染 nativeLayout 可声明独立 choiceView(x/y/width/height,clickType 为 none);Android 将几何交给 SDK,iOS 接受但不创建替代图标。位置应避开 CTA 等素材。
  • Android 自渲染的评分/下载次数读取 material.platformExtra['score']/['downloadCountText'],下载文本原样返回,不与 iOS 评论数混用。两端 CTA 按钮缺少有效文案时显示“查看详情”,素材 ctaText 保持原始值。
  • Android 下载 active/pause/failed/finish 及 installed 事件的 extra 带 fileName/appName,空串与 null 保留;字节数和逐条身份不变。
  • 主入口已停止导出六类无消费入口的 Android 常量。MuteType、VideoPlayNetType、RenderType、ReportMaterialType、CustomAdnType 不再从主入口导出;UBiddingAndroidDislikeEnforce 仍可用。

其他说明 #

广告事件 UBiddingAdEvent #

字段 类型 说明
requestId String Flutter 请求 ID,用于事件关联;默认自动生成
slotId String 当前广告位 ID
type String 事件名称
timestamp int 事件时间戳,毫秒
adDataId String? Native 单条独立身份,批次事件为空
platformRequestId String? 原生/广告源请求标识,可能为空
error UBiddingError? 结构化广告错误
extra Map<String, Object?> 平台原始扩展信息,按源核对
常用事件 含义
loadStart 加载开始,可由桥接合成
loadSuccess / loadFailure 加载成功/失败
show / showFailure 展示成功/失败
click / dismiss 点击/关闭
renderSuccess / renderFailure 模板渲染/嵌入挂载相关结果
videoReady / videoStart / videoComplete / videoError / videoSkip 原生视频相关状态
rewardVerify 奖励验证回调,与视频完成分离
detailOpened / detailClosed / willDismiss 原生详情与关闭相关事件
downloadIdle 等 Android 信息流广告源的下载扩展事件

不同形态、平台和广告源的事件集合存在差异,并非每条事件都在双端产生。保留未知事件日志,不假定事件固定总数。订阅是广播流,不回放订阅前的事件;始终在 load() 前建立监听。

错误信息 #

错误分三层处理:

来源 类型 处理方式
本地参数错误 ArgumentError 修正空 ID、嵌入尺寸或竞价参数
已释放句柄操作 UBiddingAdDisposedException 创建新句柄,不复用已释放对象
平台命令错误 PlatformException 记录 code/message/details,检查配置、状态与宿主
异步广告失败 event.error(UBiddingError) 按请求 ID 记录,更新失败状态并允许重试

UBiddingError 字段为 code、message、domain、details。details 类型为 Object?,按实际 Map 检查原生错误码,不固定强转所有错误。

常见稳定代码:invalid_argument、invalid_state、sdk_error、load_failed、show_failed、render_failed。原生错误码另存于 details,不将展示失败解释为无填充。

获取广告信息 #

import 'package:flutter/foundation.dart';
import 'package:ubidding_flutter/ubidding_flutter.dart';

Future<void> inspectAd(UBiddingAd ad) async {
  final ready = await ad.isReady();
  final info = await ad.adInfo;
  debugPrint('ready=$ready, ADN=${info?.adnName}, eCPM=${info?.ecpm}');
}
UBiddingAdInfo 字段 类型 说明
ecpm double? 原生返回的 eCPM;当前契约按分记录,具体价格含义按 SDK/ADN 核对
signedEcpm String? 原生签名价格,可能为空
adnName String? 广告源名称
adnSlotId String? 广告源广告位
extra Map<String, Object?> 扩展信息

空信息不补造价格。跨平台价格语义和服务端验收仍需使用真实 SDK 结果核对。

竞价结果上报 #

在收到加载成功且广告处于 ready 时上报真实竞价结果;建议在展示/挂载前完成。当前每轮加载只接受一次胜或负上报,二者互斥。文档示例函数接收真实计算结果,不使用诊断按钮发送虚构竞价。

Future<void> reportRealWin(UBiddingAd ad, int secondPriceCent) async {
  await ad.reportWin(UBiddingWinInfo(secondPriceCent: secondPriceCent));
}

Future<void> reportRealLoss(
  UBiddingAd ad, {
  required int reason,
  required int winnerPriceCent,
  required String winnerAdnId,
}) async {
  await ad.reportLoss(UBiddingLossInfo(
    reason: reason,
    winnerPriceCent: winnerPriceCent,
    winnerAdnId: winnerAdnId,
  ));
}
模型 参数说明
UBiddingWinInfo secondPriceCent 为可选整数分,缺省与零不同,数值语义交 SDK 判定;extra 为字符串 Map
UBiddingLossInfo reason 为 1~6;winnerPriceCent 可选非负整数;winnerAdnId、winnerAdSource、winnerAdTitle 可选,提供时非空;extra 为字符串 Map

reason 数值语义按交付 SDK 的定义核对,不猜测原因。iOS winnerAdnId 接受 UMTBidPlatform 数字字符串(0~12 或 16);Android 使用 SDK ADN ID 字符串,不直接跨平台复用名称。extra 不覆盖内建价格、原因与平台字段。命令受理不代表服务端报告验收完成。

查看版本 #

Future<Map<String, String>> readUBiddingVersions() async => {
  'flutterAdapter': UBidding.pluginVersion,
  'nativeSdk': await UBidding.sdkVersion,
};

nativeSdk 为当前设备平台实际值:Android 查询 Android SDK,iOS 查询 iOS SDK;它不在一台设备上同时读取两个平台版本。建议初始化后在首页显示平台标签、适配器版本与 SDK 版本,并显示查询失败而非硬编码成功值。

生命周期与资源释放 #

  1. 每页独立持有句柄、订阅和请求代次;禁止加载/展示按钮重复点击。
  2. load() 返回后继续等待当前请求 loadSuccess,展示/挂载前再次查询 ready。
  3. 失败重试先移除嵌入 Widget、取消旧订阅、释放旧句柄,再创建新句柄。
  4. 真正退出页面时先失效异步操作;嵌入视图先从 Widget 树移除并完成解绑,再取消订阅和释放。
  5. 全屏页取消订阅并释放,保留 dispose 兜底;临时失焦或广告覆盖不触发页面退出清理。
  6. dispose() 幂等,但清理错误仍应记录;页面已关闭后的迟到结果不更新 UI。

常见问题 #

1. 初始化失败或广告入口未开放 #

核对分平台 App ID、隐私同意时机、SDK 依赖与网络。打印 PlatformException 的 code/message/details;成功前保留初始化页,同配置失败后可重试。已成功初始化后使用不同配置会抛出 restart_required。

2. Android 编译通过但运行时报缺类 #

插件是 compileOnly,宿主应打包同一核心 AAR、所选 Adapter 与广告源运行依赖;检查是否遗漏 Maven 传递依赖及 Release 混淆规则。目录中的重复核心 SDK 也可能导致 duplicate class。

3. Android Studio Debug 停留黑屏 #

先区分启动器、安装、Dart 调试连接与 SDK 初始化。检查设备是否仍保留旧包、是否等待手机确认安装;安装返回 INSTALL_FAILED_ABORTED 时新包未部署。检查 Flutter VM service 与 logcat;项目曾遇到设备全局日志级别屏蔽调试发现的情况,应按设备诊断恢复日志配置。冷启动进入首屏与 SDK 初始化耗时分别记录。

4. iOS Pod 解析或链接失败 #

核对已发布 UBiddingAdSDK 4.1.2.13、Adapter 精确版本,以及新生成的 lock。使用 xcworkspace。模拟器使用 arm64,不再排除该架构。4.1.2.12 的验收不沿用为 4.1.2.13 已通过。

5. 加载成功但展示失败 #

loadSuccess 与实际 show 是不同阶段。展示前再查 ready,核对前台 Activity/ViewController、已使用状态、原生 showFailure/renderFailure 错误及 requestId;结束或失败后清理并创建新句柄。

6. 信息流空白、渲染失败或只有点击区域 #

核对广告位类型、显式正宽高与父布局;使用当前修复后的桥接。Android 注册容器应为 SDK UMTFeedAdView;iOS 自渲染需原生素材和媒体布局,注册点击区域本身不代表素材已渲染。分别记录加载、渲染、展示和视频回调,并保存画面证据。

7. 事件监听不工作或混入旧页面状态 #

在加载前订阅当前句柄 events,不要依赖回放。复用业务 Slot ID 不等于复用 requestId;显式 requestId 应在全部活动句柄中全局唯一。取消旧订阅、递增请求代次,检查释放后复入是否重新为 idle。

8. 页面退出后资源仍占用 #

移除 Widget 只解绑,不等于最终释放广告。页面所有者需取消订阅并 await dispose;dispose 兜底中的异步错误要记录。100 次循环和原生资源基线属于额外验收,不以单次退出无崩溃替代。

接入检查清单 #

  • ❌ 工具链满足约束,SDK 制品版本/校验一致;Android 宿主运行依赖齐备,iOS lock 与当前 Podspec 一致。
  • ❌ 宿主完成隐私同意,默认关闭可选访问,系统权限由宿主控制。
  • ❌ 初始化失败禁止进入广告首页;成功后显示适配器和实际平台 SDK 版本。
  • ❌ 五种形态分别验证加载、ready、展示/挂载、事件关联、失败重试和退出清理。
  • ❌ 模板与自渲染分别使用正确广告位,并检查素材及媒体画面。
  • ❌ 双端 Debug/Release、Android R8、iOS Pod 及真机初始化通过。
  • ❌ 并发、100 次循环、隐私、延迟及真实竞价结果按业务完成验收。

真机投放、点击、关闭和各广告源适配器由接入方在目标设备验收。本文描述桥接接口和推荐用法。

2026-10-23 开屏底部与诊断补充 #

开屏不再接收 Dart Widget 底部:Android 使用宿主 XML bottomTemplate,iOS 使用宿主 UIView 类名或引擎工厂。 load 支持底部配置,iOS 在 SDK load 前设置 bottomView;show 可单次覆盖,useBottomView:false 清空。 尺寸为逻辑像素,bottomRatio 优先于 bottomHeight。 双端 Splash/Rewarded/Interstitial 各自独立 bridge,原有 channel 名保持。 UBidding.configureLogging(level: UBiddingLogLevel.debug) 控制 Dart 和当前原生引擎的控制台日志,默认 Info; 与 SDK debugLogEnabled 独立。无文件日志或上传行为。

5
likes
0
points
0
downloads

Publisher

unverified uploader

Weekly Downloads

Flutter bridge plugin for UBiddingAdSDK supporting splash, interstitial, rewarded video, banner and native ads on Android and iOS.

Homepage

License

unknown (license)

Dependencies

flutter

More

Packages that depend on ubidding_flutter

Packages that implement ubidding_flutter