MonetriX SDK Integration Doc

ChangeLog

1. Importing the SDK

Please add dependency in your App's build.gradle:

dependencies {
    ...
    implementation 'ai.monetrix:monetrix-ads:1.2.0.2'
}

To improve ad performance, the SDK automatically adds the following declarations in the Manifest file:

• Network access permission
• GAID access declaration
• Allows cleartext traffic for a specific domain (127.0.0.1):

This domain is intended to set up a local server, enabling video download while playing, which helps reduce ad loading time and improve impression rates. The specified domain whitelist does not violate any privacy policies, and the SDK strictly adheres to all applicable privacy regulations.

<?xml version="1.0" encoding="utf-8"?>
<manifest ...>
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="com.google.android.gms.permission.AD_ID" />

    <application
        ...
        android:networkSecurityConfig="@xml/network_security_config"
        tools:replace="android:networkSecurityConfig"
        ...>
    </application>
</manifest>

SDK automatically adds the following file: res/xml/network_security_config.xml

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">127.0.0.1</domain>
    </domain-config>
</network-security-config>

If a conflict with the networkSecurityConfig occurs after integrating the SDK, please resolve as follows.

<?xml version="1.0" encoding="utf-8"?>
<manifest ...>
    <application
        ...
        android:networkSecurityConfig="@xml/network_security_config"
        tools:replace="android:networkSecurityConfig"
        ...>
    </application>
</manifest>

2. Initializing the SDK

Refer to the sample code below: pass in the App ID and call Monetrix.initialize() to initialize SDK, and then use Monetrix.InitListener to monitor initialization results.

private void initSDK() {
    InitConfig.Builder builder = new InitConfig.Builder()
            .setAppId("App-ID");
    InitConfig config = builder.build();

    Monetrix.initialize(this.getApplicationContext(), config, new Monetrix.InitListener() {
        @Override
        public void onInitSuccess() {
            log("SDK initialized");
        }

        @Override
        public void onInitFail(int code, String message) {
            log("SDK init failed: code=" + code + ",message=" + message);
        }
    });
}

3. Interstitial Ads

3.1 Loading an Ad

Before requesting interstitial ads, please make sure the SDK has been initialized.

First, declare an InstlAd object, build an InstlAdLoad instance, and pass in the Placement ID. Then, create an InstlAdLoader instance, call the loadAd() method to request an ad, and use AdLoadCallback to receive callbacks from the ad request.

InstlAdLoad adRequest = new InstlAdLoad.Builder()
        .withPlacementId(pid)
        .build();
InstlAdLoader loader = new InstlAdLoader.Builder()
        .withAdLoadCallback(new AdLoadCallback<InstlAd>() {
            @Override
            public void onError(@NonNull AdError error) {
                log("onError " + error.getCode() + ";" + error.getMessage());
            }

            @Override
            public void onAdLoaded(@NonNull InstlAd ad) {
                handleAd(ad);
            }
        }).build();
loader.loadAd(adRequest);

3.2 Showing Interstitial Ads

After the ad is loaded (onAdLoaded), call InstlAd.show() to display, and register the ad events listeners with InstlAd.setAdListener()

void handleAd(Ad ad) {
    ad.setAdListener(new AdListener() {

        @Override
        public void onAdError(@NonNull AdError error) {
            log("onAdError" + error);
        }

        @Override
        public void onAdDisplayed() {
            log("onAdDisplayed");
        }

        @Override
        public void onAdClicked() {
            log("onAdClicked");
        }

        @Override
        public void onAdOpened() {
            log("onAdOpened");
        }

        @Override
        public void onAdClosed() {
            log("onAdClosed");
        }
    });
    ((InstlAd) ad).show();
    handleBid(ad);
}

3.3 Destroying the Ads

Once the ad has been shown or is no longer used, destroy it using the following method:

ad.destroy();

4. Rewarded Video Ads

4.1 Loading an Ad

Before requesting rewarded video ads, please make sure the SDK has been initialized.

First, declare a RwdAd object, build a RwdAdLoad instance, and pass in the Placement ID. Then, create a RwdAdLoader instance, call the loadAd() method to request an ad, and use AdLoadCallback to receive callbacks from the ad request.

private void loadRewardVideoAd(String pid) {
    showProgress();
    RwdAdLoader adLoader = new RwdAdLoader.Builder()
            .withAdLoadCallback(new AdLoadCallback<RwdAd>() {
                @Override
                public void onError(@NonNull AdError error) {
                    log("onError " + error.getCode() + ";" + error.getMessage());
                }

                @Override
                public void onAdLoaded(@NonNull RwdAd ad) {
                    handleAd(ad);
                }
            }).build();
    RwdAdLoad adRequest = new RwdAdLoad.Builder()
            .withPlacementId(pid)
            .build();
    adLoader.loadAd(adRequest);
}

4.2 Showing Rewarded Video Ads

After the ad is loaded (onAdLoaded), call RwdAd.show() to display, and register the ad events listeners with RwdAd.setAdListener()

