测试工具

功能介绍

GroMore提供可视化测试工具,帮助您在应用上线前:

✅ 校验SDK接入是否正确
✅ 测试广告配置信息
✅ 验证各ADN广告加载是否正常
✅ 查看详细的回调信息和错误日志

⚠️ 重要提示
该测试工具仅限测试阶段使用,请于上线前移除测试工具相关代码和依赖。

🚀 快速开始

前置条件

在使用测试工具前,请确保:

✅ 已完成SDK初始化(initAd)
✅ Android: 已引入tools-release.aar依赖
✅ iOS: 已引入BUAdTestMeasurement.xcframework框架
✅ 已在穿山甲平台注册测试设备

基本使用

import 'package:gromore_ads/gromore_ads.dart';

// 启动测试工具
try {
  bool success = await GromoreAds.launchTestTools();
  if (success) {
    print('测试工具启动成功');
  }
} catch (e) {
  print('测试工具启动失败: $e');
}

📖 完整示例

import 'package:flutter/material.dart';
import 'package:gromore_ads/gromore_ads.dart';

class TestToolsPage extends StatefulWidget {
  @override
  _TestToolsPageState createState() => _TestToolsPageState();
}

class _TestToolsPageState extends State<TestToolsPage> {
  bool _isLoading = false;

  // 启动测试工具
  Future<void> _launchTestTools() async {
    setState(() => _isLoading = true);

    try {
      final success = await GromoreAds.launchTestTools();

      if (!mounted) return;

      if (success) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(
            content: Text('测试工具已启动'),
            backgroundColor: Colors.green,
          ),
        );
      } else {
        throw Exception('启动返回false');
      }
    } catch (e) {
      if (!mounted) return;

      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(
          content: Text('启动失败: $e'),
          backgroundColor: Colors.red,
        ),
      );
    } finally {
      if (mounted) {
        setState(() => _isLoading = false);
      }
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('广告测试工具'),
        backgroundColor: Colors.blue,
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Icon(
              Icons.bug_report,
              size: 80,
              color: Colors.blue,
            ),
            SizedBox(height: 20),
            Text(
              '点击按钮启动测试工具',
              style: TextStyle(fontSize: 16),
            ),
            SizedBox(height: 40),
            ElevatedButton.icon(
              onPressed: _isLoading ? null : _launchTestTools,
              icon: _isLoading
                  ? SizedBox(
                      width: 20,
                      height: 20,
                      child: CircularProgressIndicator(
                        strokeWidth: 2,
                        color: Colors.white,
                      ),
                    )
                  : Icon(Icons.play_arrow),
              label: Text(_isLoading ? '启动中...' : '启动测试工具'),
              style: ElevatedButton.styleFrom(
                padding: EdgeInsets.symmetric(horizontal: 30, vertical: 15),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

💡 实际场景示例

场景1: 开发阶段广告测试

需求描述: 开发阶段需要快速验证各广告位配置是否正确,各ADN SDK是否正常接入。

实现代码:

import 'package:flutter/foundation.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: MyHomePage(),
        // 仅在Debug模式显示测试工具入口
        floatingActionButton: kDebugMode
            ? FloatingActionButton(
                onPressed: () async {
                  await GromoreAds.launchTestTools();
                },
                child: Icon(Icons.bug_report),
                tooltip: '启动广告测试工具',
                backgroundColor: Colors.orange,
              )
            : null,
      ),
    );
  }
}

关键配置说明:

使用kDebugMode确保仅在Debug模式下显示
使用FloatingActionButton提供快速入口
位置固定在右下角,不影响正常UI

预期效果:

Debug模式:右下角显示浮动按钮,点击可启动测试工具
Release模式:浮动按钮不显示,保持生产环境干净

场景2: 广告位配置验证

需求描述: 在穿山甲平台创建广告位后,需要验证广告位ID是否配置正确、能否正常填充广告。

操作流程:

启动测试工具
在工具界面选择要测试的广告位
查看广告位详情和代码位列表
点击"加载广告"按钮测试加载
点击"展示广告"按钮测试展示
查看回调信息确认是否成功

测试结果判断:

✅ 测试成功:全部代码位成功完成展示,可以看到CPM信息
⚠️ 测试失败:代码位加载失败,查看错误码和错误信息定位问题
🟡 未测试:仅完成加载但未展示,或尚未开始测试

场景3: 问题排查流程

需求描述: 广告无法正常展示时,使用测试工具定位问题。

排查步骤:

第一步:检查SDK接入情况

启动测试工具 → 查看首页"组件接入情况"

确认内容:

融合SDK是否初始化成功
各ADN SDK是否正确接入(绿色图标)
Adapter版本是否在支持范围内

第二步:测试具体广告位

选择广告位 → 查看代码位列表 → 加载测试

观察加载结果:

成功:进入第三步测试展示
失败:查看回调信息中的错误码和错误信息

第三步:分析错误信息

根据错误类型修复:

错误类型	可能原因	解决方案
代码位配置错误	平台填写错误、代码位ID不匹配	检查穿山甲平台配置
渲染类型不匹配	信息流/激励广告未配置渲染类型	在代码位详情页选择渲染类型
底价过高	竞价失败,出价低于底价	调整广告位底价设置
网络问题	网络连接失败、IP限制	检查网络连接、VPN设置
设备未注册	测试设备ID未在平台注册	在平台添加测试设备ID

