激励广告自定义事件

本指南适用于希望使用 AdMob 中介来展示 AdMob 界面不直接支持的广告联盟所提供的激励广告的发布商。

借助激励广告自定义事件,您可以编写自定义的中介适配器,从而展示第三方广告联盟提供的激励广告。在本指南中,我们将介绍如何编写自定义事件,以通过我们开发的示例 SDK 请求广告。您可以在 GitHub 上找到示例 SDK 的完整源代码。

前提条件

创建自定义事件

要定义自定义事件,必须先在 AdMob 界面中创建自定义事件。有关创建自定义事件的说明,请参阅添加自定义事件

定义自定义事件后,该自定义事件适配器会指向您的应用中某个通过实现 Adapter 界面来投放激励广告的类。此外,自定义事件还会列出传递给激励广告适配器的服务器参数。

以下屏幕截图显示的是自定义事件示例的部分设置:

该屏幕截图包含以下条目:

类名称
实现自定义事件适配器的类的完全限定名称。
标签
定义广告来源的唯一名称。
参数
传递给自定义事件适配器的可选字符串参数。

实现自定义事件

自定义事件是通过实现 Adapter 来投放第三方广告的类。下面是实现自定义事件以请求和展示示例广告联盟提供的激励广告的步骤。

报告版本号

所有自定义事件都必须向 Google 移动广告 SDK 报告自定义事件本身的版本,以及与该自定义事件对接的第三方 SDK 的版本。报告版本时使用的是 VersionInfo

...
    import com.google.android.gms.ads.AdFormat;
    import com.google.android.gms.ads.mediation.Adapter;
    import com.google.android.gms.ads.mediation.VersionInfo;
    ...

    public class SampleAdNetworkCustomEvent extends Adapter implements
        SampleAdNetworkInitCompletionListener, SampleRewardedVideoAdListener {
    ...
        @Override
        public VersionInfo getVersionInfo() {
            String versionString = SampleAdNetwork.VERSION_NAME;
            String splits[] = versionString.split("\\.");
            int major = Integer.parseInt(splits[0]);
            int minor = Integer.parseInt(splits[1]);
            int micro = Integer.parseInt(splits[2]) * 100 + Integer.parseInt(splits[3]);
            return new VersionInfo(major, minor, micro);
        }

        @Override
        public VersionInfo getSDKVersionInfo() {
            String versionString = com.SampleAdNetwork.VERSION_NAME;
            String splits[] = versionString.split("\\.");
            int major = Integer.parseInt(splits[0]);
            int minor = Integer.parseInt(splits[1]);
            int micro = Integer.parseInt(splits[2]);
            return new VersionInfo(major, minor, micro);
        }
    ...
    }
    

初始化适配器

在应用初始化 Google 移动广告 SDK 后,系统会针对在 AdMob 界面中为该应用配置的所有适配器和自定义事件调用 initialize()。自定义事件应该使用此方法为第三方广告 SDK 执行任何所需的初始化或设置操作。

MediationConfiguration 参数会提供在 AdMob 界面中为该应用配置的所有展示位置的信息。

通过在 initialize() 调用中提供的 InitializationCompleteCallback 参数上调用 onInitializationSucceededonInitializationFailed,向 Google 移动广告 SDK 报告初始化是成功还是失败。

以下代码段会对示例广告 SDK 进行初始化,使其为处理广告请求做好准备:

...
    import com.google.android.gms.ads.AdFormat;
    import com.google.android.gms.ads.mediation.Adapter;
    import com.google.android.gms.ads.mediation.InitializationCompleteCallback;
    import com.google.android.gms.ads.mediation.MediationConfiguration;
    ...

    public class SampleAdNetworkCustomEvent extends Adapter implements
        SampleAdNetworkInitCompletionListener, SampleRewardedVideoAdListener {

        private static final String SAMPLE_AD_UNIT_KEY = "parameter";

        private InitializationCompleteCallback initializationCallback;

        @Override
        public void initialize(Context context,
            InitializationCompleteCallback initializationCompleteCallback,
            List<MediationConfiguration> mediationConfigurations) {

            if (!(context instanceof Activity)) {
                // Context not an Activity context, fail the initialization.
                initializationCompleteCallback.onInitializationFailed(
                    "Sample SDK requires an Activity context to initialize");
                return;
            }

            List<String> adUnitIDs = new ArrayList<>();
            for (MediationConfiguration configuration : mediationConfigurations) {
                if (configuration.getFormat() == AdFormat.REWARDED) {
                    adUnitIDs.add(configuration.getServerParameters().getString(SAMPLE_AD_UNIT_KEY));
                }
            }

            if (adUnitIDs.isEmpty()) {
                initializationCompleteCallback.onInitializationFailed(
                    "Sample SDK requires an Activity context to initialize");
            }

            this.initializationCallback = initializationCompleteCallback;

            // Initialize the Sample SDK.
            SampleRewardedVideo.initialize((Activity) context, adUnitIDs, this);
        }

        @Override
        public void OnInitSucceeded() {
            this.initializationCallback.onInitializationSucceeded();
        }
    }
    

请求激励广告

应用发出的加载激励广告的请求会调用自定义事件的 loadRewardedAd() 方法。