void handleAd(Ad ad) {
    ((RwdAd)ad).setAdListener(new RwdAdListener() {
        @Override
        public void onAdRewarded() {
            log("onAdRewarded");
        }

        @Override
        public void onAdError(@NonNull AdError error) {
            log("onAdError" + error);
        }

        @Override
        public void onAdDisplayed() {
            log("onAdDisplayed");
        }

        @Override
        public void onAdClicked() {
            log("onAdClicked");
        }

        @Override
        public void onAdOpened() {
            log("onAdOpened");
        }

        @Override
        public void onAdClosed() {
            log("onAdClosed");
        }
    });
    ((RwdAd) ad).show();
    handleBid(ad);
}

4.3 Destroying the Ads

Once the ad has been shown or is no longer required, destroy it using the following method:

ad.destroy();

5. Banner

5.1 Loading an Ad

Before requesting banner ads, please make sure the SDK has been initialized.

First, declare a BannerAd object

BannerAd mBannerAd;

Then build a BannerAdLoad instance

BannerAdLoad adRequest = new BannerAdLoad.Builder()
        .withPlacementId(pid)
        .build();

Build a BannerAdLoader instance and pass in AdLoadListener to receive callbacks from the ad request, then call loadAd() to request an ad

BannerAdLoad adRequest = new BannerAdLoad.Builder()
        .withPlacementId(pid)
        .build();
BannerAdLoader loader = new BannerAdLoader.Builder()
        .withAdLoadCallback(new AdLoadCallback<BannerAd>() {
            @Override
            public void onError(@NonNull AdError error) {
                log("onError " + error.getCode() + ";" + error.getMessage());

            }

            @Override
            public void onAdLoaded(@NonNull BannerAd ad) {
                handleAd(ad);
            }
        }).build();

loader.loadAd(adRequest);

5.2 Showing Banner Ads

When a Banner Ad fills, use BannerAd.adView() method to fetch banner ad view and add it to your window

adViewContainer.addView(mBannerAd.adView());

Register ad events with BannerAd.setAdListener() method

void handleAd(Ad ad) {
    ad.setAdListener(new AdListener() {

        @Override
        public void onAdError(@NonNull AdError error) {
            log("onAdError" + error);
        }

        @Override
        public void onAdDisplayed() {
            log("onAdDisplayed");
        }

        @Override
        public void onAdClicked() {
            log("onAdClicked");
        }

        @Override
        public void onAdOpened() {
            log("onAdOpened");
        }

        @Override
        public void onAdClosed() {
            log("onAdClosed");
        }
    });
    mAdContainerLayout.removeAllViews();
    View view = ((BannerAd) mAd).adView();
    if (view != null) {
        mAdContainerLayout.addView(view);
    }
    handleBid(ad);
}

5.3 Destroying the Ads

Once the ad has been shown or is no longer required, destroy it using the following method:

adViewContainer.removeAllViews();
mBannerAd.destroy();

6. User Privacy Settings

Before initializing the SDK, please complete the following privacy configurations:

GDPR

If no third-party CMP platform is integrated, you can use the following interface to pass whether the user has granted consent to share their personal information.

import com.monetrix.adsdk.Monetrix;

Monetrix.setGDPRFlag(this, true);
// user has granted consent to collecting and using personal info

Monetrix.setGDPRFlag(this, false);
// user refused to grant consent to collecting and using personal info

CCPA

If the user is subject to the California Consumer Privacy Act (CCPA), you can use the following interface to pass whether the user has granted consent to share their personal information.

import com.monetrix.adsdk.Monetrix;

Monetrix.setCCPAFlag(this, true);
// user has granted consent to collecting and using personal info

Monetrix.setCCPAFlag(this, false);
// user refused to grant consent to collecting and using personal info

COPPA

import com.monetrix.adsdk.Monetrix;

Monetrix.setDirectToChildFlag(this, false);
// The user is not a child under 13

Monetrix.setDirectToChildFlag(this, true);
// The user is a child under 13

7. Advanced Settings

If you integrate Client Bidding, you can fetch the price for this impression and bid on client side

7.1 Getting Impression-level Price

When ad fills, call the getBid() and getBiddingPrice() methods to obtain the price (unit: eCPM). Refer to the following example:

private void handleBid(Ad ad, boolean win) {
    AdBid adBid = ad.getBid();
    if (adBid != null) {
        if (win) {
            adBid.notifyWin("secondPrice", "secondBidder");// monetix wins
        } else {
            adBid.notifyLoss("winPrice","winBidder", "lossReason");// monetrix loses
        }
        log("thd biddingPrce for this ad is " + adBid.getBiddingPrice());
    }
}

7.2 Win/Loss Notification

If MonetriX wins the bid, please call notifyWin() as shown below, and pass in the second-highest price and the name of the losing bidder.

void notifyWin(@Nullable Double secondPrice, @Nullable String secondBidder);
//secondPrice (ecpm)
//secondBidder bidder name of the losing bidder

If MonetriX loses the bid, please call notifyLoss() as shown below, and pass in the highest price, the winning bidder's name and the loss reason.

void notifyLoss(@Nullable Double winPrice, @Nullable String winBidder, @LossReason int lossReason);
// winPrice (ecpm)
// winBidder winning bidder's name
// lossReason loss reason。1=unknow ; 100=price is lower than floor；102=price is lower than winning bidder

8. Test IDs

In order to validate sdk integration, you can use the following test ids. Test ids are 100% fill rate

9. Error Codes