广告素材探测-Android 接入说明

• 本文档面向接入广告SDK 的开发者，说明如何在开屏/横幅/原生（有容器） 与 插屏/激励视频（无容器） 两种场景下，在展示回调里对广告画面做截帧，用于素材归档、抽检或上报。请结合 广告SDK 的展示 API 与回调，便于直接落地实现。
• 下载地址：http://info.appsmartsite.com/Material_monitor/Android_MaterialMonitor.zip

1. 模块能力

2. Gradle 接入

2.1 作为源码子模块（与本 Demo 相同）

在宿主 settings.gradle 中 include ':material-monitor'，在 app 模块：

dependencies {
    implementation project(':material-monitor')
    // 广告 SDK 依赖需保留，保证运行时存在 ATAdInfo
}

将 *_core_*.aar（或与你们版本一致的 core）放到 material-monitor/libs/，与仓库中 material-monitor/build.gradle 的 compileOnly fileTree(dir: 'libs') 一致。

2.2 权限与要求

• minSdkVersion：本库 build.gradle 为 21；宿主若更高以宿主为准。

• Java 8+。

• 网络权限：上报需宿主具备 INTERNET。模块已声明 ACCESS_NETWORK_STATE（用于上传前 是否有可用外网 的预检；合并 manifest 后由系统授予「查看网络连接」类权限）。

  plaintext 复制代码

  <?xml version="1.0" encoding="utf-8"?>
  <manifest xmlns:android="http://schemas.android.com/apk/res/android">
      <uses-permission android:name="android.permission.INTERNET" />
      <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  </manifest>

• Core AAR：将 *_core_*.aar（或与你们版本一致的 core）放到 material-monitor/libs/，与仓库中 material-monitor/build.gradle 的 compileOnly fileTree(dir: 'libs') 一致。

3. 初始化

在首个 Activity.onCreate 调用（内部会注册生命周期回调以跟踪前台 Activity, 参考demo）：

import com.github.material.monitor.MaterialMonitor;
import com.github.material.monitor.MaterialMonitorConfig;

public class FirstActivity extends Activity {
    @Override
    public void onCreate() {
        super.onCreate();
        // 开发者用户协议允许之后自行获取和填充设备信息
        MaterialMonitor.init(this, new MaterialMonitorConfig.Builder()
                .baseUploadUrl("https://your-gateway-host")   // 上传地址
                .appId("YOUR_APP_ID")
                .appKey("YOUR_APP_KEY")                      // 请勿泄漏
                .oaid(oaidString)
                .androidId(androidIdString)
                .gaid(gaidString)
                // .imei(...).mac(...)
                // .maxUploadAttempts(3)
                // .retryDelayMs(3000L, 10000L)
                // .connectTimeoutMs(15000).readTimeoutMs(30000)
                // .debugPerfLogging(BuildConfig.DEBUG)
                .build());
    }
}

3.1 MaterialMonitorConfig.Builder 参数一览

类路径：com.github.material.monitor.MaterialMonitorConfig。构建后可通过** MaterialMonitor.get().getConfig() 读取；isUploadConfigured()** 在 baseUploadUrl、appId、appKey 三者均非空时为 true（自动入队上报的前置条件）。

仅采集、不上传：可MaterialMonitor.init(this) 则使用默认空配置；此时自动入队 / reportFrameRecord 会因未配置完整上传参数而得到 ErrorCodes.NOT_READY（见 §8）。

4. 何时调用、delayMs 建议与特殊场景

4.1 通用原则

在 广告已展示、目标区域已 layout 完成 且仍 attached 的回调里调用（如 onAdShow、Banner 展示回调、原生绑定数据后）。
FrameOptions.delayMs 表示：从调用时刻起再等待多少毫秒 才真正截屏，用于错开白屏、素材或视频首帧未就绪、弱网加载慢等情况。

4.2 因网络与素材加载的延迟建议（推荐默认值）

结合弱网下视频类素材缓冲更慢、静态或 HTML 类相对更快的差异，建议如下（可在远程配置中下发，按流量分层微调）：

