Rewarded Ads

Rewarded ads are full-screen video ads that reward users for watching.

1. Adding a Rewarded Ad

Step 1: Creating a Rewarded Ad Object

Create a RewardAd object. The sample code is as follows:

public class RewardedVideoActivity extends Activity {
    // Test ad slot ID
    private static final String AD_ID = "testx9dtjwj8hp";
    private RewardAd rewardAd;
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_rewarded);
        // Create a reward ad object.
        createRewardAd();
    }
    private void createRewardAd() {
        rewardAd = new RewardAd(this, AD_ID);
    }
}

Step 2: Loading an Ad

Call the loadAd() method of the RewardAd object to load an ad. The sample code is as follows:

/**
  * Load a rewarded ad.
  */
 private void loadRewardAd() {
     if (rewardAd == null) {
         rewardAd = new RewardAd(this, AD_ID);
     }
     RewardAdLoadListener listener= new RewardAdLoadListener() {
         @Override
         public void onRewardedLoaded() {
             // Rewarded ad loaded successfully.
         }
         @Override
         public void onRewardAdFailedToLoad(int errorCode) {
             // Failed to load the rewarded ad.
         }
     };
     rewardAd.loadAd(new AdParam.Builder().build(), listener);
}

For details about the methods, please refer to RewardAdLoadListener in the API Reference.

Step 3: Displaying an Ad

Call the isLoaded() method to confirm that an ad has finished loading, and call the show() method of the RewardAd object to display the ad.

The sample code is as follows:

/**
  *  Display a rewarded ad.
  */
private void rewardAdShow() {
     if (rewardAd.isLoaded()) {
         rewardAd.show(RewardedVideoActivity.this, new RewardAdStatusListener() {
             @Override
             public void onRewardAdOpened() {
                 // Rewarded ad opened.
             }
             @Override
             public void onRewardAdFailedToShow(int errorCode) {
                 // Failed to display the rewarded ad.
             }
             @Override
             public void onRewardAdClosed() {
                 // Rewarded ad closed.
             }
             @Override
             public void onRewarded(Reward reward){
                 // Reward earned by user.
                 // TODO Reward the user.
             }
         });
     }
 }

Note:

If the reward information has been configured for the ad slot, the reward object is passed in the onRewarded method. Call the reward.getAmount() method to obtain the reward amount and the reward.getName() method to obtain the name of the reward. It is recommended that the reward be granted immediately and verification be implemented on the server side to determine whether the reward is valid. If no reward information is configured, grant rewards based on the actual scenario.

2. Testing a Rewarded Ad

When testing rewarded ads, use the dedicated test ad slot ID to obtain test ads. This avoids invalid ad clicks during the test. The test ad slot ID is used only for function commissioning. Before releasing your app, apply for a formal ad slot ID and replace the test ad slot ID with the formal one.

The following table lists the dedicated ad slot ID for rewarded ad testing.

Ad Format	Display Form	Test Ad Slot ID
Rewarded	Video	testx9dtjwj8hp

You can download the sample code for rewarded ads and execute the code. The following screen will be displayed.

3. Validating Server-Side Verification CallBacks

Server-side verification callbacks refer to the URL requests, with specified query parameters, that are sent by HUAWEI Ads to notify a media server that a user needs to be rewarded for interacting with a rewarded video ad. These callbacks provide protection against spoofing.

Rewarding a User

1. You need to balance user experience and reward validation when deciding when to reward a user. There may be delays if you use server-side callbacks. You are advised to reward the user immediately using a client-side callback and validate all rewards when receiving server-side callbacks. This approach ensures the validity of granted rewards while providing a good user experience.

2. For some apps where reward validity is very important, delays in granting rewards are acceptable. In this case, you can wait for the server-side verification callback before rewarding users.

Validating Server-Side Verification CallBacks

Step 1: Configure reward information for a rewarded ad.

When applying for a rewarded video ad slot on the Publisher Console, enable reward settings, set the reward item, reward amount, and URL for server-side verification. The following figure shows the reward settings.

Step 2: (Optional) Set data and userId.

Set data and userId for a rewarded ad object.

RewardAd rewardAd = new RewardAd(RewardActivity.this, getString(R.string.ad_id_reward));
RewardVerifyConfig config = new RewardVerifyConfig.Builder().setData("CUSTOM_DATA")
  .setUserId("1234567")
  .build();
rewardAd.setRewardVerifyConfig(config);
...
rewardAd.loadAd(new AdParam.Builder().build(), rewardAdLoadListener);

Note:

If data and userId are not set, reward grant events can still be reported, but the two parameters will not be present in the server-side callback. If you want to set data and userId, set them before showing the ad and ensure that each parameter value after URLEncode does not exceed 1024 characters. Otherwise, the server-side verification will be affected.

