广告探测器-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
}

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>

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  秒一次）。

注意：

• 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 collectFrameFromAdPage

签名

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

适用：插屏/激励等  无稳定业务侧广告容器、或全屏覆盖难以取子  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.4 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.5 reportFrameRecord

签名

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

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

5.6 flushPendingFrames

void flushPendingFrames()

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

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

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

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

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

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。