以上针对「单次展示只截一帧」的常规监测；与 §4.3 的「激励关闭前多帧」可组合使用。

4.3 激励视频：关闭前按需 0 延时、间隔多帧

为更准确识别 违规画面、异常跳转、结束帧诱导 等，可在 广告即将关闭或用户即将离开 前，在 画面已稳定可见 的节点上，使用 **delayMs(0) 做 即时截帧，并按业务间隔 多次调用（例如每隔 5 秒一次，或在 onReward、onClose 前一刻各一次）。

注意：

• delayMs(0) 表示 不额外等待，仍要求调用时 View 已 layout 且 仍附着在窗口上；若调用过早仍可能失败（VIEW_INVALID / 黑帧），请把「0 延时调用」放在 生命周期靠后、内容已展示 的回调里。

• 每一次 collectFrameFrom* 都会生成 新的 FrameRecord.uploadTaskId（队列幂等键），同一广告展示可多次截帧、多次上报；网关侧展示维度仍以 **ATAdInfo.getShowId() 等与 meta.event_info 一致。

• 多帧会增加 流量、队列长度与日配额 消耗，请与产品/合规约定 频次上限。若有多帧截取需求，建议5秒一次，按最长边像素（maxLongEdge）1080标准；若有高频需求，则需降低maxLongEdge标准如720、540；高频截帧动作会增加ANR或内存上涨过高风险。

示例（伪代码：在激励关闭前短间隔再采一帧，delayMs 为 0）：

FrameOptions urgent = new FrameOptions.Builder().delayMs(0).maxSizeKb(300).build();
MaterialMonitor.get().collectFrameFromAdContainer(rewardContainer, adInfo, timing, urgent, callback);

4.4 原生自渲染：按素材类型选择采集 API

原生自渲染广告请按 主素材类型 选用 API（Demo 参考 NativeAdActivity 图片、NativePatchVideoActivity 视频）：

• creativeAssetUrl：图片场景 有则传；须为 http:// 或 https:// 开头。空白或非法协议不会失败整次调用，而是回退为截屏。

• url-only 成功时 FrameRecord.file 为 null，multipart 不含 image part；具体必填规则以网关文档为准。

5. API 参考（入参、返回值与用法）

包名：**com.github.material.monitor**。以下若无说明，采集相关回调均在主线程（见对外实施方案中的线程说明）。

5.1 MaterialMonitor.init / get / getConfig

5.2 collectFrameFromAdContainer

签名

void collectFrameFromAdContainer(
    View targetView,
    ATAdInfo adInfo,
    AdTimingInput timing,
    FrameOptions options,
    FrameCallback callback
)

行为：校验通过后 **postDelayed(delayMs)，到时截屏 → 压缩写盘 → 主线程 **onCollectSuccess** → 若上传已配置则 自动 **enqueueReport**。失败走 **onCollectFailure**（不会入队）。

样式目录：MaterialStyle 由内部根据 ATAdInfo 解析，用于本地子目录名（如 rewarded_video），与网关 ad_type 含义对应，无需调用方传入。

5.3 collectFrameFromNativeAdContainer

签名

void collectFrameFromNativeAdContainer(
    View targetView,
    ATAdInfo adInfo,
    AdTimingInput timing,
    FrameOptions options,
    String creativeAssetUrl,
    FrameCallback callback
)

行为：有效 URL 时延时结束后直接 onCollectSuccess（file == null）并入队 url-only 上报；回退路径与容器截屏一致。

5.4 collectFrameFromAdPage

签名

void collectFrameFromAdPage(
    Activity hostActivity,
    ATAdInfo adInfo,
    AdTimingInput timing,
    FrameOptions options,
    FrameCallback callback
)

延时后的捕获目标（按优先级）：

1. 当前 前台 resumed Activity（常为 SDK 独立广告页）；

2. 否则回退到 pin 住的 hostActivity；

3. 通过 HostOverlayViewLocator 解析 Dialog / 独立 Window / decor 顶层 overlay，而非简单取 android.R.id.content。

