Rewarded Ads

Setting up rewards on an ad unit allows you to directly monetize your ad unit in return for granting a currency to the user. Your users are rewarded the currency of your choice for seeing a video ad. When you set up a reward, you choose your conversion rate.

The reward for seeing a video can be supported by server-side or client-side rewarded integration. For example:

  • In a server-side rewarded integration, Yahoo sends the server-side callback to your server as the user completes seeing the video.
  • In a client-side rewarded integration, Yahoo only serves the video. Your app is responsible for informing the user of the amount of the reward.

An Integration Use Case

One of the most popular integrations is in the storefront area of an app. In a storefront, users can generally purchase goods, get virtual currency and discover opportunities to earn free currency or goods. Typically, you create a button within your app in the storefront area, like Click here for free points, that launches the video ad.

Client-Side Rewarded Ads

Yahoo enables the setup of the Client-side rewards system without requiring you to integrate your app with the server-side callbacks.

You can serve client-side rewarded videos into Full Screen ad spaces where users are offered a reward for watching a video. The highlights of this setup are:

  • Users are rewarded for watching videos.
  • The app notifies the user and presents the reward to the user in the app.
  • The app determines the amount of reward; the amount of reward cannot be changed on the Yahoo server side.

Configure a Client-side Rewarded Ad Space

Follow these steps:

  1. After you log in to the developer portal at http://y.flurry.com and navigate to the App Publishing tab, select Applications & Ad Units from the left navigation bar.
  2. Click +New Ad Unit.
  3. Give your ad unit a name, select the application it will appear in, and select Type Rewarded
  4. Select Reward Delivery Client-side.

You can now save your ad unit.

Important

Look for a green success banner at the top of this page to ensure your ad unit has successfully saved. Should it not save correctly, you will not be able to retrieve ads later on. Clicking “save” again should resolve this issue.

client-side rewarded ad space

Deliver Client-side Rewards in Your App

For ad units that are configured as Client-side rewarded, the Flurry SDK triggers the onVideoCompleted listener callback for Android and the adInterstitialVideoDidFinish delegate callback for iOS, as the user completes seeing the video.

You’ll need to provide the code in these callbacks that rewards the user for seeing the complete video. Details on code integration are provided below.

Add Android Code

In addition to the Android fetchAd / displayAd code documented here, pay attention to the onVideoCompleted(FlurryAdInterstitial adInterstitial) method of the FlurryAdInterstitialListener.

When this listener method is triggered, it indicates the user has completed watching the video and has earned the reward.

Add iOS Code

Pay attention to the adInterstitialVideoDidFinish:(FlurryAdInterstitial*)interstitialAd method of the FlurryAdInterstitialDelegate.

When this method is triggered, it indicates the user has completed the video watching and has earned the reward. The amount of this reward is the same for each user and each video watched.

Server-Side Rewarded Ads

Yahoo enables the setup of the Server-side rewards system where Yahoo sends the server-side callbacks as the user completes seeing the ad.

You can serve server-side rewarded videos into Full Screen ad spaces where users are offered a reward for watching a video.

To serve Flurry’s rewarded ads, you perform the following required tasks:

  1. Configure your rewarded ad space.
  2. Define your rewards.
  3. Configure callbacks.
  4. Enable callback security.
  5. Match rewards to users (in the app code).

Configure a Server-side Rewarded Ad Space

Follow these steps:

  1. After you log in to the developer portal at http://y.flurry.com and navigate to the App Publishing tab, select Applications & Ad Units from the left navigation bar.
  2. Click +New Ad Unit.
  3. Give your ad unit a name, select the application it will appear in, and select Type Rewarded.
  4. Select Reward Delivery Server-side.

You can now save your ad unit.

Important

Look for a green success banner at the top of this page to ensure your ad unit has successfully saved. Should it not save correctly, you will not be able to retrieve ads later on. Clicking “save” again should resolve this issue.

server-side rewarded ad space

