Documentation

Support

Unity LevelPlay

Get started with LevelPlay

SDK integration

LevelPlay platform

Unity LevelPlay

Rewarded ads integration for Unity Package

Integrate the Rewarded Video ad unit by initializing the SDK, creating ad objects post-initialization, and implementing listeners to handle ad events, enhancing user engagement through in-app rewards.
Read time 6 minutesLast updated a day ago
The Unity LevelPlay Rewarded Ad is a user-initiated ad unit that offers users the opportunity to engage with full-screen ads in exchange for in-app rewards, enhancing engagement while maintaining a positive user experience.

Prerequisites

  • Ensure that you have correctly integrated the LevelPlay Unity package 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. Once created, 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. You can create the ad object by calling: 
// Create Rewarded Ad object LevelPlayRewardedAd rewardedAd = new LevelPlayRewardedAd(rewardedAdUnitId);

Creating with a Price Floor

To set an optional Price Floor for your ad requests, pass it via the 
Config
object when creating the 
LevelPlayRewardedAd
(more information here): 
// Create Rewarded Ad object with Price Floor in config.var configBuilder = new LevelPlayRewardedAd.Config.Builder();configBuilder.SetBidFloor(1.0); // Minimum bid price in USDvar rvConfig = configBuilder.Build();LevelPlayRewardedAd RewardedAd = new LevelPlayRewardedAd(RewardedAdUnitId, rvConfig);

Register to Rewarded Events

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.
// Register to Rewarded eventsRewardedAd.OnAdLoaded += RewardedOnAdLoadedEvent;RewardedAd.OnAdLoadFailed += RewardedOnAdLoadFailedEvent;RewardedAd.OnAdDisplayed += RewardedOnAdDisplayedEvent;RewardedAd.OnAdDisplayFailed += RewardedOnAdDisplayFailedEvent;RewardedAd.OnAdRewarded += RewardedOnAdRewardedEvent;RewardedAd.OnAdClosed += RewardedOnAdClosedEvent;// OptionalRewardedAd.OnAdClicked += RewardedOnAdClickedEvent;RewardedAd.OnAdInfoChanged += RewardedOnAdInfoChangedEvent;// Implement the eventsvoid RewardedOnAdLoadedEvent(LevelPlayAdInfo adInfo) {}void RewardedOnAdLoadFailedEvent(LevelPlayAdError error) {}void RewardedOnAdDisplayedEvent(LevelPlayAdInfo adInfo) {}void RewardedOnAdDisplayFailedEvent(LevelPlayAdInfo adInfo, LevelPlayAdError error) {}void RewardedOnAdRewardedEvent(LevelPlayReward adReward, LevelPlayAdInfo adInfo) {}void RewardedOnAdClosedEvent(LevelPlayAdInfo adInfo) {}void RewardedOnAdClickedEvent(LevelPlayAdInfo adInfo) {}void RewardedOnAdInfoChangedEvent(LevelPlayAdInfo adInfo) {}

LevelPlay Ad Info

The LevelPlayAdInfo parameter includes information about the loaded ad. Learn more about its implementation and available fields here.

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

public LevelPlayReward getReward(String placementName)
Retrieves the reward name and amount for a specific placement or the default ad unit. There are no other parameters to use.

Parameter

Description

placementNameThe unique identifier for the placement as defined in the LevelPlay dashboard. Pass 
null
to retrieve the default reward for the ad unit.
Returns a LevelPlayReward object containing the name (String) and amount (int).

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 example shows how to call the reward API for Unity: 
/// <summary> /// 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. /// </summary> /// <param name="placement">The placement name to retrieve the reward for, or null to use the ad unit's reward.</param> /// <returns>A <see cref="LevelPlayReward"/> object. Returns an empty reward on failures (name: "" and amount: 0).</returns> LevelPlayReward reward = rewardedAd.getReward("battle_screen");// Update UI dynamicallyif (reward.Amount > 0 && !string.IsNullOrEmpty(reward.Name)) {    rewardButton.text = $"Click to get {reward.Amount} {reward.Name}";} else {    rewardButton.text = "Watch for Rewards";}

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. 
// Load rewarded adRewardedAd.LoadAd();

Show Rewarded Ad