通过在 loadRewardedAd() 调用中提供的 MediationAdLoadCallback 参数上调用 onSuccessonFailure,向 Google 移动广告 SDK 报告广告加载是成功还是失败。报告广告加载成功时,请引用一个符合 MediationRewardedAd 的对象。调用 onSuccess 方法会返回 MediationRewardedAdCallback。自定义事件应该保留对此对象的引用,以向 Google 移动广告 SDK 发出广告生命周期事件的通知。有关进一步详细说明,请参阅展示广告部分。

下面是 loadRewardedAd() 的实现示例:

...
    import com.google.ads.mediation.sample.sdk.SampleRewardedVideo;
    import com.google.android.gms.ads.mediation.InitializationCompleteCallback;
    import com.google.android.gms.ads.mediation.MediationAdLoadCallback;
    import com.google.android.gms.ads.mediation.MediationRewardedAd;
    import com.google.android.gms.ads.mediation.MediationRewardedAdCallback;
    ...

    public class SampleAdNetworkCustomEvent extends Adapter implements
        SampleAdNetworkInitCompletionListener, MediationRewardedAd {
        private static final String SAMPLE_AD_UNIT_KEY = "parameter";
        private InitializationCompleteCallback initializationCallback;
        private MediationRewardedAdCallback rewardedAdCallback;
    ...
        @Override
        public void loadRewardedAd(MediationRewardedAdConfiguration adConfiguration,
            MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> MediationAdLoadCallback) {
            // Gets the custom event parameter from thd ad configuration.
            String adUnit = adConfiguration.getServerParameters().getString(SAMPLE_AD_UNIT_KEY);
            if (SampleRewardedVideo.isAdAvailable()) {
                this.rewardedAdCallback = MediationAdLoadCallback.onSuccess(this);
            } else {
                MediationAdLoadCallback.onFailure("No fill.");
            }
        }
    ...
    }
    

展示广告

在收到自定义事件发出的广告已成功加载的通知后,Google 移动广告 SDK 可能会随时调用自定义事件的 showAd() 方法。调用完此方法后,适配器就应该会展示激励广告了。

...
    public class SampleAdNetworkCustomEvent extends Adapter implements
        SampleAdNetworkInitCompletionListener, MediationRewardedAd {
    ...
        private MediationRewardedAdCallback rewardedAdCallback;
    ...
        @Override
        public void showAd(Context context) {
            // Show the rewarded ad.
            if (SampleRewardedVideo.isAdAvailable()) {
                // Rewarded ad available, show ad.
                SampleRewardedVideo.showAd();
            }
        }
    ...
    }
    

报告广告事件

展示广告后,自定义事件应该使用广告成功加载时提供的 MediationRewardedAdCallback,向 Google 移动广告 SDK 报告相应的广告生命周期事件。

...
    public class SampleAdNetworkCustomEvent extends Adapter implements
        SampleAdNetworkInitCompletionListener, MediationRewardedAd {
    ...
        private MediationRewardedAdCallback rewardedAdCallback;
    ...
        @Override
        public void showAd(Context context) {
            // Show the rewarded ad.
            if (SampleRewardedVideo.isAdAvailable()) {
                // Rewarded ad available, show ad.
                SampleRewardedVideo.showAd();
            } else {
                // Report that ad cannot be shown.
                this.rewardedAdCallback.onAdFailedToShow("Ad is unavailable to show.");
            }
        }

        @Override
        public void onAdFullScreen() {
            this.rewardedAdCallback.onAdOpened();
            this.rewardedAdCallback.onVideoStart();
            this.rewardedAdCallback.reportAdImpression();
        }

        @Override
        public void onAdRewarded(final String rewardType, final int amount) {
            /*
             * AdMob requires a reward item with a reward type and
             * amount to be sent when sending the rewarded callback. If your SDK does
             * not have a reward amount you need to do the following:
             *
             * 1. AdMob provides an ability to override the
             *    reward value in the UI. Ask the publisher to override the reward
             *    value on AdMob's UI.
             * 2. Send a reward item with default values for the type (an empty string
             *    "") and reward amount (1).
             */
            this.rewardedAdCallback.onUserEarnedReward(new SampleRewardItem(rewardType,
                amount));
        }

        @Override
        public void onVideoComplete() {
            this.rewardedAdCallback.onVideoComplete();
        }

        @Override
        public void onAdClicked() {
            this.rewardedAdCallback.reportAdClicked();
        }

        @Override
        public void onAdClosed() {
            this.rewardedAdCallback.onAdClosed();
        }
    ...
    }
    

下面详细列出了必须向 Google 移动广告 SDK 报告的广告事件:

广告事件 说明
onAdOpened() 向 Google 移动广告 SDK 发出广告已打开的通知。
onAdFailedToShow() 向 Google 移动广告 SDK 发出激励广告无法展示的通知。
onVideoStart() 向 Google 移动广告 SDK 发出激励广告开始播放的通知。
reportAdImpression() 向 Google 移动广告 SDK 发出广告展示了一次的通知。
onVideoComplete() 向 Google 移动广告 SDK 发出激励广告已播放完毕的通知。
onUserEarnedReward() 向 Google 移动广告 SDK 发出用户已获得奖励的通知。
reportAdClicked() 向 Google 移动广告 SDK 发出用户已点击广告的通知。
onAdClosed() 向 Google 移动广告 SDK 发出广告已关闭的通知。