🔧 测试工具功能说明

可视化测试界面

测试工具提供完整的可视化界面,包括以下模块:

1. SDK接入检测

功能说明:

显示融合SDK版本号
列出所有配置的ADN SDK
显示各ADN SDK接入状态(已接入/未接入)
显示Adapter版本是否在支持范围内

状态指示器:

🟢 绿色:SDK已接入,版本正常
🔴 红色:SDK未接入或版本不匹配

2. 广告位测试

功能说明:

显示应用下所有广告位列表
查看广告位下的代码位详情
测试广告加载和展示
查看测试状态和结果

测试状态:

🟡 未测试:尚未开始测试,或仅完成加载未展示
✅ 测试成功:全部代码位成功展示
❌ 测试失败:存在加载失败的代码位

3. 调试信息查看

功能说明:

显示广告加载回调信息
显示广告展示回调信息
显示错误码和详细错误信息
展示成功后显示CPM、ADN等信息

回调信息示例:

onAdLoaded: 广告加载成功
Prime_rit: xxxxx
ADN: CSJ
CPM: 5.00

支持的广告类型

广告类型	支持状态	说明
开屏广告	✅ 支持	完整支持测试
激励视频广告	✅ 支持	需选择渲染类型
信息流广告	✅ 支持	需选择渲染类型
Draw信息流	✅ 支持	完整支持测试
Banner广告	✅ 支持	完整支持测试
插屏广告	⚠️ 暂不支持	官方SDK限制

⚠️ 注意事项

生产环境移除

🔴 必须在上线前移除
测试工具严禁带到线上环境,上线前必须移除:
代码移除:
删除所有调用GromoreAds.launchTestTools()的代码
删除测试工具相关的UI入口(如浮动按钮、菜单项等)
依赖移除:
Android: 从build.gradle中移除tools-release.aar依赖
iOS: 从项目中移除BUAdTestMeasurement.xcframework框架
验证方法:
全局搜索launchTestTools确认无残留调用
检查依赖配置确认已移除测试工具包

平台差异

💡 iOS平台特殊限制
仅Debug构建可用:测试工具使用#if DEBUG编译条件,Release构建会自动禁用
最低版本要求:要求iOS 10.0或更高版本
自动保护:Release包中调用launchTestTools()会返回错误,不会影响用户
💡 Android平台注意
无构建类型限制:测试工具在Debug和Release构建中都可用
需手动移除:必须手动删除代码调用和依赖,否则会带到生产环境
建议实践:使用kDebugMode或自定义flavor控制测试工具入口

前置条件

📋 使用前必须满足
SDK初始化:必须先调用initAd完成SDK初始化
UI容器可用:
Android需要有可用的Activity
iOS需要有可用的ViewController
权限开启:
Android:建议开启设备信息权限(用于获取IMEI、AndroidId、OAID)
iOS:建议开启广告追踪权限(用于获取IDFA)
设备注册:在穿山甲平台注册测试设备ID

测试设备注册

🧪 如何注册测试设备
登录穿山甲平台
进入"应用管理" → 选择应用 → "测试设备管理"
添加测试设备ID:
Android: 建议填入IMEI、AndroidId、OAID(三选一或全填)
iOS: 建议填入IDFA
保存后等待生效(通常几分钟内)
推荐测试设备:
Android 9及以下版本(更容易获取设备ID)
iOS 13及以下版本(更容易获取IDFA)

常见问题

Q: 启动测试工具提示"SDK未初始化"?

A: 必须先调用initAd完成SDK初始化,建议在应用启动时初始化。

// 应用启动时初始化
await GromoreAds.initAd(
  'your_app_id',
  useMediation: true,
  debugMode: true,
);

// 初始化完成后才能启动测试工具
await GromoreAds.launchTestTools();

Q: iOS Release构建调用测试工具报错?

A: iOS测试工具仅在Debug构建中可用,这是正常保护机制。建议:

import 'package:flutter/foundation.dart';

// 仅在Debug模式调用
if (kDebugMode) {
  await GromoreAds.launchTestTools();
}

Q: Android提示"未找到测试工具依赖"?

A: 需要在build.gradle中引入tools-release.aar:

dependencies {
    implementation files('libs/tools-release.aar')
}

Q: 测试工具显示ADN未接入,但实际已引入SDK?

A: 可能原因:

未在config中配置该ADN
Adapter版本不匹配
ADN SDK初始化失败

建议查看测试工具的详细信息,根据提示修复。

Q: 广告加载失败,显示"设备未注册"?

A: 需要在穿山甲平台添加测试设备ID:

获取设备ID(IMEI/AndroidId/OAID/IDFA)
在平台"测试设备管理"中添加
等待几分钟后重试

🔗 相关功能

快速开始 - 了解SDK初始化流程
开屏广告 - 测试开屏广告配置
激励广告 - 测试激励视频配置
广告预缓存 - 学习广告预加载优化

更新记录:

2025-09-30: 初始版本