Rewarded Ads

所谓激励广告,指的是用户可以选择与之互动来换取应用内奖励的一种广告。本指南介绍了如何将 Ad Manager 激励广告植入到 Android 应用中。

If you'd like to get an idea of how rewarded ads work, take a look at the demo below. This demo shows the flow of rewarded video ads integrated in to a simple game.

前提条件

  • Google 移动广告 SDK 17.2.0 或更高版本。
  • 按照入门指南导入 Google 移动广告 SDK 并更新您的 Android 清单。

创建激励广告对象

激励广告由 RewardedAd 对象请求和展示。第一步是将 RewardedAd 实例化。这可在以下代码段中 ActivityonCreate() 方法中完成:

Java

import com.google.android.gms.ads.rewarded.RewardedAd;

public class MainActivity extends Activity {

    private RewardedAd rewardedAd;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...
        rewardedAd = new RewardedAd(this,
            "/6499/example/rewarded-video");
    }

}

Kotlin

import com.google.android.gms.ads.rewarded.RewardedAd

class MainActivity : Activity() {

  private lateinit var rewardedAd: RewardedAd

  override fun onCreate(savedInstanceState:Bundle) {
    ...
    rewardedAd = RewardedAd(this,
        "/6499/example/rewarded-video")
  }
}

构造函数需要以下参数:

务必用测试广告进行测试

在构建和测试应用时,请确保使用的是测试广告,而不是实际投放的广告。否则,可能会导致您的帐号被暂停。

对于 Android 激励广告,加载测试广告最简便的方法就是使用下面的专用测试广告单元 ID:

/6499/example/rewarded-video

该测试广告单元 ID 已经过专门配置,可为每个请求返回测试广告,您可以在自己应用的编码、测试和调试过程中随意使用该测试广告单元 ID。只需确保您会在发布应用前用自己的广告单元 ID 替换该测试广告单元 ID 即可。

如需详细了解移动广告 SDK 的测试广告如何运作,请参阅测试广告

加载广告

要加载激励广告,请调用 RewardedAd 对象的 loadAd() 方法。此方法需要将 PublisherAdRequestRewardedAdLoadCallback 的实例作为参数。

Java

import com.google.android.gms.ads.rewarded.RewardedAd;

public class MainActivity extends Activity {

    private RewardedAd rewardedAd;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...
        rewardedAd = new RewardedAd(this,
            "/6499/example/rewarded-video");

        RewardedAdLoadCallback adLoadCallback = new RewardedAdLoadCallback() {
            @Override
            public void onRewardedAdLoaded() {
                // Ad successfully loaded.
            }

           @Override
            public void onRewardedAdFailedToLoad(LoadAdError adError) {
                // Ad failed to load.
            }
        };
        rewardedAd.loadAd(new PublisherAdRequest.Builder().build(), adLoadCallback);
    }
}

Kotlin

import com.google.android.gms.ads.rewarded.RewardedAd

class MainActivity : Activity() {

  private val rewardedAd: RewardedAd

  override fun onCreate(savedInstanceState:Bundle) {
    rewardedAd = RewardedAd(this, "/6499/example/rewarded-video")
    val adLoadCallback = object: RewardedAdLoadCallback() {
      fun onRewardedAdLoaded() {
        // Ad successfully loaded.
      }
      fun onRewardedAdFailedToLoad(adError: LoadAdError) {
        // Ad failed to load.
      }
    }
    rewardedAd.loadAd(PublisherAdRequest.Builder().build(), adLoadCallback)
  }
}

RewardedAdLoadCallbackonRewardedAdLoaded()onRewardedAdFailedToLoad() 方法提供的是广告加载操作的结果。

可替换的方法
onRewardedAdLoaded() 广告加载完成时,系统会执行此方法。
onRewardedAdFailedToLoad() 广告加载失败时,系统会调用此方法。它包含一个 LoadAdError 类型的错误参数,以指明发生了何种类型的失败。如需了解详情,请参阅“调试广告加载错误”文档

展示广告

在向用户展示激励广告之前,必须为用户提供明确的选项,让用户可以自行选择是否通过观看激励广告内容来换取奖励。激励广告必须始终是一项可选择接受的体验。

要展示 RewardedAd,请使用 isLoaded() 方法验证广告是否已完成加载,然后调用 show()show() 方法需要将 ActivityRewardedAdCallback 实例作为参数。Activity 实例应该是在其中展示激励广告的活动。

上一个代码示例中的激励广告可以在按钮的 OnClickListener 中展示,如下所示:

Java

myButton.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        if (rewardedAd.isLoaded()) {
            Activity activityContext = MainActivity.this
            RewardedAdCallback adCallback = new RewardedAdCallback() {
                @Override
                public void onRewardedAdOpened() {
                    // Ad opened.
                }

                @Override
                public void onRewardedAdClosed() {
                    // Ad closed.
                }

                @Override
                public void onUserEarnedReward(@NonNull RewardItem reward) {
                    // User earned reward.
                }

                @Override
                public void onRewardedAdFailedToShow(AdError adError) {
                    // Ad failed to display.
                }
            };
            rewardedAd.show(activityContext, adCallback);
        } else {
            Log.d("TAG", "The rewarded ad wasn't loaded yet.");
        }
    }
});

Kotlin

myButton.setOnClickListener {
  if (rewardedAd.isLoaded) {
    val activityContext: Activity = this@MainActivity
    val adCallback = object: RewardedAdCallback() {
      override fun onRewardedAdOpened() {
        // Ad opened.
      }
      override fun onRewardedAdClosed() {
        // Ad closed.
      }
      override fun onUserEarnedReward(@NonNull reward: RewardItem) {
        // User earned reward.
      }
      override fun onRewardedAdFailedToShow(adError: AdError) {
        // Ad failed to display.
      }
    }
    rewardedAd.show(activityContext, adCallback)
  }
  else {
    Log.d("TAG", "The rewarded ad wasn't loaded yet.")
  }
}

