Documentation

Support

Unity LevelPlay

Get started with LevelPlay

SDK integration

LevelPlay platform

Unity LevelPlay

Rewarded ads integration for iOS

Implement the Rewarded Video ad unit in your iOS app by initializing the ad unit, setting delegates, and handling ad events.
Read time 6 minutesLast updated a day ago
The Unity LevelPlay Rewarded is a full-screen ad unit, usually served at natural transition points during the app lifecycle. 

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 can create multiple Rewarded ad objects if necessary. 
self.rewardedAd = [[LPMRewardedAd alloc] initWithAdUnitId:@"adUnitId"];

Implement Delegates

Implement the LPMRewardedAdDelegate in your code to get informed of ad delivery. 
  • It is recommended to set the delegate before loading the Rewarded ad.
  • Each Rewarded ad should have its own delegate implementation.
  • Delegate methods run on the main thread.
self.rewardedAd = [[LPMRewardedAd alloc] initWithAdUnitId:@"adUnitId"]; self.rewardedAd.delegate = self;#pragma mark - LPMRewardedAdDelegate Methods- (void)didLoadAdWithAdInfo:(LPMAdInfo *)adInfo {}- (void)didFailToLoadAdWithAdUnitId:(NSString *)adUnitId error:(NSError *)error {}- (void)didChangeAdInfo:(LPMAdInfo *)adInfo {}- (void)didDisplayAdWithAdInfo:(LPMAdInfo *)adInfo {}- (void)didFailToDisplayAdWithAdInfo:(LPMAdInfo *)adInfo error:(NSError *)error {}- (void)didClickAdWithAdInfo:(LPMAdInfo *)adInfo {}- (void)didCloseAdWithAdInfo:(LPMAdInfo *)adInfo {}- (void)didRewardAdWithAdInfo:(LPMAdInfo *)adInfo reward:(LPMReward *)reward {}

LevelPlay Ad Info

The LPMAdInfo 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

- (LPMReward *)getRewardWithPlacementName:(NSString *)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 
nil
to retrieve the default reward for the ad unit.
Returns a LPMReward 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 LPMReward 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 nil 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 iOS: 
/**  * 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 `nil` to use the ad unit's reward.  * @return A `LPMReward` object. Returns an empty reward on failures (`name: ""` and `amount: 0`).  */ LPMReward *reward = [self.rewardedAd getRewardWithPlacementName:@"main_menu"];NSLog(@"Reward: %ld %@", (long)reward.amount, reward.name);

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. 
[self.rewardedAd loadAd];

Show Rewarded Ad

Show a Rewarded ad after you receive the didLoadAd callback.
  • It is required to share ViewController. 
  • 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. 
- (void)showRewardedAd {// Check that ad is readyif ([self.rewardedAd isAdReady]) {    // Show without placement    [self.rewardedAd showAdWithViewController:self placementName:NULL];  }}

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 ([self.rewardedAd isAdReady] && ![LPMRewardedAd isPlacementCapped:placementName]) {[self.rewardedAd showAdWithViewController:self placementName: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. 
// Check that ad is ready and that the placement is not cappedif ([self.rewardedAd isAdReady] && ![LPMRewardedAd isPlacementCapped:placementName]) {// Show ad with placement[self.rewardedAd showAdWithViewController:self placementName:@"PlacementName"];}

Reward the User

The LevelPlay SDK will fire the didRewardAd each time the user successfully completes a video. The didRewardAd and didCloseAd are asynchronous. Make sure to set up your listener to grant rewards even in cases where didRewardAd is fired after the didCloseAd. 
- (void)didRewardAdWithAdInfo:(LPMAdInfo *)adInfo reward:(LPMReward *)reward {// Implement logic to grant the reward to the userNSString *name = reward.name; NSInteger *amount = reward.amount;}

Full Implementation Example of Rewarded Ads

NS_ASSUME_NONNULL_BEGIN@interface RewardedAdViewController () <LPMRewardedAdDelegate>@property(nonatomic, strong) LPMRewardedAd *RewardedAd;@end@implementation RewardedAdViewController- (void)createRewardedAd {self.rewardedAd = [[LPMRewardedAd alloc] initWithAdUnitId:@"adUnitId"];self.rewardedAd.delegate = self;}- (void)loadRewardedAd {// used to load or reload the ad[self.rewardedAd loadAd];}- (void)showRewardedAd {if ([self.rewardedAd isAdReady]) {   [self.rewardedAd showAdWithViewController:self placementName:NULL];}}- (void)showRewardedAdWithPlacementName:(NSString *)placementName {// check that ad is ready and that the placement is not capped if ([self.rewardedAd isAdReady] && ![LPMRewardedAd isPlacementCapped:placementName]) {   [self.rewardedAd showAdWithViewController:self placementName:placementName];}}#pragma mark - LPMRewardedAdDelegate Methods- (void)didLoadAdWithAdInfo:(LPMAdInfo *)adInfo {}- (void)didFailToLoadAdWithAdUnitId:(NSString *)adUnitId error:(NSError *)error {}- (void)didChangeAdInfo:(LPMAdInfo *)adInfo {}- (void)didDisplayAdWithAdInfo:(LPMAdInfo *)adInfo {}- (void)didFailToDisplayAdWithAdInfo:(LPMAdInfo *)adInfo error:(NSError *)error {}- (void)didClickAdWithAdInfo:(LPMAdInfo *)adInfo {}- (void)didCloseAdWithAdInfo:(LPMAdInfo *)adInfo {}- (void)didRewardAdWithAdInfo:(LPMAdInfo *)adInfo reward:(LPMReward *)reward {} @endNS_ASSUME_NONNULL_END

LevelPlay Mediation Demo App

The Integration Demo application demonstrates how to integrate Rewarded Ad Unit APIs in your app. Download iOS 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: