广告事件

---

5. 广告事件 advertising

AdvertisingEvent — APP 内部自定义的活动弹窗等广告互动事件（手动上报）。

AdvertisingEvent({
  required String eventType,       // 事件类型：click(点击)、close(关闭)、show(展示)
  required String advertisingKey,  // 广告标识：home_popup、home_banner、video_reward 等
  required String advertisingName, // 广告标识名称：首页弹窗、首页Banner、激励视频
  required String advertisingId,   // 广告 ID
})

使用示例：

AnalyticsSdk.instance.track(AdvertisingEvent(
  eventType: 'click',
  advertisingKey: 'home_banner',
  advertisingName: '首页Banner',
  advertisingId: 'ad_123',
));

---

6. 广告展示事件 ad_impression

AdImpressionEvent — 广告展示日志（手动上报，SDK 自动去重）。

AdImpressionEvent({
  required String pageKey,      // 页面标识
  required String pageName,     // 页面名称
  required String adSlotKey,    // 广告位标识：home_banner_1 等
  required String adSlotName,   // 广告位名称：首页顶部Banner
  required String adId,         // 广告 ID，多个用英文逗号分隔
  String? creativeId,           // 素材 ID（可选），多个用英文逗号分隔
  required String adType,       // 广告类型：banner、feed、interstitial、reward_video 等
})

使用示例：

import 'package:analytics_sdk/observer/page_lifecycle_observer.dart';
import 'package:analytics_sdk/manager/page_name_manager.dart';

// 单个广告 ID
AnalyticsSdk.instance.track(AdImpressionEvent(
  pageKey: PageLifecycleObserver.currentPageKey,
  pageName: PageNameMapper.getPageName(PageLifecycleObserver.currentPageKey),
  adSlotKey: 'home_banner_1',
  adSlotName: '首页顶部Banner',
  adId: 'ad_123',
  adType: 'banner',
));

// 多个广告 ID（用英文逗号分隔）
AnalyticsSdk.instance.track(AdImpressionEvent(
  pageKey: '/home',
  pageName: '首页',
  adSlotKey: 'home_feed',
  adSlotName: '首页信息流',
  adId: 'ad_123,ad_456,ad_789',
  adType: 'feed',
));

去重机制：

• 所有广告 ID 都已上报过时，跳过本次上报
• 支持多个广告 ID 英文逗号分隔，同一个 ID 只上报一次
• 去重记录存储在内存中，应用重启后清空（确保重新上报）
• 容量限制：默认最多 10000 条，超出后 FIFO 淘汰最旧记录

去重管理 API（高级）：

import 'package:analytics_sdk/manager/ad_impression_manager.dart';

bool isReported = AdImpressionManager.instance.isReported('ad_123');
List<String> unreported = AdImpressionManager.instance.getUnreportedAdIds('ad_123,ad_456');
AdImpressionManager.instance.markAsReported('ad_123');
int count = AdImpressionManager.instance.reportedCount;
AdImpressionManager.instance.trimTo(5000);
AdImpressionManager.instance.clear();

---

7. 广告点击事件 ad_click

AdClickEvent — 广告点击日志（手动上报）。

AdClickEvent({
  required String pageKey,      // 页面标识
  required String pageName,     // 页面名称
  required String adSlotKey,    // 广告位标识，与展示事件一致
  required String adSlotName,   // 广告位名称，与展示事件一致
  required String adId,         // 被点击的广告 ID
  String? creativeId,           // 素材 ID（可选）
  required String adType,       // 广告类型
})

使用示例：

import 'package:analytics_sdk/observer/page_lifecycle_observer.dart';
import 'package:analytics_sdk/manager/page_name_manager.dart';

AnalyticsSdk.instance.track(AdClickEvent(
  pageKey: PageLifecycleObserver.currentPageKey,
  pageName: PageNameMapper.getPageName(PageLifecycleObserver.currentPageKey),
  adSlotKey: 'home_banner_1',
  adSlotName: '首页顶部Banner',
  adId: 'ad_123',
  adType: 'banner',
));