Rewarded Video for Android

Rewarded video ads are a full screen experience where users opt-in to view a video ad in exchange for something of value, such as virtual currency, in-app items, exclusive content, and more. The ad experience is 15-30 second non-skippable and contains an end card with a call to action. Upon completion of the full video, you will receive a callback to grant the suggested reward to the user.

Below are details on how to implement rewarded video ads from Audience Network on Android.

Set up the Android SDK

The Audience Network Rewarded Video format is now included in the public SDK. Please note, that this feature is still in closed Beta.

Manual installation

Once you have downloaded the private build copy the AudienceNetwork.aar file and place it in the /libs folder in your project (you might need to create the directory if it doesn't already exist). Then add the following lines to your app's build.gradle:

repositories {
  flatDir {
    dirs 'libs'
  }
}

dependencies {
  ...
  compile(name: 'AudienceNetwork', ext: 'aar')
}
  1. If using AudienceNetwork.jar for your project, under the AudienceNetwork/bin folder, rename the AudienceNetwork.aar to AudienceNetwork.zip, extract classes.jar file and rename it to AudienceNetwork.jar, place the AudienceNetwork.jar file in the /libs folder in your project (you might need to create the directory if it doesn't already exist). Make sure your IDE's UI reflects this change. If you are using Intellij IDEA, right click on the libs/AudienceNetwork.jar file and choose 'Add as Library'.
  2. If you are not already including it, add the Android v4 Support Library (without resources) to your project, detailed steps can be found here.
Configure your Manifest

In addition, you'll also need to configure your app's manifest file as follows:

  • Declare the INTERNET and ACCESS_NETWORK_STATE permissions:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
  package="com.example.package"
  android:versionCode="1"
  android:versionName="1.0">
   ...

  <uses-permission android:name="android.permission.INTERNET"/>
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

  <application android:label="@string/app_name">
   ...
  </application>
</manifest>

Though not required, we recommend that you set up your project to work with Google Play Services as indicated here. This will enable the Audience Network SDK to fetch the Advertising ID more efficiently.

Implementation

Before starting, make sure you include the modifications to your app's manifest file as described below:

<application android:label="@string/app_name">
 ...
 <activity android:name="com.facebook.ads.AudienceNetworkActivity"
 android:configChanges="keyboardHidden|orientation|screenSize" />
</application>  

Add the following code at the top of your activity class in order to import the Facebook Ads SDK:

import com.facebook.ads.*;

Then, add a function in your Activity that initializes the rewarded video object and caches the video creative.

private RewardedVideoAd rewardedVideoAd;

private void loadRewardedVideoAd { 
 rewardedVideoAd = new RewardedVideoAd(AdSampleActivity.this.getActivity(),
 YOUR_PLACEMENT_ID);
 rewardedVideoAd.setAdListener(AdSampleActivity.this);
 rewardedVideoAd.loadAd();
}

Use the Placement ID you obtained from step 3 on the Getting Started guide.

Now that you have added the code to load the ad, declare that your activity class implements the RewardedVideoAdListener interface and implement these functions, which handle various events.

For example:

  • onAdLoaded ensures your app is aware when the ad is cached and ready to be displayed
  • onRewardedVideoCompleted lets you know when to deliver your reward to the user after a completed video view
@Override
public void onError(Ad ad, AdError error) {
 // Rewarded video ad failed to load
}

@Override
public void onAdLoaded(Ad ad) {
 // Video ad is loaded and ready to be displayed  
}

@Override
public void onAdClicked(Ad ad) {
 // Video ad clicked
}

@Override
public void onLoggingImpression(Ad ad) {
 // Rewarded Video ad impression - the event will fire when the 
 // video starts playing
}


@Override
public void onRewardedVideoCompleted() {
 // Rewarded Video View Complete - the video has been played to the end.
 // You can use this event to initialize your reward
    }

@Override
public void onRewardedVideoClosed() {
 // The Rewarded Video ad was closed - this can occur during the video
 // by closing the app, or closing the end card.
    }

Finally, when you are ready to show the rewarded video ad you can call the following code.

if (rewardedVideoAd != null || rewardedVideoAd.isAdLoaded()) {
 rewardedVideoAd.show();
} 

When running on the simulator, test ads will be shown by default. To enable test ads on a device, add the following line of code before loading an ad: AdSettings.addTestDevice(HASHED ID). Use the hashed ID that is printed to the log cat when you first make a request to load an ad on a device.

Server Side Reward Validation

Overview

If you manage your user rewards server-side, then Facebook offers a solution for carrying this out securely by using a validation technique. Our server will communicate with a specified endpoint to validate each ad impression and validate whether a reward should be granted.

  1. Audience Network SDK requests a rewarded video ad with the following parameters:
    • Audience Network Placement ID
    • Unique User ID - an attribute you use to identify a unique user. For example, a numeric identifier
    • Reward Value - the value of the reward you would like to grant the user. For example, 100Coins
  2. Upon video completion, the Facebook Server relays these values to your specified end point, together with the App Secret and a Unique Transaction ID.
  3. Upon receipt, the server validates the request and responds as follows:
    • 200 response: request is valid and the reward should be delivered
    • Non 200 response: request is not valid, and the reward should not be delivered.
  4. Once the video is complete, the end card is presented and one of the following events will fire.
    • onRewardServerSuccess - triggered only if a 200 response was received during step 3.
    • onRewardServerFailed - triggered if a non 200 response was received during step 3.

An example of the URL which will hit your publisher end point, from Facebook's server.

https://www.your_end_point.com/?token=APP_SECRET&puid=USER_ID&pc=REWARD_ID&ptid=UNIQUE_TRANSACTION_ID

Please provide your publisher end point to your Facebook representative in order to enable this feature.

SDK Implementation

After initializing the rewarded video object, you will need to pass in a User ID and Reward amount into the rewarded ad data before loading an ad. Both User ID and Reward amount are strings. For example:

private RewardedVideoAd rewardedVideoAd;

private void loadRewardedVideoAd { 
 rewardedVideoAd = new RewardedVideoAd(AdSampleActivity.this.getActivity(),
 YOUR_PLACEMENT_ID);
 rewardedVideoAd.setAdListener(AdSampleActivity.this);

 //Set the rewarded ad data
 rewardedVideoAd.setRewardData(new RewardData("YOUR_USER_ID",
 "YOUR_REWARD"));

 rewardedVideoAd.loadAd();
}

In order for your app to be notified whether the reward was validated or not, you will need to implement the S2SRewardedVideoAdListener interface. This includes all of the events noted above, as well as two additional events. The following can be used alongise the events monetioned above.

@Override
public void onRewardServerSuccess() {
 // Rewarded video ad validated
}

@Override
public void onRewardServerFailed() {
 // Rewarded video ad not validated or no response from server  
}

Please note - the server validation callbacks will only occur after the end card has been dismissed by a user. You should not deallocate the rewarded video object until after one of these callbacks.