适用：插屏/激励等 无稳定业务侧广告容器、或全屏覆盖难以取子 View 时（Demo：InterstitialAdActivity、RewardVideoAdActivity 传入 this）。
失败常见原因：延时后无可用 Activity / 捕获 View → ACTIVITY_INVALID；弱引用 Activity 被回收等。

示例：

MaterialMonitor.get().collectFrameFromAdPage(
        InterstitialAdActivity.this, adInfo, timing,
        new FrameOptions.Builder().delayMs(3000).build(), callback);

5.5 onAdClosed

签名

void onAdClosed(ATAdInfo adInfo)

行为：若同一 showId 的 collectFrameFromAdContainer 或 collectFrameFromAdPage 尚未执行截屏，则 取消 本次采集并回调 onCollectFailure(COLLECT_CANCELLED, …)，避免广告已关仍截到空白或宿主页。

何时调用：在广告 关闭回调 中调用（Demo：onInterstitialAdClose、onRewardedVideoAdClosed）。Dialog / overlay / 宿主 Activity 上展示的插屏 建议必调；独立全屏 AdActivity 且生命周期已足够时可省略。

@Override
public void onInterstitialAdClose(ATAdInfo adInfo) {
    MaterialMonitor.get().onAdClosed(adInfo);
}

5.6 reportFrameRecord

签名

void reportFrameRecord(FrameRecord record, ATAdInfo adInfo)
void reportFrameRecord(FrameRecord record, ATAdInfo adInfo, ReportCallback callback)

典型用途：先采集落盘、后择机上传；或采集成功但此前上传失败后的补传（注意 uploadTaskId 与重复入队语义）。

5.7 flushPendingFrames

void flushPendingFrames()

作用：主动请求模块 尽快处理一次 SQLite 中仍存在的 待上传任务（内部会调度上传执行器里的 drain，与「新任务入队」触发的处理同源）。可从任意线程调用，内部会切到上传线程与主线程 Handler，不会在调用线程上做 HTTP。

典型使用场景（按需选用；与「新任务入队自动 drain」叠加一般无害）：

一般不必：仅依赖进程内 入队 / init 时的自动 drain 也能在恢复网络后陆续上传；无全局网络监听时，至少在 网络可用回调 + 主 Activity **onResume** 调用即可。

与「无网延后」的关系：flush 只唤醒上传队列，不重新截屏；无网时 drain 内仍会预检失败并再次排程，但比干等定时器更及时。

注意：flush 不绕过日配额门；本地文件已删或任务已终态则无上传可做。无网延后、回调语义等见 §9。

5.8 getRecords / deleteRecord

List<FrameRecord> getRecords(MaterialStyle style)
boolean deleteRecord(FrameRecord record)

**MaterialStyle 枚举：SPLASH、BANNER、INTERSTITIAL、REWARDED_VIDEO、NATIVE（与文件夹名一致，见源码 getFolderName()）。

6. FrameOptions 与 AdTimingInput

6.1 FrameOptions.Builder

构建：new FrameOptions.Builder().delayMs(2000).maxSizeKb(300).build()。

6.2 AdTimingInput

网关对 request_ts / fill_ts / show_ts 的必填语义以对接文档为准；库内对 ≤0 的项会按 show_ts 等同秒做回填（见 CreativeMetaBuilder），生产环境仍建议传入真实三阶段时间。

7. 回调说明（FrameCallback / AbstractFrameCallback）

AbstractFrameCallback() {
            @Override
            public void onCollectSuccess(FrameRecord record) {
                // 主线程：截屏成功时 file 已写好；url-only 时 file 为 null、仅带 image_url
            }

            @Override
            public void onCollectFailure(int errorCode, String message, Throwable cause) {
                // 主线程：未入队上传
            }

            @Override
            public void onReportSuccess(FrameRecord record) {
                // 主线程：上传成功；record.getFile() 通常为 null（库已删 JPEG）
            }

            @Override
            public void onReportSkip(FrameRecord record, String reason) {
                // 主线程：重复 task、配额封禁等
            }

            @Override
            public void onReportFailure(int errorCode, String message, FrameRecord record, Throwable cause) {
                // 主线程：record 可能为 null（终端失败且已清理）
            }
        }

