Ad Detector - Android Integration Instructions

This document is intended for developers integrating the Ad SDK, explaining how to capture frames of the ad screen within the display callback in two scenarios: banner/native (with container) and splash/interstitial/rewarded Video (without container). These frames can be used for material archiving, random checks, or reporting. Please refer to the Ad SDK's display API and callbacks for direct implementation.

1.  Module capabilities

2. Gradle integration

2.1  As a submodule of the source code (same as this Demo)

Add the following to the dependencies section of the module's build.gradle file:

dependencies {
    implementation files("libs/material-monitor-release")
    // The advertising SDK dependency must be retained to ensure that AdInfo exists at runtime.
}

2.2  Permissions and Requirements

• minSdkVersion：The build.gradle file for this repository is set to 21; if the host application has a higher value, the host application's value will prevail.

• Java 8+。

• Network permissions：Reporting requires the host to have INTERNET. The module has declared ACCESS_NETWORK_STATE (used for pre-checking whether there is an available external network before uploading; after merging the manifest, the system grants "view network connections" type permissions).

  plaintext Copy

  <?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.  initialization

In the first Activity.onCreate call (which internally registers lifecycle callbacks to track the foreground Activity, see demo):

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

public class FirstActivity extends Activity {
    @Override
    public void onCreate() {
        super.onCreate();
        // The developer user agreement allows them to obtain and populate device information independently.
        MaterialMonitor.init(this, new MaterialMonitorConfig.Builder()
                .baseUploadUrl("https://your-gateway-host")   // Upload address
                .appId("YOUR_APP_ID")
                .appKey("YOUR_APP_KEY")                      // Please do not disclose.
                .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  Parameters at a glance

Classpath:：com.github.material.monitor.MaterialMonitorConfig。After construction, it can be read via MaterialMonitor.get().getConfig(); isUploadConfigured() is true when baseUploadUrl, appId, and appKey are all non-empty (a prerequisite for automatic enqueueing and reporting).

Collect only, do not upload：However, MaterialMonitor.init(this) will use the default empty configuration; in this case, automatic enqueueing / reportFrameRecord will result in ErrorCodes.NOT_READY due to incomplete upload parameters (see §8).

4.  When to call DelayMs, suggestions and special scenarios

4.1  General principles

Call this function in callbacks where the ad has been displayed, the target area has been laid out, and the ad is still attached (e.g., onAdShow, banner display callback, or after native data binding).
FrameOptions.delayMs indicates how many milliseconds to wait from the time of the call before actually taking a screenshot. This is used to avoid situations such as blank screens, the first frame of the footage or video not being ready, or slow loading on a weak network.

4.2  Due to network and material loading delays, we recommend (default values).

Considering the difference that video materials buffer slower in weak network conditions, while static or HTML materials buffer relatively faster, the following suggestions are recommended (which can be deployed in remote configuration and fine-tuned according to traffic levels):

The above is for the routine monitoring of "only capturing one frame per display"; it can be used in combination with "multiple frames before excitation is turned off" in §4.3.

4.3  Rewarded Video：On-demand before closing; zero latency; multiple frames per interval.

To more accurately identify illegal screens, abnormal jumps, and end-frame inducements, you can use delayMs(0) to perform real-time frame capture at the node where the screen is stably visible before the ad is about to close or the user is about to leave, and call it multiple times at business intervals (e.g., once every 5 seconds).

Notice：

• delayMs(0) means no extra waiting, but still requires that View has been laid out and still attached to the window when called; if called too early, it may still fail (VIEW_INVALID / black frame), please put the "0 delay call" in a callback that is later in the lifecycle and the content has been displayed.
• Each time collectFrameFrom generates a new FrameRecord.uploadTaskId (queue idempotent key), the same ad display can be captured and reported multiple times; the gateway side display dimension is still consistent with AdInfo.getShowId() and meta.event_info.
• Multiple frames will increase traffic, queue length, and daily quota consumption. Please agree on a frequency limit with product/compliance. If multiple frames need to be captured, it is recommended to capture them once every 5 seconds, using the longest side pixel (maxLongEdge) standard of 1080. If there is a high frequency requirement, the maxLongEdge standard should be reduced to 720 or 540. High-frequency frame capture will increase the risk of ANR or excessive memory usage.

Example (pseudocode: sample one more frame at a short interval before the excitation is turned off, delayMs is 0):

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

4.4  Native self-rendering: Select capture API based on material type

For native self-rendering ads, please select the API (Demo reference: NativeAdActivity for images, NativePatchVideoActivity for videos) according to the Main Creative Type:

• creativeAssetUrl：Image scenario: Send if available; must begin with http:// or https://. A blank space or an invalid protocol will not fail the entire call, but will instead revert to a screenshot.
• When url-only is successful, FrameRecord.file will be null, and multipart will not include the image part; specific required rules are subject to the gateway documentation.

5. API Reference (Input Parameters, Return Values, and Usage)

Package Name：com.github.material.monitor。Unless otherwise specified below, all data collection-related callbacks are performed on the main thread (see thread description in the external implementation plan).

5.1 MaterialMonitor.init / get / getConfig

5.2 collectFrameFromAdContainer

sign

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

Behavior: After successful verification, postDelayed(delayMs) is executed, at which point a screenshot is taken → the image is compressed and written to disk → onCollectSuccess in the main thread → if upload is configured, enqueueReport is executed automatically. If it fails, onCollectFailure is executed (the image is not enqueued).

Style Directory: MaterialStyle is resolved internally based on AdInfo and used for local subdirectory names (such as rewarded_video). It corresponds to the meaning of the gateway ad_type and does not need to be passed in by the caller.

5.3 collectFrameFromAdPage

sign

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

Applicable to: Interstitial/incentive ads, etc. When there is no stable business-side ad container, or when it is difficult to retrieve child Views in full-screen coverage (Demo: InterstitialAdActivity, RewardVideoAdActivity, pass in this).
Common reasons for failure: No available Activity after the delay / Capture View → ACTIVITY_INVALID; Weak reference Activity being recycled, etc.

示例：

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

5.4 onAdClosed

sign

void onAdClosed(AdInfo adInfo)

Behavior: If the same showId's collectFrameFromAdContainer or collectFrameFromAdPage has not yet executed a screenshot, then cancel this collection and call back onCollectFailure(COLLECT_CANCELLED, ...) to avoid capturing a blank page or the host page even when the ad is turned off.

When to call: Called in the ad's close callback (Demo: onInterstitialAdClose, onRewardedVideoAdClosed). Recommended to call: For interstitials displayed on the Dialog/overlay/host Activity; can be omitted if the independent full-screen AdActivity has a sufficient lifecycle.

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

5.5 reportFrameRecord

sign

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

Typical Uses: First collect data and write it to disk, then upload it at an opportune time; or re-upload after a successful data collection but a previous upload failure (note the semantics of uploadTaskId and duplicate queuing).

5.6 flushPendingFrames

void flushPendingFrames()

Function: Actively requesting modules to process, as quickly as possible, any remaining pending upload tasks in SQLite (internally scheduling the drain in the upload executor, which is from the same source as the processing triggered by "new task queuing"). It can be called from any thread; internally, it switches between the upload thread and the main thread's Handler, and does not perform HTTP operations on the calling thread.

Typical Use Cases (Select as needed; generally harmless when combined with "Automatic Drain for New Tasks Joining the Queue"):

Generally unnecessary: Automatic drain during in-process enqueueing/init is sufficient to upload gradually after network recovery; without global network monitoring, it's enough to call at least once the network availability callback is available and the main Activity's onResume function is invoked.

Relationship with "No Network Delay": flush only wakes up the upload queue and does not re-capture; when there is no network, the pre-check will still fail and be re-scheduled within the drain, but it is more timely than waiting for the timer to run.
Note: flush does not bypass the daily quota gate; if local files have been deleted or the task has ended, no uploads can be performed. See §9 for details on network delays, callback semantics, etc.

6. FrameOptions and AdTimingInput

6.1 FrameOptions.Builder

Build: new FrameOptions.Builder().delayMs(2000).maxSizeKb(300).build()。

6.2 AdTimingInput

The gateway's required semantics for request_ts / fill_ts / show_ts are subject to the integration documentation; for items with values ​​≤0 , the database will backfill according to the equivalent seconds of show_ts (see CreativeMetaBuilder), it is still recommended to pass in the actual three-stage time in the production environment.

7.  Callback Explanation（FrameCallback / AbstractFrameCallback）

AbstractFrameCallback() {
            @Override
            public void onCollectSuccess(FrameRecord record) {
                // Main thread: When the screenshot is successful, the file is already written; when url-only, the file is null and only the image_url is included.
            }

            @Override
            public void onCollectFailure(int errorCode, String message, Throwable cause) {
                // Main thread: Uploads not yet in queue
            }

            @Override
            public void onReportSuccess(FrameRecord record) {
                // Main thread: Upload successful; record.getFile() is usually null (the library for JPEG has been removed).
            }

            @Override
            public void onReportSkip(FrameRecord record, String reason) {
                // Main thread: repetitive tasks, quota blocking, etc.
            }

            @Override
            public void onReportFailure(int errorCode, String message, FrameRecord record, Throwable cause) {
                // Main thread: record may be null (terminal failed and has been cleaned up).
            }
        }

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

If the frameCallback needs to hold the activity, two usage paths are recommended to avoid memory leaks:

1. static inner class + reference Activity.this method: refer to MaterialMonitorHelper.demoFrameCallback(activity) for weak reference to the activity;
2. Anonymous / Non-static inner class + strong reference Activity.this method: can be used in the activity onDestroy interface, passing in the same instance as collect frameCallback:

  MaterialMonitor.get().detachCallback(frameCallback);

8.  Error Code Quick Reference（com.github.material.monitor.ErrorCodes）

In the SDK callback, the errorCode values ​​are all 6xxx client-side codes, which are not the same set of values ​​as the code (1xxx ~ 5xxx) in the gateway's HTTP response JSON. When troubleshooting gateway issues, please check the gateway NNNN: … prefix in the failed message and refer to the CreativeAuditGateway - SDK Integration Documentation.

8.1  End-side error codes overview

8.2  Callbacks and Error Codes

Collection vs. Reporting: 6001-6004 and 6009 only appear in onCollectFailure; 6005-6008 mainly appear in onReportFailure (6005 may also be triggered at the collection entry point).

8.3  Gateway code and endpoint errorCode

Do not mix the 6xxx endpoint codes with the gateway codes 1xxx to 5xxx in the same set of tracking points. See §8.4 for a complete list of gateway codes.

8.4  Gateway response error codes（CreativeAuditGateway）

The upload interface POST .../v1/creative/upload returns JSON, where code == 0 indicates success (HTTP is usually 200). On failure, code will be non-zero, and trace_id may be returned on both success and failure. Please log failures for easy troubleshooting.

The following is consistent with Section 8 of document/CreativeAuditGateway - SDK Integration Documentation.md; if there are any additions or deletions to the gateway version, the online interface documentation shall prevail.

8.4.1  success

8.4.2 1xxx —  Authentication error (cannot be retried)

8.4.3 2xxx —  Parameter/Image error (cannot be retried)

8.4.4 3xxx — Quota error (will not be reported again today)

8.4.5 4xxx —  Rate limiting (can be retried)

8.4.6 5xxx —  Server-side error (please retry)

8.4.7 material-monitor  Processing of gateway codes

9.  Network, offline latency and queuing

9.1  Queues and Threads

• When data collection is successful and upload is configured, the task is written to SQLite and uploaded sequentially by a single-threaded uploadExecutor.
• Daily Quota (3001/3002): May contain onReportSkip, reason, and daily_quota_reset_at (see gateway documentation).

9.2  No network / Transport layer failure (NETWORK_ERROR = 6006)

The upload thread calls NetworkReachability.hasInternet (which requires ACCESS_NETWORK_STATE, merged into the host module's manifest) before actually initiating the HTTP request:

• Android M (API 23) and above: The current default network must have NET_CAPABILITY_INTERNET and NET_CAPABILITY_VALIDATED (the system has determined that it can access the internet), otherwise it is considered to have no network.
• Even earlier versions: Continue only if NetworkInfo.isConnected() is true.

If the preflight checks for no network access, or if the HttpURLConnection fails before receiving the HTTP status line (timeout, UnknownHost, no route, etc., the upload result will show httpCode==0 and gatewayCode==-1), then the process will proceed to the delayed path:

The host can call MaterialMonitor.get().flushPendingFrames() in places such as NetworkCallback.onAvailable and onResume when returning to the foreground, to shorten the "wait 30 seconds" window (it is harmless to overlap with internal timers).

9.3 flushPendingFrames（summary）

MaterialMonitor.get().flushPendingFrames();

Actively wake up the queue once using drain; can be called from any thread. See §5.7 table for typical scenarios.

10.  Privacy and Compliance Recommendations

• Only capture the ad-related area of the View to avoid including sensitive personal screens.
• Device identifiers (OAID, GAID, etc.) must comply with local laws and platform policies.
• Hardcoding the appKey in publicly accessible places is not recommended.

11.  Troubleshooting List

For the complete error code table, see  §8。