Rewarded Video

This page explains how to use the Smart Display SDK to display a rewarded video in your application.

A rewarded video is an interstitial format that will display a video, then an HTML end card. The user can get a reward if he watches the video until the end.

Overview
Configuring the SDK
Creating a placement
Loading a rewarded video using a manager
Showing a rewarded video
Retrieving the reward
Disposing of a rewarded video manager

Overview

Rewarded videos are loaded and displayed using a SASRewardedVideoManager instance.

To load and display an ad using a rewarded video manager, you will need:

An fully configured Smart Display SDK.
An instance of SASAdPlacement that will be used to perform ad calls to the delivery engine.
An instance of SASRewardedVideoManager to load a rewarded video ad for the specified placement and show it if it was successfully loaded.
An object implementing the SASRewardedVideoManager.RewardedVideoListener listener to monitor rewarded video ads lifecycle events.

The next sections describe the whole process necessary to load and show a rewarded video ad.

You can also refer to the samples if you need a full runnable project.

Configuring the SDK

The Smart Display SDK needs to be configured with your own site ID and base URL before making any ad calls. You will have to call the method configure() of the SASConfiguration shared instance to do so.

This method must be called at least once, as soon as possible.
Ideally call it in the onCreate() method of your Application class. For instance:


public class MyApplication extends MultiDexApplication {
  @Override
  public void onCreate() {
    super.onCreate();

    // 123456 is used as an example, be sure to use your own siteID
    SASConfiguration.getSharedInstance().configure(this, 123456);
  }


class MyApplication : MultiDexApplication() {
  @Override
  public void onCreate() {
    super.onCreate()

    // 123456 is used as an example, be sure to use your own siteID
    SASConfiguration.getSharedInstance().configure(this, 123456)
  }

Any subsequent valid call to the configure() method will update the current configuration with the newly supplied parameters.

Note: Any ad call performed before calling the configure() method will fail by throwing a IllegalStateException.

Creating a placement

You will need an ad placement to perform an ad call. A placement identifies a part of your inventory where you want to display ads.

Creating an ad placement is done by instantiating a SASAdPlacement object using mandatory parameters site ID, page ID, format ID and an optional keyword targeting String that and can be null (more info in the API documentation).


  SASAdPlacement adPlacement = new SASAdPlacement(SOME_SITE_ID, SOME_PAGE_ID, SOME_FORMAT_ID, SOME_KEYWORD_TARGETING);