MaterialMonitor.get().collectFrameFromAdContainer(target, adInfo, AdTimingTracker.mock(), options,
                MaterialMonitorHelper.demoFrameCallback(this));

若frameCallback需要持有activity，为避免内存泄漏推荐两种使用路径：

1. static 内部类 + 引用 **Activity.this**方式：参考MaterialMonitorHelper.demoFrameCallback(activity) 弱引用持有activity；

2. 匿名 / 非 static 内部类 + 强引用 **Activity.this**方式：可在activity **onDestroy** 对接 传入与 **collect*** 的同一实例 frameCallback：

  MaterialMonitor.get().detachCallback(frameCallback);

8. 错误码速查（com.github.material.monitor.ErrorCodes）

SDK 回调里的 errorCode 均为 6xxx 端侧码，与网关 HTTP 响应 JSON 的 **code**（1xxx～5xxx）不是同一套数值。排查网关问题时，请看失败 message 里的 gateway NNNN: … 前缀，并对照 CreativeAuditGateway - SDK对接文档。

8.1 端侧错误码一览

8.2 回调与错误码

采集 vs 上报：6001～6004、6009 只出现在 onCollectFailure；6005～6008 主要出现在 onReportFailure（6005 也可能在采集入口触发）。

8.3 网关 code 与端侧 errorCode

不要把 6xxx 端侧码与网关 1xxx～5xxx 混在同一套埋点枚举里。网关码完整表见 §8.4。

8.4 网关响应错误码（CreativeAuditGateway）

上传接口 POST …/v1/creative/upload 返回 JSON，**code == 0** 表示成功（HTTP 通常为 200）。失败时 code 为非 0，且 **trace_id** 在成功与失败时均可能返回，请失败时落日志便于排查。

以下与 **document/CreativeAuditGateway - SDK对接文档.md** §八 一致；若网关版本有增删，以在线接口说明为准。

8.4.1 成功

8.4.2 1xxx — 鉴权错误（不可重试）

8.4.3 2xxx — 参数 / 图片错误（不可重试）

8.4.4 3xxx — 配额错误（当日不再上报）

8.4.5 4xxx — 限流（可重试）

8.4.6 5xxx — 服务端错误（可重试）

8.4.7 material-monitor 对网关码的处理

9. 网络、无网延后与队列

9.1 队列与线程

• 采集成功且上传已配置时，任务写入 SQLite，由 单线程 uploadExecutor 顺序上传。

• 日配额（3001/3002）：可能 onReportSkip，reason 含 daily_quota_reset_at（见网关文档）。

9.2 无网 / 传输层失败（NETWORK_ERROR = 6006）

上传线程在 真正发起 HTTP 之前 会调用 NetworkReachability.hasInternet（需 ACCESS_NETWORK_STATE，由本模块 manifest 合并进宿主）：

• Android M（API 23）及以上：当前默认网络须具备 NET_CAPABILITY_INTERNET 且 NET_CAPABILITY_VALIDATED（系统已判定可上网），否则视为无网。

• 更低版本：NetworkInfo.isConnected() 为真才继续。

若预检判定无网，或 HttpURLConnection 在收到 HTTP 状态行之前失败（超时、UnknownHost、无路由等，上传结果表现为 **httpCode==0 且 gatewayCode==-1），进入 延后路径：

宿主可在 **NetworkCallback.onAvailable**、回到前台的 **onResume** 等处调用 **MaterialMonitor.get().flushPendingFrames()**，缩短「等 30 秒」的空窗（与内部定时叠加无害）。

9.3 flushPendingFrames（摘要）

MaterialMonitor.get().flushPendingFrames();

主动唤醒一次队列 drain；可从任意线程调用。典型场景见 §5.7 表格。

10. 隐私与合规建议

• 只截取 广告相关区域 的 View，避免把个人敏感界面截进去。

• 设备标识（OAID、GAID 等）请遵守当地法律与平台政策。

• appKey 不建议硬编码在公开的地方。

11. 排错清单

完整错误码表见 §8。