接收广告事件通知

提供给 show() 方法的 RewardedAdCallback 用于接收激励广告事件的通知。RewardedAdCallback 中每个可替换的方法均对应激励广告生命周期内的一个事件。例如,如果要向用户提供他们应获得的奖励,则非常适合使用 onUserEarnedReward() 方法。下面提供了有关每个广告事件方法的其他详细信息。

可替换的方法
onRewardedAdOpened() 在广告开始展示并铺满设备屏幕时,系统会调用此方法。
onRewardedAdClosed() 在用户点按“关闭”图标或使用“返回”按钮关闭激励广告时,系统会调用此方法。如果您的应用暂停了音频输出或游戏循环,则非常适合使用此方法恢复这些活动。
onUserEarnedReward() 在用户因与广告互动而应获得奖励时,系统会调用此方法。您可通过 RewardItem 参数的 getType()getAmount() 方法访问为广告单元配置的奖励详细信息。
onRewardedAdFailedToShow() 广告显示失败时,系统会调用此方法。此方法包含一个 adError 参数,该参数会指明发生了何种类型的失败。错误代码 (adError.getCode()) 的可能值在 RewardedAdCallback 类中以常量的形式指定。

使用 RewardedAdCallback 预加载下一个激励广告

RewardedAd 是一次性对象。这意味着,在展示激励广告后,就不能再用该对象加载另一个广告了。要请求另一个激励广告,您需要创建新的 RewardedAd 对象。

最佳做法是在 RewardedAdCallback 上的 onRewardedAdClosed() 方法中加载另一个激励广告,以便在上一个激励广告关闭后,立即开始加载下一个激励广告:

Java

public RewardedAd createAndLoadRewardedAd() {
        RewardedAd rewardedAd = new RewardedAd(this,
                "/6499/example/rewarded-video");
        RewardedAdLoadCallback adLoadCallback = new RewardedAdLoadCallback() {
            @Override
            public void onRewardedAdLoaded() {
                // Ad successfully loaded.
            }

            @Override
            public void onRewardedAdFailedToLoad(LoadAdError adError) {
                // Ad failed to load.
            }
        };
        rewardedAd.loadAd(new PublisherAdRequest.Builder().build(), adLoadCallback);
        return rewardedAd;
}

@Override
public void onRewardedAdClosed() {
    this.rewardedAd = createAndLoadRewardedAd();
}

Kotlin

fun createAndLoadRewardedAd(): RewardedAd {
  val rewardedAd = RewardedAd(this, "/6499/example/rewarded-video")
  val adLoadCallback = object: RewardedAdLoadCallback() {
    override fun onRewardedAdLoaded() {
      // Ad successfully loaded.
    }
    override fun onRewardedAdFailedToLoad(adError: LoadAdError) {
      // Ad failed to load.
    }
  }
  rewardedAd.loadAd(PublisherAdRequest.Builder().build(), adLoadCallback)
  return rewardedAd
}
fun onRewardedAdClosed() {
  this.rewardedAd = createAndLoadRewardedAd()
}

加载多个激励广告

要加载多个激励广告,请针对您要加载的每个广告,按照创建激励广告对象加载广告部分中所述的步骤操作。下面的代码段展示了如何为两个不同的广告展示位置加载两个激励广告。

Java

package ...

import com.google.android.gms.ads.PublisherAdRequest;
import com.google.android.gms.ads.rewarded.RewardedAd;

public class MainActivity extends Activity {

    private RewardedAd gameOverRewardedAd;
    private RewardedAd extraCoinsRewardedAd;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...
        gameOverRewardedAd = createAndLoadRewardedAd(
          "/6499/example/rewarded-video");
        extraCoinsRewardedAd = createAndLoadRewardedAd(
          "/6499/example/rewarded-video");
    }

    public RewardedAd createAndLoadRewardedAd(String adUnitId) {
        RewardedAd rewardedAd = new RewardedAd(this, adUnitId);
        RewardedAdLoadCallback adLoadCallback = new RewardedAdLoadCallback() {
            @Override
            public void onRewardedAdLoaded() {
                // Ad successfully loaded.
            }

            @Override
            public void onRewardedAdFailedToLoad(LoadAdError adError) {
                // Ad failed to load.
            }
        };
        rewardedAd.loadAd(new PublisherAdRequest.Builder().build(), adLoadCallback);
        return rewardedAd;
    }
}

Kotlin

import com.google.android.gms.ads.PublisherAdRequest
import com.google.android.gms.ads.rewarded.RewardedAd

class MainActivity: Activity() {

  private val gameOverRewardedAd:RewardedAd
  private val extraCoinsRewardedAd:RewardedAd

  override fun onCreate(savedInstanceState:Bundle) {
    ...
    gameOverRewardedAd = createAndLoadRewardedAd(
      "/6499/example/rewarded-video")
    extraCoinsRewardedAd = createAndLoadRewardedAd(
      "/6499/example/rewarded-video")
  }

  fun createAndLoadRewardedAd(adUnitId:String): RewardedAd {
    val rewardedAd = RewardedAd(this, adUnitId)
    val adLoadCallback = object: RewardedAdLoadCallback() {
      overrride fun onRewardedAdLoaded() {
        // Ad successfully loaded.
      }
      overrride fun onRewardedAdFailedToLoad(adError: LoadAdError) {
        // Ad failed to load.
      }
    }
    rewardedAd.loadAd(PublisherAdRequest.Builder().build(), adLoadCallback)
    return rewardedAd
  }
}

后续步骤