文档

支持

LevelPlay SDK - Flutter

Unity

Android

iOS

Adobe Air

Flutter

React Native

LevelPlay SDK - Flutter

Rewarded ads integration for Flutter

Integrate Rewarded Video ads into your Flutter application, utilizing ad placements, capping, pacing, and manual loading options for optimized user engagement.
阅读时间5 分钟最后更新于 7 天前

Prerequisites

  • Ensure that you integrate the Flutter Plug-in into your app.
  • 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 ironSource SDK step). Set the rewarded listener for the rewarded ad unit created, to get informed of ad delivery. 
final LevelPlayRewardedAd _rewardedAd = LevelPlayRewardedAd(adUnitId: [YOUR_AD_UNIT_ID]);@overridevoid initState() {    super.initState();    _rewardedAd.setListener(this);}// LevelPlayRewardedAdListener methods@overridevoid onAdLoaded(LevelPlayAdInfo adInfo) {}@overridevoid onAdLoadFailed(LevelPlayAdError error) {} @overridevoid onAdDisplayed(LevelPlayAdInfo adInfo) {}@overridevoid onAdDisplayFailed(LevelPlayAdError error, LevelPlayAdInfo adInfo) {}@override void onAdClosed(LevelPlayAdInfo adInfo) {}@overridevoid onAdClicked(LevelPlayAdInfo adInfo) {} @overridevoid onAdInfoChanged(LevelPlayAdInfo adInfo) {}@overridevoid onAdRewarded(LevelPlayReward reward, LevelPlayAdInfo adInfo) {}

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/Rate

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. 
  • placementName
    : The 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.

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 a rewarded ad. This should be done using the method: 
_rewardedAd.loadAd();

Show Rewarded Ad

You can show a 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 placement_rewardedAd.showAd();// Show ad with placement_rewardedAd.showAd(placement: [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 loads successfully and ad unit isn't capped, or false otherwise.
  • isPlacementCapped
    : Returns true when a valid placement is capped. If the placement isn't valid, or not capped, this API will return false.
// Check that ad is ready and that the placement is not capped if(_rewardedAd.isAdReady() && !LevelPlayRewardedAd.isPlacementCapped([YOUR_PLACEMENT])) {     _rewardedAd.showAd(placement:[YOUR_PLACEMENT]);}
After the ad was displayed successfully to the player, you can load another ad, repeating the Load Rewarded Ad step. You don't need to create a new ad entity when loading a single ad at a time.

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 1 to 64 alphanumeric characters.
  • You will receive a 
    dynamicUserId
    parameter in the callback URL with the reward details.
LevelPlay.setDynamicUserId("userId");

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
. 
@overridevoid onAdRewarded(LevelPlayReward reward, LevelPlayAdInfo adInfo) {    // Implement logic to grant the reward to the user}

Multiple Ad Unit Rewarded APIs

Category

Legacy

Ad Unit (new)

Class
IronSource
LevelPlayRewardedAd
API
loadRewardedVideo
loadAd
API
showRewardedVideo
showAd
API
isRewardedVideoPlacementCapped
isPlacementCapped
API
isRewardedVideoAvailable
isAdReady
API
placement.getRewardName
reward.name
API
placement.getRewardAmount
reward.amount

Full Implementation Example of Rewarded Ad

final LevelPlayRewardedAd _rewardedAd = LevelPlayRewardedAd(adUnitId: 'YOUR_AD_UNIT_ID');@overridevoid initState() {    super.initState();    _rewardedAd.setListener(this);    _rewardedAd.loadAd();}@overridevoid onAdRewarded(LevelPlayReward reward, LevelPlayAdInfo adInfo) {    // Implement your logic here...}@overridevoid onAdClicked(LevelPlayAdInfo adInfo) {    // Implement your logic here...}@overridevoid onAdClosed(LevelPlayAdInfo adInfo) {    // Implement your logic here...}@overridevoid onAdDisplayFailed(LevelPlayAdError error, LevelPlayAdInfo adInfo) {    // Implement your logic here...}@overridevoid onAdDisplayed(LevelPlayAdInfo adInfo) {    // Implement your logic here...}@overridevoid onAdInfoChanged(LevelPlayAdInfo adInfo) {    // Implement your logic here...}@overridevoid onAdLoadFailed(LevelPlayAdError error) {    // Implement your logic here...}@overridevoid onAdLoaded(LevelPlayAdInfo adInfo) {    // Implement your logic here, for example showing the ad    _rewardedAd.showAd();}// Rest of the widget// End of widget...