For server-side Rewarded spaces, inventory can be served into interstitial-sized Ad Spaces only.

Define Your Rewards

To start, click Create Reward in the Ad Unit page or in the Application list in the Applications & Ad Units section.

Now follow these steps:

  1. Name your reward. This is the name of the virtual good or currency that you will give to your user for engaging with video. The reward name limit is 13 characters.
  2. Define the quantity/conversion rate of your reward or currency. This is the amount you’d like to credit the user for every $1 you receive from Yahoo.
  3. Define a minimum reward for each video view.
  4. Finally, paste your callback URL into the bottom field. The callback URL is the notification Flurry sends to your server with information to credit a user for converting on a rewarded ad. When you add your callback URL, be sure to format the string with key parameters for awarding your users.
  5. You may enter a test device ID (IDFA or GPAID) to send a callback test for that device. Click the “Test response” link in the callback field to test. (This link appears after you have entered a callback URL.)
  6. Click Save. Your reward will apply to all ad units within the app.

The callback is called whenever a user is granted a reward (on a conversion).

Note

Your callback server must return a 200 response whenever it is able to process the reward. If your callback server does not respond with a 200, Yahoo will continue to send the same callback at increasing intervals until your server responds with a 200 or a max retry limit is reached. Consider defining a per-user reward limit to protect from abuse.

define rewards

Callback URL Example

For an iOS app, the callback contains iOS identifiers to help identify the device that originated the callback.

For an Android app, the callback contains Android identifiers to help identify the device that originated the callback.

Enable Callback URL Security

Yahoo will add the following parameters to the end of the callback URL automatically:

  • fguid - a unique identifier for the action to be rewarded
  • rewardquantity - an integer denoting the number of reward units to be granted to the user
  • fhash - an md5 hash which can be used to verify that the callback really came from Flurry and that the reward quantity is correct.

The fhash value is the following:

md5( fguid:rewardquantity:secretkey )

Here is an example using realistic-looking input:

fguid=f2dcd862-f2c7-4e61-beb3-a7e8641bc944 rewardquantity=10 secret key=865B906F71E61D1C6FAF280A5F06C9037A9AC24D

callback url=http://callback.server.com/reward.do?udid=0123456789

The URL that the Flurry service will hit in this example would be:

http://callback.server.com/reward.do?udid=0123456789&fguid=f2dcd862-f2c7-4e61-beb3-a7e8641bc944&rewardquantity=10&fhash=89e602b688ea323c2e22fe2d2e514f6f

Yahoo recommends that you verify that the fhash value equals:

md5( f2dcd862-f2c7-4e61-beb3-a7e8641bc944:10:865B906F71E61D1C6FAF280A5F06C9037A9AC24D ) which, in this case equals: 89e602b688ea323c2e22fe2d2e514f6f.

Doing so ensures that the callback really came from Yahoo because only Yahoo and you know your secret key.

Because Yahoo wants to ensure that your users get their rewards, there is a possibility that you could get the same callback URL twice for the same rewarded action. Therefore, Yahoo also recommends that you store the fguid on your end and ensure that you only give your users one reward for each unique fguid value that you receive from Flurry’s callback service. Consider defining a per-user reward limit to protect from abuse.

You can see your application’s secret key by going to the App Publishing Tab and clicking the Applications & Ad Units link in the left-hand navigation.

Note

There is a different secret key for each of your applications!

Match Rewards to Users

Once you get a rewarded callback from Yahoo, you will need to match it back up to whichever user triggered the callback. The best way to accomplish this task is to instantiate the FlurryAdTargeting object and assign it the key/value cookie pair in your app that can be used to identify the user who completed watching the video. These key/value pairs will automatically be added to the callback URL.

In the above example, user\_id=1234 will be appended to your callback URL. You can use this to identify and reward that user’s account. If you rely on FlurryAdTargeting to set user cookies, ensure that it is declared before any type of rewarded ads are displayed.

On Android to match users to their rewards, similarly you call the setUserCookies method on the FlurryAdTargeting object.