Step 3: Obtain the content to be verified.

After a user watches a rewarded ad, the HUAWEI Ads server sends the parameters to be verified as well as keyId and sign to https://www.example.com/feedback (the verification URL configured in Step 1).

Request Body:

{
  "adId" : "testx9dtjwj8hp",
  "data" : "CUSTOM_DATA",
  "keyId" : "12345678",
  "rewardAmount" : "10",
  "rewardName" : "Gold Coin",
  "sign" : "OA33u6mypnhE4hbmF32N/ibYi1uXt72nDDyYMwjDI6JXVVFKePZYo4F7Fuk2MaG......",
  "uniqueId" : "3361626337333932313435313430373438383561376265636130393939313166",
  "userId" : "1234567"
}

The following table describes the parameters.

Parameter	Type	Mandatory	Description
adId	string	Yes	Ad slot ID of the rewarded video.
data	String	No	Custom data string.
keyId	String	Yes	Key used to verify callbacks.
rewardAmount	String	No	Reward amount.
rewardName	String	No	Reward item.
sign	String	Yes	Callback signature.
uniqueId	String	Yes	Unique hexadecimal identifier generated for each reward grant event.
userId	String	No	User ID.

Step 4: Encapsulate the content to be verified.

The format of content to be verified (excluding sign and keyId) is as follows:

adId={adId}&data={data}&rewardAmount={rewardAmount}&rewardName={rewardName}&uniqueId={uniqueId}&userId={userId}

In the format, {} enclose parameter values and the parameter sequence cannot be changed. If a parameter is null or left empty, do not add it to the URL. Then, use SHA-256 to calculate a hash value for paramContentData.

The sample code is as follows:

String adId = request.getParameter("adId");
String data = request.getParameter("data");
...
String userId = request.getParameter("userId");
String param = "adId=" + adId + "&data=" + data + "&rewardAmount=" + rewardAmount + "&rewardName=" + rewardName + "&uniqueId=" + uniqueId + "&userId=" + userId;
String sha256Value = Sha256Util.digest(param);
byte[] paramContentData = sha256Value.getBytes(Charset.forName("UTF-8"));

Step 5: Obtain the public key list.

Obtain the public key list provided by Huawei using the following URL:

https://ppscrowd-dre.op.dbankcloud.com/action-lib-track/publickeys

Response body:

{  
  "keys": [    
    {     
      "keyId":"12345678",     
      "publicKey":"LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS1cbk1GLi4uc3c9PVxkQgUFVCTElt"    
    },   
    {     
      "keyId":"22345678",                
      "publicKey":"LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS1cbk1GLi4uc3c9PVxkQgUFVCTElt"    
    }   
  ]
}

Response structure:

Parameter	Type	Mandatory	Description
Keys	List<key>	Yes	Public key list.

Key structure:

Parameter	Type	Mandatory	Description
keyId	String	Yes	Secret key ID.
publicKey	String	Yes	Public key.

The sample code is as follows:

String data = "";
String url = "https://ppscrowd-dre.op.dbankcloud.com/action-lib-track/publickeys";
HttpClient httpclient = new DefaultHttpClient();
HttpGet request = new HttpGet();
try {
    request.setURI(new URI(url));
    HttpResponse response = httpclient.execute(request);
    data = EntityUtils.toString(response.getEntity());
} catch (Exception e) {
    logger.error(e.getMessage());
}

Step 6: Perform verification.

1. Use keyId to find the Base64-encoded public key from the public key list.

2. Use paramContentData, publicKey, and sign as the input parameters of the SHA256withRSA digital signature algorithm to perform verification.

The sample code is as follows:

public static boolean verify(byte[] data, String publicKey, String sign, String signatureAlgorithm) {
    try {
        byte[] keyBytes = base64Decode(publicKey);
        X509EncodedKeySpec keySpec = new X509EncodedKeySpec(keyBytes);
        KeyFactory keyFactory = KeyFactory.getInstance("RSA");
        PublicKey publicK = keyFactory.generatePublic(keySpec);
        Signature signature = Signature.getInstance(signatureAlgorithm);
        signature.initVerify(publicK);
        signature.update(data);
        return signature.verify(base64Decode(sign));
    } catch (InvalidKeyException | SignatureException | UnsupportedEncodingException | InvalidKeySpecException | NoSuchAlgorithmException e) {
        logger.error("verify error:", e);
        return false;
    }
}
private static byte[] base64Decode(String encoded) throws UnsupportedEncodingException {
    return Base64.decodeBase64(encoded.getBytes("UTF-8"));
}