Rewarded ads integration for Android
Integrate the LevelPlay SDK's Rewarded ad unit by implementing LevelPlayRewardedAdListener, initializing and checking ad availability, showing ads with placements, rewarding users on completion, and verifying setup with the LevelPlay Integration Helper.
読み終わるまでの所要時間 7 分最終更新 1日前
The Unity LevelPlay Rewarded is a full-screen ad unit, usually served at natural transition points during the app lifecycle.
注
This documentation is relevant for SDK 8.5.0+.
Prerequisites
- Ensure that you have correctly integrated the LevelPlay SDK into your application. Integration is outlined here.
- Ensure that you initialize the SDK using LevelPlay Initialization API.
- Find the AdUnitID in LevelPlay dashboard.
Create Rewarded Ad Object
The creation of the Rewarded ad object must be performed after receiving the onInitSuccess callback. The object is a reusable instance that can handle multiple loads and shows throughout the session. After creation, it should be used to load and show ads for the same ad unit. For more advanced implementations, you may create multiple Rewarded ad objects if necessary.LevelPlayRewardedAd mRewardedAd = new LevelPlayRewardedAd("adUnitId");
Set Rewarded Listener
Implement the LevelPlayRewardedAdListener in your code to get informed of ad delivery.- It is recommended to set the listener before loading the Rewarded ad.
- Each Rewarded ad should have its own listener implementation.
- Callbacks run on the main thread.
// Create the Rewarded ad objectLevelPlayRewardedAd mRewardedAd = new LevelPlayRewardedAd("adUnitId");mRewardedAd.setListener(new LevelPlayRewardedAdListener() {@Overridepublic void onAdLoaded(LevelPlayAdInfo levelPlayAdInfo) { // Ad was loaded successfully}@Overridepublic void onAdLoadFailed(LevelPlayAdError levelPlayAdError) { // Ad load failed }@Overridepublic void onAdDisplayed(LevelPlayAdInfo levelPlayAdInfo) { // Ad was displayed and visible on screen}@Override public void onAdRewarded(@NonNull LevelPlayReward reward, @NonNull LevelPlayAdInfo adInfo) { // Ad reward received }@Overridepublic void onAdDisplayFailed(LevelPlayAdError levelPlayAdError, LevelPlayAdInfo levelPlayAdInfo) { // Ad fails to be displayed // Optional}@Overridepublic void onAdClicked(LevelPlayAdInfo levelPlayAdInfo) { // Ad was clicked // Optional}@Overridepublic void onAdClosed(LevelPlayAdInfo levelPlayAdInfo) { // Ad was closed // Optional}@Overridepublic void onAdInfoChanged(LevelPlayAdInfo levelPlayAdInfo) { // Called after the ad info is updated. Available when another Rewarded ad has loaded, and includes a higher CPM/Rate // Optional}});
LevelPlay Ad Info
The LevelPlayAdInfo parameter includes information about the loaded ad.Get Rewarded ad details
Use the getReward API to access reward data that you've set up in your LevelPlay dashboard. Unlike other mediation APIs, this is an independent call that returns data stored locally in the SDK after initialization. This enables you to build dynamic, data-driven UIs that inform users of potential rewards before they engage with an ad, eliminating the need to hardcode reward values in your app.Prerequisites
Before implementing the getReward API, ensure your project meets these technical requirements:- SDK Initialization: Call initSDK and wait for the onInitializationSuccess callback to ensure the reward data has been cached.
- Ad Object Instance: Instantiate a Rewarded Ad object with a valid Ad Unit ID before calling the API.
- Minimum SDK Version: Use LevelPlay SDK version 8.1.0 or higher (Native or Unity package).
Best practices
Follow these recommendations to ensure a stable and predictable integration.- Call on initialization success: The best time to call getReward is immediately inside your initialization success listener. This ensures your UI is ready the moment the user enters a screen.
- Check for empty states: Always validate that amount > 0 before you update your UI. This ensures a smooth user experience if a network error occurs during initialization.
- Placement precision: Ensure the string used in getReward("placementName") exactly matches the name defined in the LevelPlay dashboard.
API structure
The getReward method lets you access synchronized reward data from the LevelPlay dashboard. Use this method to query the local SDK cache for specific placement values or global ad unit defaults.getReward
Retrieves the reward name and amount for a specific placement or the default ad unit. There are no other parameters to use.public LevelPlayReward getReward(String placementName)
Parameter | Description |
|---|---|
| placementName | The unique identifier for the placement as defined in the LevelPlay dashboard. Pass |
Initial setup
The getReward API functions as a core component of the LevelPlay SDK, operating under the following logic to ensure data is available without latency:- Integrated feature: Because the reward data is retrieved during the initial SDK setup, the API call is instantaneous and doesn't require a network request.
- Editor configuration: After your app is integrated with the LevelPlay SDK, the API is available for use immediately. No additional assets or plugins are required to test this functionality.
Understand reward selection logic
The API returns a LevelPlayReward object based on a specific hierarchy. Understanding this logic helps you troubleshoot why a specific reward is appearing.- Placement level: If a valid placement name is provided in the call, the SDK returns the specific reward configured for that placement in the dashboard.
- Ad Unit level: If the placement name is null or not found, the SDK falls back to the default reward defined for the Ad Unit.
- Fallback state: If the API is called before initialization is complete, it returns a reward object with an empty string name and an amount of 0.
Update your UI dynamically
Use the getReward API to transform static buttons into high-intent calls to action. For example: instead of a generic "Watch Video" button, you can display "Watch to earn 50 Gold."- Validate amount: Always verify that reward.amount > 0 before updating your UI components.
- Event-Driven updates: Call the API inside your initialization success listener to ensure the UI is accurate the moment a user enters a screen.
- Case sensitivity: Ensure the placement name string in your code matches the LevelPlay dashboard exactly; mismatched strings will trigger the Ad Unit fallback.
Retrieve reward data examples
The following examples show how to call the reward API for Android:/** * Retrieves the reward associated with the ad. * Use this method to obtain the reward configured for the ad unit or placement. The * placement-specific reward takes precedence over the ad unit reward when a valid placement name * is provided. * @param placement The placement name to retrieve the reward for, or `null` to use the ad unit's reward. * @return A [LevelPlayReward] object. Returns an empty reward on failures (`name: ""` and `amount: 0`). */ @JvmOverloads fun getReward(placement: String? = null): LevelPlayReward { val reward = mRewardedAd.getReward(placement) Log.d("LevelPlay", "Amount: ${reward.amount}, Name: ${reward.name}") return reward}
Troubleshooting getReward API implementation
- Reward amount returns 0: This usually occurs if the API is called before the onInitializationSuccess callback. Ensure the SDK is fully ready before querying rewards.
- Wrong reward type shown: Check if you have multiple placements. If the placement name is misspelled, the SDK will default to the primary ad unit reward instead of the specific placement reward.
Load Rewarded Ad
To load a Rewarded ad use loadAd.mRewardedAd.loadAd();
Show Rewarded Ad
Show an Rewarded ad after you receive the onAdLoaded callback using the LevelPlayRewardedAdListener APIs.- It is required to share Activity.
- If using placements, pass the placement name in the showAd API as shown in the Placements section below.
- After the ad has been successfully displayed to the user, you can load another ad by repeating the loading step.
public void showRewardedAd() {// Check that ad is readyif (mRewardedAd.isAdReady()) { // Show ad mRewardedAd.showAd(this);}}
Check Ad is Ready
To avoid show failures, and to make sure the ad could be displayed correctly, we recommend using the following API before calling the showAd API. isAdReady – returns true if ad was loaded successfully and ad unit is not capped, or false otherwise. isPlacementCapped – returns true when a valid placement is capped. If the placement is not valid, or not capped, this API will return false.// Check that ad is ready and that the placement is not capped if (mRewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped(placementName)) {mRewardedAd.showAd(this, placementName);}
Placements
We support placements pacing and capping for Rewarded on the LevelPlay dashboard. If placements are set up for Rewarded ads, call the showAd method to serve the ad for a specific placement.public void showRewardedAdWithPlacement() { // Check that ad is ready and that the placement is not capped if (mRewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped(placementName)) { // Show ad with placement mRewardedAd.showAd(this, placementName);}}
Dynamic UserId
The Dynamic UserID is a parameter used to verify AdRewarded transactions that you can change throughout the session. You will receive this parameter through the server-to-server ad rewarded callbacks, and you must set it before calling showAd.- The string value must be comprised of 1-64 alphanumeric characters.
- You will receive a parameter in the callback URL with the reward details.
dynamicUserId
LevelPlay.setDynamicUserId("userId");
public class RewardedAdActivity extends Activity implements LevelPlayRewardedAdListener {private LevelPlayRewardedAd mRewardedAd;void createRewardedAd() { mRewardedAd = new LevelPlayRewardedAd("adUnitId"); mRewardedAd.setListener(this);}void loadRewardedAd() { // Load or reload the ad mRewardedAd.loadAd();}void showRewardedAd() { if(mRewardedAd.isAdReady()) { mRewardedAd.showAd(this); }}void showRewardedAd(@NonNull String placementName) { // Check that ad is ready and that the placement is not capped if(mRewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped(placementName)) { mRewardedAd.showAd(this, placementName); }}// LevelPlayRewardedAdListener methods@Overridepublic void onAdLoaded(@NonNull LevelPlayAdInfo adInfo) {}@Overridepublic void onAdLoadFailed(@NonNull LevelPlayAdError error) {}@Overridepublic void onAdDisplayed(@NonNull LevelPlayAdInfo adInfo) {}@Overridepublic void onAdClosed(@NonNull LevelPlayAdInfo adInfo) {}@Overridepublic void onAdClicked(@NonNull LevelPlayAdInfo adInfo) {}@Overridepublic void onAdDisplayFailed(@NonNull LevelPlayAdError error, @NonNull LevelPlayAdInfo adInfo) {}@Overridepublic void onAdInfoChanged(@NonNull LevelPlayAdInfo adInfo) {}@Overridepublic void onAdRewarded(@NonNull LevelPlayReward reward, @NonNull LevelPlayAdInfo adInfo) {}}