💡 最佳实践

综合整理 GroMore 广告在 Flutter 项目中的排查思路、性能优化与数据监控要点。

1. 初始化排查清单

Future<void> verifyInitialization() async {
  // 权限
  if (Platform.isAndroid) {
    final granted = await GromoreAds.requestPermissionIfNecessary;
    debugPrint('Android permission: $granted');
  } else if (Platform.isIOS) {
    await GromoreAds.requestIDFA;
  }

  // SDK 初始化
  final ok = await GromoreAds.initAd(
    'your_app_id',
    useMediation: true,
    debugMode: kDebugMode,
  );
  debugPrint('GroMore init => $ok');

  // 如需限制个性化广告、替换本地 config，可在此额外传入 limitPersonalAds、config 等可选参数。
}

若初始化失败，请再次确认：

应用 ID 与广告位是否在 GroMore 控制台启用；
Android AndroidManifest、iOS Info.plist 权限是否齐全；
网络连通性与代理设置是否正常。

2. 加载失败重试策略

Future<bool> loadWithRetry(Future<bool> Function() loader, {int maxRetry = 3}) async {
  for (var attempt = 0; attempt < maxRetry; attempt++) {
    final ok = await loader();
    if (ok) return true;
    await Future.delayed(Duration(seconds: 1 << attempt));
  }
  return false;
}

// 使用示例
final rewardReady = await loadWithRetry(() => GromoreAds.loadRewardVideoAd('reward_pos_id'));

3. 预加载策略

分类配置：按业务场景拆分 PreloadConfig 列表；
网络判断：Wi-Fi 环境下可调高 parallelNum，移动网络适当降低；
定期刷新：长时间停留的页面可每隔数分钟调用一次 preload；
存量管理：记录已领取到的 feed/draw 广告 ID，使用后调用 clearFeedAd / clearDrawFeedAd 及时释放。

Future<void> smartPreload(bool isWifi) async {
  final configs = <PreloadConfig>[
    if (isWifi) const PreloadConfig.rewardVideo(['reward_pos_id']),
    const PreloadConfig.interstitial(['interstitial_pos_id']),
  ];

  if (configs.isEmpty) return;
  await GromoreAds.preload(
    configs: configs,
    parallelNum: isWifi ? 3 : 1,
    requestIntervalS: 2,
  );
}

4. 内存与资源管理

使用 Banner Widget 时无需手动销毁；调用 API 方式时记得 destroyBannerAd()；
Feed/Draw 广告使用结束后调用 clearFeedAd / clearDrawFeedAd 并清理自有缓存；
页面切换时可调用 GromoreAds.removeEventListener()，避免后台仍处理事件。

5. 监控与埋点

class AdMonitor extends OnAdEventListener {
  final _metrics = <String, _Record>{};

  @override
  void onAdEvent(AdEvent event) {
    final record = _metrics.putIfAbsent(event.posId, () => _Record());
    if (event.action.endsWith('_loaded')) record.loaded++;
    if (event.action.endsWith('_showed')) record.shown++;
    if (event.action.endsWith('_clicked')) record.clicked++;
  }

  @override
  void onAdError(AdErrorEvent event) {
    final record = _metrics.putIfAbsent(event.posId, () => _Record());
    record.failed++;
  }

  Map<String, Map<String, int>> snapshot() {
    return _metrics.map((posId, record) => MapEntry(posId, record.toJson()));
  }
}

class _Record {
  int loaded = 0;
  int shown = 0;
  int clicked = 0;
  int failed = 0;

  Map<String, int> toJson() => {
        'loaded': loaded,
        'shown': shown,
        'clicked': clicked,
        'failed': failed,
      };
}

将统计结果上报到 BI/埋点系统，有助于分析填充率、点击率与收益。

6. QA 检查清单

[ ] 调试包内启用 debugMode: true 并使用测试广告位；
[ ] 所有广告位均配备事件监听，覆盖错误回调；
[ ] 预加载流程在冷启动/热点场景均验证；
[ ] 服务端奖励回调串联正常；
[ ] 发布包禁用所有测试入口及日志。

按照以上建议可以显著提升 GroMore 广告集成的稳定性与可观测性。