Show a rewarded ad after you receive the OnAdLoaded callback using the LevelPlayRewardedAdListener APIs.
  • If using placements, pass the placement name in the ShowAd API as shown in the Placements section below.
  • Once the ad has been successfully displayed to the user, you can load another ad by repeating the loading step.
// Show ad without placementRewardedAd.ShowAd();// Show ad with placementRewardedAd.ShowAd(placementName: "placementName");

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 cappedif (RewardedAd.IsAdReady() && !LevelPlayRewardedAd.IsPlacementCapped(placementName)){    RewardedAd.ShowAd(placementName);}

Placements

We support placements pacing and capping for rewarded ad on the LevelPlay dashboard. If placements are set up for rewarded ads, call the ShowAd method to serve the ad for a specific placement. 
// Check that ad is ready and that the placement is not cappedif (RewardedAd.IsAdReady() && !LevelPlayRewardedAd.IsPlacementCapped(placementName)){    RewardedAd.ShowAd(placementName);}

Reward the User

The LevelPlay SDK will fire the OnAdRewarded each time the user successfully completes a video. The OnAdRewarded and OnAdClosed are asynchronous. Make sure to set up your listener to grant rewards even in cases where OnAdRewarded is fired after the OnAdClosed. 
// Subscribe to the OnAdRewarded eventRewardedAd.OnAdRewarded += (adReward, adInfo) =>{    // Grant the reward to the user    Debug.Log($"Ad Completed: {adInfo.PlacementName}, Reward: {adReward.Name} - {adReward.Amount}");    GrantReward(adReward.Name, adReward.Amount);};// Example method to process the rewardprivate void GrantReward(string rewardName, int rewardAmount){    // TODO: Implement logic to grant the reward to the user    Debug.Log($"Granting reward: {rewardName} with amount: {rewardAmount}");}

Full Implementation Example of Rewarded Ads

public class RewardedAdSample {    private LevelPlayRewardedAd RewardedAd;    void CreateRewardedAd() {        // Create RewardedAd instance        RewardedAd = new LevelPlayRewardedAd("RewardedAdUnitId");        // Subscribe RewardedAd events        RewardedAd.OnAdLoaded += RewardedOnAdLoadedEvent;        RewardedAd.OnAdLoadFailed += RewardedOnAdLoadFailedEvent;        RewardedAd.OnAdDisplayed += RewardedOnAdDisplayedEvent;        RewardedAd.OnAdDisplayFailed += RewardedOnAdDisplayFailedEvent;        RewardedAd.OnAdClicked += RewardedOnAdClickedEvent;        RewardedAd.OnAdClosed += RewardedOnAdClosedEvent;        RewardedAd.OnAdRewarded += RewardedOnAdRewardedEvent;        RewardedAd.OnAdInfoChanged += RewardedOnAdInfoChangedEvent;    }    void LoadRewardedAd() {        // Load or reload RewardedAd        RewardedAd.LoadAd();    }    void ShowRewardedAd() {        // Show RewardedAd, check if the ad is ready before showing        if (RewardedAd.IsAdReady()) {            RewardedAd.ShowAd();        }    }    // Implement RewardedAd events    void RewardedOnAdLoadedEvent(LevelPlayAdInfo adInfo) { }    void RewardedOnAdLoadFailedEvent(LevelPlayAdError error) { }    void RewardedOnAdClickedEvent(LevelPlayAdInfo adInfo) { }    void RewardedOnAdDisplayedEvent(LevelPlayAdInfo adInfo) { }    void RewardedOnAdDisplayFailedEvent(LevelPlayAdInfo adInfo, LevelPlayAdError error) { }    void RewardedOnAdClosedEvent(LevelPlayAdInfo adInfo) { }    void RewardedOnAdRewardedEvent(LevelPlayReward adReward, LevelPlayAdInfo adInfo) { }    void RewardedOnAdInfoChangedEvent(LevelPlayAdInfo adInfo) { }}

LevelPlay Mediation Demo App

The Integration Demo application demonstrates how to integrate rewarded Ad Unit APIs in your app. Download Unity Demo Application Verify your integration with our Integration Test Suite.

Next steps

Follow our integration guides to integrate additional Rewarded Ad networks or configure additional ad formats: