Adding Rewarded Video Ads to your Cocos-2dx app

The Audience Network C++ SDK allows you to monetize your Cocos2d-x apps with Facebook ads. A Rewarded Video ad is a full screen ad with video content that you can show in your app. Users will be required to watch the Rewarded Video ad. After the Rewarded Video ad is finished, users will be able to earn rewards from their apps.


Let's implement the following Rewarded Video ad placement.

Step 1: Load and Show Rewarded Video Ad

Step 2: Server Side Reward Validation


Load and Show Rewarded Video Ad

Follow the Audience Network Getting Started guide and ensure you have created a Facebook app and an Audience Network placement.


Follow the Audience Network C++ SDK Getting Started guides and ensure you have successfully configured the Cocos2d-x platform and have one Cocos2d-x sample app created.

  1. Include the RewardedVidoeAd.h file in your Cocos2d-x sample app as following:
    #include "RewardedVideoAd.h"
    using namespace facebook::audience_network;
    ...
    //create an rewardedVideoAd instance using std::shared_ptr
    std::shared_ptr<facebook::audience_network::RewardedVideoAd> rewardedVideoAd = 
      std::make_shared<RewardedVideoAd>("YOUR_PLACEMENT_ID");
    Replace YOUR_PLACEMENT_ID with your own placement id string. If you don't have a placement id or don't know how to get one, refer to the Audience Network Getting Started guide.

  2. Your app needs to be set with various callbacks from the RewardedVideoAd instance.
    For example, your app needs to call the show() function after the ad is loaded. In another case, if the ad is fails to load, your app needs to log the error message. The callbacks from RewardedVideoAd are called as following:
    void adDidLoad(std::shared_ptr<RewardedVideoAd> ad) 
    {
      // Ad is loaded.
    }
    
    void adWillLogImpression(std::shared_ptr<RewardedVideoAd> ad) 
    {
      // Ad has an impression from the user.
    }
    
    void adDidClick(std::shared_ptr<RewardedVideoAd> ad) 
    {
      // Ad is clicked by the user.
    }
    
    void adWillClose(std::shared_ptr<RewardedVideoAd> ad) 
    {
      // User will close the ad.
    }
    
    void adDidClose(std::shared_ptr<RewardedVideoAd> ad)
    {
      // User has closed the ad.
    }
    
    void adRewardComplete(std::shared_ptr<RewardedVideoAd> ad) 
    {
      // User has completed a reward after watching the ad.
    }
    
    void adDidFailWithError(std::shared_ptr<RewardedVideoAd> ad, std::string error) 
    {
        // Ad is failed to load with error message.
    }
    
    rewardedVideoAd->setDidLoad(adDidLoad);
    rewardedVideoAd->setWillLogImpression(adWillLogImpression);
    rewardedVideoAd->setDidClick(adDidClick);
    rewardedVideoAd->setWillClose(adWillClose);
    rewardedVideoAd->setDidClose(adDidClose);
    rewardedVideoAd->setComplete(adRewardComplete);
    rewardedVideoAd->setDidFailWithError(adDidFailWithError);
  3. After the callbacks are set, you can call the loadAd() method to load a RewardedVideo ad.
    When the ad is loaded, you can call show() to present a RewardedVideo ad in your app.

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 from the app:

    • 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, 100 coins.
  2. Facebook server receives the Rewarded Video ad request from Audience Network SDK with the above parameter values. It will send the validation request to the publisher validation server with the request format as follows:

    • HTTP request: https://www.your_end_point.com/?token=APP_SECRET&puid=USER_ID&pc=REWARD_ID&ptid=UNIQUE_TRANSACTION_ID
    • token: client token from Settings (Advanced) in your app dashboard
    • puid: user id of the game player
    • pc: REWARD_ID which is the reward amount in currency. The format is [CURRENCY][AMOUNT]. For example, Coins100.
    • ptid: a unique transaction ID
  3. Upon receipt, the publisher server needs to send the validation response to Facebook server with following response format:

    • 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.

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



SDK Implementation

When initialising the rewarded video object, along with the Placement ID, you will need to also set a User ID, Currency Type and Reward value. User ID and Currency are both strings, whilst the Reward value is an integer. The Audience Network SDK combines the Currency and Amount into a single string before sending the request, so ensure that your end point is expecting this type of request. For example:

#include "RewardedVideoAd.h"
using namespace facebook::audience_network;
...
//create an rewardedVideoAd instance using std::shared_ptr
std::shared_ptr<facebook::audience_network::RewardedVideoAd> rewardedVideoAd = 
  std::make_shared<RewardedVideoAd>("YOUR_PLACEMENT_ID", "userid123", "coins", 100);

After rewardedVideoAd is created, you will need to set the callback method for server side validation and handle the callbacks as follows:

void adServerRewardSuccess(std::shared_ptr<RewardedVideoAd> ad) {
    //reward success and validated by server to server
}

void adServerRewardFailure(std::shared_ptr<RewardedVideoAd> ad) {
    //reward failed and validated by server to server
}
rewardedVideoAd->setServerRewardSuccess(adServerRewardSuccess);
rewardedVideoAd->setServerRewardFailure(adServerRewardFailure);

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.