  val adPlacement = SASAdPlacement(SOME_SITE_ID, SOME_PAGE_ID, SOME_FORMAT_ID, SOME_KEYWORD_TARGETING)

Note that for testing purposes, it is possible to instantiate a generic ad placement that will always deliver an ad from a particular type. This is done by using one of the constants of the SASAdPlacement class.

Warning: Don't forget to remove any test placement before releasing your app.

Loading a rewarded video ad using a manager

Rewarded video ads are loaded and displayed using a rewarded video manager

The rewarded video manager is attached to a unique placement object passed at instantiation time.

The separation of the load and show steps implies setting a SASRewardedVideoManager.RewardedVideoListener on the SASRewardedVideoManager instance is mandatory (similar to interstitial integration).

To load a rewarded video, start by creating a new SASRewardedVideoManager instance using the ad placement defined earlier and an Object implementing the SASRewardedVideoManager.RewardedVideoListener interface:


SASRewardedVideoManager mRewardedVideoManager = new SASRewardedVideoManager(this, mRewardedVideoPlacement);

SASRewardedVideoManager.RewardedVideoListener mRewardedVideoListener = new SASRewardedVideoManager.RewardedVideoListener() {
  @Override
  public void onRewardedVideoAdLoaded(SASRewardedVideoManager rewardedVideoManager, SASAdElement adElement) {
    Log.i(RewardedVideoActivity.TAG, "RewardedVideo Ad loading completed.");
  }

  @Override
  public void onRewardedVideoAdFailedToLoad(SASRewardedVideoManager rewardedVideoManager, Exception exception) {
    Log.i(RewardedVideoActivity.TAG, "RewardedVideo Ad loading failed with exception: " + exception.getLocalizedMessage());
  }

  @Override
  public void onRewardedVideoAdShown(SASRewardedVideoManager rewardedVideoManager) {
    Log.i(TAG, "RewardedVideo ad is shown.");
  }

  @Override
  public void onRewardedVideoAdFailedToShow(SASRewardedVideoManager rewardedVideoManager, Exception exception) {
    Log.i(RewardedVideoActivity.TAG, "RewardedVideo playback failed with exception: " + exception.getLocalizedMessage());
  }

  @Override
  public void onRewardedVideoAdClosed(SASRewardedVideoManager rewardedVideoManager) {
    Log.i(RewardedVideoActivity.TAG, "RewardedVideo closed.");
  }

  @Override
  public void onRewardReceived(SASRewardedVideoManager rewardedVideoManager, SASReward reward) {
    if (reward != null) {
      Log.i(RewardedVideoActivity.TAG, "User should be rewarded with: " + reward.getAmount() + " " + reward.getCurrency() + ".");
    }
  }

  @Override
  public void onRewardedVideoAdClicked(SASRewardedVideoManager rewardedVideoManager) {
    Log.i(RewardedVideoActivity.TAG, "RewardedVideo clicked.");
  }

  @Override
  public void onRewardedVideoEvent(SASRewardedVideoManager rewardedVideoManager, int videoEvent) {
    Log.i(RewardedVideoActivity.TAG, "RewardedVideo did send event: " + videoEvent);
  }

  @Override
  public void onRewardedVideoEndCardDisplayed(SASRewardedVideoManager rewardedVideoManager, ViewGroup endCardView) {
    Log.i(RewardedVideoActivity.TAG, "RewardedVideo HTML EndCard displayed.");
  }
};

rewardedVideoManager.setRewardedVideoListener(mRewardedVideoListener);


private val rewardedVideoManager by lazy {
  SASRewardedVideoManager(this, SASAdPlacement(SOME_SITE_ID, SOME_PAGE_ID, SOME_FORMAT_ID, SOME_KEYWORD_TARGETING))
}

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  setContentView(R.layout.activity)

  // Setup rewarded video manager listener
  rewardedVideoManager.rewardedVideoListener =
    object : SASRewardedVideoManager.RewardedVideoListener {
      override fun onRewardedVideoAdLoaded(rewardedVideoManager: SASRewardedVideoManager?, adElement: SASAdElement?) {
        Log.i("Sample", "Rewarded video ad loading completed.")
      }

      override fun onRewardedVideoAdFailedToLoad(rewardedVideoManager: SASRewardedVideoManager?, e: Exception?) {
        Log.i("Sample", "Rewarded video failed to load: $e.")
      }

      override fun onRewardedVideoAdShown(rewardedVideoManager: SASRewardedVideoManager?) {
        Log.i("Sample", "Rewarded video was shown.")
      }

      override fun onRewardedVideoAdFailedToShow(rewardedVideoManager: SASRewardedVideoManager?, e: Exception?) {
        Log.i("Sample", "Rewarded video failed to show: $e.")
            }

      override fun onRewardedVideoAdClicked(rewardedVideoManager: SASRewardedVideoManager?) {
        Log.i("Sample", "Rewarded video was clicked.")
      }

      override fun onRewardedVideoAdClosed(rewardedVideoManager: SASRewardedVideoManager?) {
        Log.i("Sample", "Rewarded video was closed.")
      }

      override fun onRewardReceived(rewardedVideoManager: SASRewardedVideoManager?, reward: SASReward?) {
        if (reward != null) {
          Log.i("Sample", "Rewarded collected a reward. User should be rewarded with: ${reward.amount} ${reward.currency}.")
        }
      }

      override fun onRewardedVideoEvent(rewardedVideoManager: SASRewardedVideoManager?, event: Int) {
        Log.i("Sample", "Video event $event was triggered on RewardedVideo.")
      }

