Add rewarded-product-specific features

One method of unlocking in-app products and benefits for your users is to create rewarded products, or items that users receive after they watch a video advertisement. By providing rewarded products, you allow users to obtain in-app rewards and benefits without them having to make direct purchases.

This document explains how to implement functionality specific to rewarded products. The workflow diagram section of this page illustrates the process.

Identify your app's rewarded products

Rewarded products have a SkuType of INAPP. To ensure users are able to watch multiple ads and get multiple rewards, the products need to be consumed.

Before you can offer a rewarded product to a user, you must obtain the SkuDetails for the product. To do this, call querySkuDetailsAsync() with SkuType.INAPP as the product type.

Declare age-appropriate ads

To help facilitate compliance with legal obligations related to children and to underage users, including the Children's Online Privacy Protection Act (COPPA) and the General Data Protection Regulation (GDPR), your app should declare which ads should be treated as child-directed in the United States and which ads are directed at users who are under the applicable age of consent in their country. The AdMob Help Center explains when you should tag your ad requests for child-directed treatment and when you should tag them for under-the-age-of-consent treatment, as well as the effects of doing so.

As you create your app's billing client, consider whether the rewarded ad requests should be treated as child-directed or whether they should be directed at users who are under the age of consent. If the ad requests should have these restrictions in place, call the setChildDirected() and setUnderAgeOfConsent() methods, passing appropriate values into each method.

The following code snippet shows how to declare that video ads should be suitable for children or for users who are under the age of consent:

val billingClient = BillingClient.newBuilder(context)
        .setListener(this)
        .setChildDirected(ChildDirected.CHILD_DIRECTED)
        .setUnderAgeOfConsent(UnderAgeOfConsent.UNDER_AGE_OF_CONSENT)
        .build()

BillingClient billingClient =
    BillingClient.newBuilder(context)
        .setListener(this)
        .setChildDirected(ChildDirected.CHILD_DIRECTED)
        .setUnderAgeOfConsent(UnderAgeOfConsent.UNDER_AGE_OF_CONSENT)
        .build();

Load video ads

Before showing your user an option to watch a video ad in order to receive a rewarded product, you need to load the video. To do so, create a RewardLoadParams object, associating it with the SkuDetails object that represents the rewarded product. Then, call your billing client's loadRewardedSku() method, passing in the RewardLoadParams object and a RewardResponseListener object.

The RewardResponseListener listener is notified when the video has finished loading. The listener is also notified if the video is unavailable or if another error, such as a server timeout, occurs.

To maintain device performance when loading the videos associated with your app's rewarded products, keep the following best practices in mind:

• Load at most three rewarded product SKUs at a time.
• Attempt to load the videos whenever the user enters your app. This step helps you check whether the videos are still loaded and available.

• When deciding when to load the videos, choose the balance between bandwidth usage and app responsiveness that works best for your use case:

  • At the earliest, load the videos after you call getSkuDetails() for the associated rewarded product. Your app remains very responsive, but you might waste network data loading a video that the user never watches.
  • At the latest, load the video when the user navigates to the page where the video is to be displayed. Your app rarely wastes bandwidth in this case, but the user might have to wait a few moments before the button for watching the video becomes clickable.

The following code snippet demonstrates the process for loading a video ad that plays before the user receives the rewarded product:

if (skuDetails.isRewarded()) {
    val params = RewardLoadParams.Builder()
            .setSkuDetails(skuDetails)
            .build()
    mBillingClient.loadRewardedSku(params.build(),
            object : RewardResponseListener {
        override fun onRewardResponse(@BillingResponse responseCode : Int) {
            if (responseCode == BillingResponse.OK) {
                // Enable the reward product, or make
                // any necessary updates to the UI.
            }
        }
    })
}

if (skuDetails.isRewarded()) {
    RewardLoadParams.Builder params = RewardLoadParams.newBuilder();
    params.setSkuDetails(skuDetails);
    mBillingClient.loadRewardedSku(params.build(),
        new RewardResponseListener() {
            @Override
            public void onRewardResponse(int responseCode) {
                if (responseCode == BillingResponse.OK) {
                      // Enable the reward product, or make
                      // any necessary updates to the UI.
                  }
            }
        });
}

Give rewarded purchases to users

If the Google Play Billing Library successfully loads the video associated with a rewarded product—that is, if the RewardResponseListener receives a responseCode of BillingResponse.OK—you can launch the billing flow.

You start playing ads for a rewarded product by calling launchBillingFlow(), as you do for all other types of in-app products. Even though the user isn't making a direct purchase to receive a rewarded product, you still need to enable the billing flow so that the user is able to obtain and use the product.

Consume the purchase

To notify your billing client that a user has received and consumed a rewarded product, handle the purchase in your billing client listener's onPurchasesUpdated() method. Note that rewarded purchases need to be consumed.

Test your rewarded products

To test how your app loads video ads and provides users with rewarded products, make use of licensed testers, who by default get test ads instead of real ones. To learn how to set up accounts for these testers, see User-test a Google Play Billing app.

Another method of testing is for you to use the android.test.reward product ID. This specific product is a reserved name in Google Play Billing, so you don't need to add it to your list of in-app products in the Play Console.

Diagram of rewarded product workflow

The following sequence diagram shows how the user, your app, and the Google Play Billing Library work together to show a video ad and grant the user access to a rewarded product: