Rewarded ads integration for React Native
Integrate rewarded video ads in your React Native app by initializing the SDK, creating ad units, and setting up event listeners to handle ad lifecycle events.
Read time 5 minutesLast updated a day ago
Note
This documentation is relevant for SDK 8.7.0+.
Prerequisites
- Ensure that you have correctly integrated the React Native Plugin into your app. Integration is outlined here.
- Ensure that you initialize the SDK using LevelPlay Initialization API.
- Find the AdUnitID in LevelPlay dashboard.
Create Rewarded and Register to Events
After you receive the onInitSuccess callback, you can create an ad unit using the relevant Ad Unit ID, as defined in the LevelPlay platform (Initializing the LevelPlay SDK step). Set the rewarded listener for the rewarded ad unit created, to get informed of ad delivery.const [rewardedAd, setRewardedAd] = useState < LevelPlayRewardedAd > (new LevelPlayRewardedAd([YOUR_AD_UNIT]))useEffect(() => { const listener: LevelPlayRewardedAdListener = { onAdLoaded: (adInfo: LevelPlayAdInfo) => { // Provided when the ad is successfully loaded }, onAdLoadFailed: (error: LevelPlayAdError) => { // Provided when the ad fails to load. Ad Unit information is included }, onAdInfoChanged: (adInfo: LevelPlayAdInfo) => { // Provided when the ad info is updated. Available when another ad has loaded, and includes a higher CPM/Rate }, onAdDisplayed: (adInfo: LevelPlayAdInfo) => { // Provided when the ad is displayed }, onAdDisplayFailed: (error: LevelPlayAdError, adInfo: LevelPlayAdInfo) => { // Provided when the ad fails to be displayed }, onAdClicked: (adInfo: LevelPlayAdInfo) => { // Provided when the user clicks on the ad }, onAdClosed: (adInfo: LevelPlayAdInfo) => { // Provided when the ad is closed }, onAdRewarded: (reward: LevelPlayReward, adInfo: LevelPlayInfo) => { // Provided when the ad is rewarded. Ad Unit info and the reward info are included. } }; rewardedAd.setListener([YOUR_LISTENER]);}, [rewardedAd]);
LevelPlay Rewarded Ad Callbacks
onAdLoaded – Provided when the ad is successfully loaded onAdLoadFailed – Provided when the ad fails to load. Ad Unit information is included onAdDisplayed – Provided when the ad is displayed. This is equivalent to an impression onAdDisplayFailed (optional) – Provided when the ad fails to be displayed onAdRewarded – Provided when the ad is rewarded. Ad Unit info and the reward info are included. onAdClicked (optional) – Provided when the user clicks on the ad onAdClosed – Provided when the ad is closed onAdInfoChanged (optional) – Provided when the ad info is updated. Available when another ad has loaded, and includes a higher CPM/RateGet 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.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.
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
After you receive the onInitSuccess callback, you are ready to load an rewarded ad. This should be done using the method:rewardedAd.loadAd();
Show Rewarded Ad
You can show an rewarded ad after you receive onAdLoaded callback, using the showAd APIs. If you are using placements, share their name as part of the API, as shown below.// Show ad without placementrewardedAd.showAd();// Show ad with placementrewardedAd.showAd([YOUR_PLACEMENT]);
Check ad 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.After the ad was displayed successfully to the player, you can load another ad, repeating the Load Rewarded Ad step. You do not need to create a new ad entity when loading a single ad at a time.// Check that ad is ready and that the placement is not capped if(rewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped([YOUR_PLACEMENT])) { rewardedAd.showAd([YOUR_PLACEMENT]);}
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.onAdRewarded: (reward: LevelPlayReward, adInfo: LevelPlayInfo) => { // Provided when the ad is rewarded. Ad Unit info and the reward info are included}
Multiple Ad Unit Rewarded APIs
Legacy | Ad Unit (new) | |
|---|---|---|
| Class | IronSource | LevelPlayRewardedAd |
| API | loadRewardedVideo | loadAd |
| showRewardedVideo | showAd | |
| isRewardedVideoPlacementCapped | isPlacementCapped | |
| isRewardedVideoAvailable | isAdReady | |
| placement.getRewardName | reward.name | |
| placement.getRewardAmount | reward.amount |
Full Implementation Example of Rewarded Ad
const [rewardedAd, setRewardedAd] = useState < LevelPlayRewardedAd > (new LevelPlayRewardedAd('YOUR_AD_UNIT_ID'))const listener: LevelPlayRewardedAdListener = { onAdLoaded: (adInfo: LevelPlayAdInfo) => { // Implement your logic here, for example showing the ad rewardedAd.showAd() }, onAdLoadFailed: (error: LevelPlayAdError) => { // Implement your logic here... }, onAdInfoChanged: (adInfo: LevelPlayAdInfo) => { // Implement your logic here... }, onAdDisplayed: (adInfo: LevelPlayAdInfo) => { // Implement your logic here... }, onAdDisplayFailed: (error: LevelPlayAdError, adInfo: LevelPlayAdInfo) => { // Implement your logic here... }, onAdClicked: (adInfo: LevelPlayAdInfo) => { // Implement your logic here... }, onAdClosed: (adInfo: LevelPlayAdInfo) => { // Implement your logic here... }, onAdRewarded: (reward: LevelPlayReward, adInfo: LevelPlayAdInfo) => { // Implement your logic here... }};useEffect(() => { rewardedAd.setListener(listener) rewardedAd.loadAd()}, []);// Rest of component ...// End of component ...