      override fun onRewardedVideoEndCardDisplayed(rewardedVideoManager: SASRewardedVideoManager?, viewGroup: ViewGroup?) {
        Log.i("Sample", "Rewarde video HTML EndCard was displayed.")
      }
   }
}

There are methods of the listener interface that you can leave empty, but you should at least implement the two methods onRewardedVideoAdLoaded and onRewardedVideoAdFailedToLoad used to check if a rewarded video ad has been loaded or if it has failed to load.

This will notify you if the interstitial can be shown or if you need to try another load ad call.

Finally, to actually trigger the rewarded video ad loading process, call the loadRewardedVideo() method of the SASRewardedVideoManager:


rewardedVideoManager.loadRewardedVideo();


rewardedVideoManager.loadRewardedVideo()

Note 1: the loadRewardedVideo() method of the SASRewardedVideoManager executes the ad loading task asynchronously in a different thread from the calling thread. Therefore, if the loadRewardedVideo() method is called while a previous ad call is being performed and has not finished yet, it will fail with a SASPendingRequestException in the onRewardedVideoAdFailedToLoad() method of the SASRewardedVideoManager.RewardedVideoListener.

Note 2: a consequence of the ad call being performed on a thread different from the main thread (also known as UI thread) is that the onRewardedVideoAdLoaded() and onRewardedVideoAdFailedToLoad() methods of the SASRewardedVideoManager.RewardedVideoListener are NOT executed from the main thread. Any code in these methods that needs to be run from the main thread MUST be wrapped in a Runnable object which will be executed on the main thread. This can be done using a Handler on the main Thread.


Handler mainLooperHandler = new Handler(Looper.getMainLooper());
mainLooperHandler.post(new Runnable() {
  @Override
  public void run() {
    // execute you UI sensitive code here
  }
});


  Handler(Looper.getMainLooper()).post {
  // execute you UI sensitive code here
}

Showing a rewarded video

When the rewarded video manager has loaded an ad successfully, you can show it when needed using the showRewardedVideo() method.

It is also possible to check the current status of a rewarded video manager at any time using the adStatus property.


SASAdStatus adStatus = mRewardedVideoManager.getAdStatus();
if (adStatus == SASAdStatus.READY) {
  mRewardedVideoManager.showRewardedVideo();
} else if (adStatus == SASAdStatus.NOT_AVAILABLE || adStatus == SASAdStatus.EXPIRED) {
  // The rewarded video isn't ready or is maybe expired
}


val adStatus: SASAdStatus = rewardedVideoManager.adStatus
if (adStatus == SASAdStatus.READY) {
  rewardedVideoManager.showRewardedVideo()
} else if (adStatus == SASAdStatus.NOT_AVAILABLE || adStatus == SASAdStatus.EXPIRED) {
  // The rewarded video isn't ready or is maybe expired
}

Note that the showRewardedVideo() method can fail and trigger the SASRewardedVideoManager.RewardedVideoListener onRewardedVideoAdFailedToShow() method, providing details about the error in the Exception parameter.

When a rewarded video ad has been shown, it is discarded and a new one must be loaded again (the same rewarded video manager should be reused if the ad placement does not change).

Retrieving the reward

When a user watches a rewarded video until the end, he might get an associated reward (depending on the ad programming) .

You should implement the onRewardReceived() method of the SASRewardedVideoManager.RewardedVideoListener interface to retrieve this reward:


@Override
public void onRewardReceived(SASRewardedVideoManager rewardedVideoManager, SASReward reward) {
  if (reward != null) {
    // Here you should reward your user with the amount of the given currency
  }
}


override fun onRewardReceived(rewardedVideoManager: SASRewardedVideoManager?, reward: SASReward?) {
  if (reward != null) {
    // Here you should reward your user with the amount of the given currency
  }
}

Disposing of a rewarded video manager

Once you are done using a rewarded video manager, typically when its hosting Activity is being destroyed, you should call the onDestroy() method of the SASRewardedVideoManager to release the resources it was using.


/**
 * Overriden from Activity class
 */
@Override
protected void onDestroy() {
  mRewardedVideoManager.onDestroy();
  super.onDestroy();
}


override fun onDestroy() {
  rewardedVideoManager.rewardedVideoListener = null
  rewardedVideoManager.onDestroy()
  super.onDestroy()
}