HarmonyOS 鸿蒙Next 打造开放、合规的广告生态 - 激励广告

HarmonyOS 鸿蒙Next 打造开放、合规的广告生态 - 激励广告 场景介绍

激励广告是一种全屏幕的视频广告，用户可以选择点击观看，以换取相应奖励。

接口说明

开发步骤

1. 获取OAID。

   如果想要为用户更精准的推送广告，可以在请求参数AdRequestParams中添加oaid属性。

   如何获取OAID参见获取OAID信息。

   说明 使用以下示例中提供的测试广告位必须先获取OAID信息。

2. 请求单广告位广告。

   需要先创建一个AdLoader对象，通过AdLoader的loadAd方法请求广告，最后通过AdLoadListener，来监听广告的加载状态。

   请求广告关键参数如下所示：

1. 事件订阅。

   开发者需要在App中订阅com.huawei.hms.pps.action.PPS_REWARD_STATUS_CHANGED事件来监听激励广告页面变化并接收奖励信息。示例代码中的订阅方法registerPPSReceiver()需要在每次展示广告前调用 。

   在订阅到公共事件后，可以从CommonEventData的parameters参数中使用"reward_ad_status"作为key值获取激励广告页面变化状态，使用"reward_ad_data"作为key值获取奖励信息，属性rewardType用来获取奖励物品的名称，rewardAmount用来获取奖励物品的数量。

2. 展示广告。

   ads为步骤2请求到的广告信息，调用showAd方法来展示广告。

校验激励广告服务端验证回调

服务端验证回调是指鲸鸿动能平台发送给媒体服务器的网址请求，其中带有特定的查询参数，用来通知媒体服务器某位用户因为与激励视频广告互动而应予以奖励，从而规避欺骗的行为。

奖励用户

• 在给用户发奖励时，要把握好用户体验和奖励验证之间的平衡。由于服务器端回调会存在延迟的情况，因此我们建议客户端立即奖励用户，同时在收到服务器端回调时对所有奖励进行验证。这种做法可确保奖励符合发放条件，同时提供良好的用户体验。
• 对于某些应用而言，奖励是否达到发放条件非常重要，用户可适当接受延迟。这时，推荐做法是等待服务器端回调完成验证，再向用户发放奖励。

校验服务端验证回调

说明

App上架至华为应用市场（AppGallery）时间超过12小时才可以收到回调。

1. 设置激励广告的奖励配置。

   您在鲸鸿动能媒体服务平台上申请激励视频广告位时选择“媒体管理（点击媒体名）> 新增展示位 > 选择激励视频（点击下一步，进入编辑页面）”，设置奖励类型和奖励数量，并点击“高级设置”，设置服务器端验证的URL。如下图：

   

2. （可选）设置自定义数据customData和userId。

   您在App中展示激励广告之前设置自定义数据customData和userId。示例代码如下所示：

   如果没有设置customData和userId，不影响发放奖励事件上报但是服务端验证的参数中没有这两个字段。如果设置customData和userId，必须在展示广告之前设置并且URLEncode之后，长度不超过1024个字符，否则影响服务端验证。

3. 获取要验证的内容。

   用户观看完激励广告时，鲸鸿动能平台服务端会把需要验证的参数以及keyId和sign传给媒体提供的URL：https://www.example.com/feedback（即步骤1中配置的验证URL）。请求体样例：

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

   服务器端验证回调查询参数说明：

1. 组装验证参数

   验证内容（除sign、keyId）格式顺序如下：

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

   其中‘{}’里面表示参数的值，且参数顺序不能变。如果参数为null或者空字符串，则URL中不拼接该参数。然后用SHA256计算散列值，得到paramContentData。示例代码如下所示：

   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"));
   

2. 获取公钥列表。

   a. 在鲸鸿动能媒体服务平台上查看对应的帐户信息时选择“账户”。

   b. 您根据应用分发区域不同，需要使用对应站点的接口URL去获取公钥列表，不同站点对应的接口URL如下所示：

   • 中国：https://ppscrowd-drcn.op.hicloud.com/action-lib-track/publickeys

   将body通过密钥进行HMAC-SHA256加密得到签名，替换到Authorization中，并设置“开发者ID”和Authorization到Header中。示例代码如下所示：

   String data = "";
   String url = "https://ppscrowd-dre.op.dbankcloud.com/action-lib-track/publickeys";
   String authorization = "Digest validTime=\"{0}\", response=\"{1}\"";
   // 开发者ID
   String userId = "YOUR_PUBLISHER_ID";
   // 密钥
   String key = "YOUR_KEY";
   
   HttpClient httpclient = HttpClients.createDefault();
   HttpGet request = new HttpGet();
   try {
       // 将body通过密钥进行HMAC-SHA256加密得到签名，替换到Authorization中
       String validTime = String.valueOf(System.currentTimeMillis());
       String body = validTime + ":/publickeys";
       byte[] keyBytes = Base64.decodeBase64(key);
       byte[] bodyBytes = body.getBytes(Charsets.UTF_8);
       
       Mac mac = Mac.getInstance("HmacSHA256");
       SecretKey secretKey = new SecretKeySpec(keyBytes, "HmacSHA256");
       mac.init(secretKey);
       byte[] signatureBytes = mac.doFinal(bodyBytes);
       
       String signature = (signatureBytes == null) ? null : Hex.encodeHexString(signatureBytes);
       authorization = MessageFormat.format(authorization, validTime, signature);
       // 设置开发者ID和Authorization到Header中
       request.setURI(new URI(url));
       request.setHeader("userId", userId);
       request.setHeader("Authorization", authorization);
       HttpResponse response = httpclient.execute(request);
       data = EntityUtils.toString(response.getEntity());
   } catch (Exception e) {
       System.out.println(e.getMessage());
   }
   

   返回data消息体（publicKey已匿名化）：

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

   返回消息结构体：

key结构体：

1. 执行验证。

   a. 根据keyId从公钥列表中找到对应的base64编码后的publicKey。

   b. 将paramContentData、publicKey、sign和SHA256withRSA数字签名算法的入参，执行验证。

   示例代码如下所示：

   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) {
           return false;
       }
   }
   
   private static byte[] base64Decode(String encoded) throws UnsupportedEncodingException {
       return Base64.decodeBase64(encoded.getBytes("UTF-8"));
   }